Edgewall Software

Changes between Initial Version and Version 1 of TracDev/PluginDevelopment/ExtensionPoints/trac.admin.api.IAdminCommandProvider


Ignore:
Timestamp:
Jun 12, 2011, 1:27:07 PM (8 years ago)
Author:
psuter <petsuter@…>
Comment:

Legend:

Unmodified
Added
Removed
Modified
  • TracDev/PluginDevelopment/ExtensionPoints/trac.admin.api.IAdminCommandProvider

    v1 v1  
     1== Extension Point : ''IAdminCommandProvider'' ==
     2
     3||'''Interface'''||''IAdminCommandProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IAdminCommandProvider 0.12]||
     4||'''Module'''||''trac.admin''||'''Source'''||[source:trunk/trac/admin/api.py#56 api.py]||
     5
     6
     7The ''IAdminCommandProvider'' allows adding commands to the console administration interface [wiki:TracAdmin trac-admin].
     8
     9== Purpose ==
     10
     11Trac provides a command line interface for administrators to configure and customize a Trac environment. Plugins can extend this interface by providing additional commands. This allows the administration tool [wiki:TracAdmin trac-admin] to present a uniform interface with a consistent help system and command completion. It's easy to write additional commands. There is no code duplication for command parsing and auto-completion. Commands can share relevant code with web admin modules and are defined by the relevant modules.
     12
     13== Usage ==
     14
     15Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].
     16
     17The implementation has to implement the {{{get_admin_commands()}}} method. It should return a tuple for each supported command. The tuple contains the command name (can consist of multiple space-separated words, giving the illusion of sub-commands), argument description and help text and two callback functions.
     18
     19The first callback function is for automatic command completion in [wiki:TracAdmin#InteractiveMode trac-admin's interactive mode]. If no command completion support can be provided, the tuple should contain {{{None}}} instead of a callback. If a callback is provided, it is called when the user triggers a command completion (by pressing the command completion key, usually ''Tab'') after typing the respective command. (Note that command completion depends on the ''readline'' library, which may need to be installed and configured separately.) It can simply return a list of suggestions for completing the current command argument. More advanced completion can be achieved by returning a list subclass implementing a {{{complete(text)}}} method. (See for example {{{trac.admin.api.PrefixList}}})
     20
     21The second callback is the actual command to be executed, with the command arguments passed as positional arguments.
     22
     23== Examples ==
     24
     25The following example implements two trivial commands ''greeting list'' and ''greeting say <greeting>''. The first lists some known greetings. The second prints the given greeting, and implements completion for the known greetings.
     26
     27{{{#!python
     28from trac.core import *
     29from trac.admin import IAdminCommandProvider
     30from trac.util.text import print_table, printout
     31
     32class GreetingsAdminCommandProvider(Component):
     33
     34    implements(IAdminCommandProvider)
     35
     36    # IAdminCommandProvider methods
     37
     38    greetings = ['hi', 'hello', 'salut', 'hola', 'ciao']
     39
     40    def get_admin_commands(self):
     41        yield ('greeting list', '',
     42               'Get a list of greetings',
     43               None, self._do_list)
     44        yield ('greeting say', '<greeting>',
     45               'Say a greeting',
     46               self._complete_greeting, self._do_say_greeting)
     47
     48    def _do_list(self):
     49        print_table(self.greetings)
     50
     51    def _complete_greeting(self, args):
     52        return self.greetings
     53
     54    def _do_say_greeting(self, greeting):
     55        printout(greeting)
     56}}}
     57
     58== Available Implementations ==
     59
     60There are several implementations in various core parts of Trac:
     61
     62* [source:trunk/trac/config.py#L733 trac.config.ConfigurationAdmin][[br]]
     63  trac-admin command provider for trac.ini administration.
     64   * Implemented commands: ''config *'' (where ''*'' is one of: ''get'', ''set'', ''remove'', ...)
     65   * Command completion support for config sections and per-section options.
     66
     67* [source:trunk/trac/env.py#L809 trac.env.EnvironmentAdmin][[br]]
     68  trac-admin command provider for environment administration
     69   * Implemented commands: ''deploy'', ''hotcopy'', ''upgrade''
     70   * No command completion support.
     71
     72* [source:trunk/trac/versioncontrol/admin.py#L38 trac.versioncontrol.admin.VersionControlAdmin][[br]]
     73  trac-admin command provider for version control administration.
     74   * Implemented commands: ''changeset *'' (where ''*'' is one of: ''added'', ''modified'', ...) and ''repository  *'' (where ''*'' is one of: ''list'', ''sync'', ''resync'', ...)
     75   * Command completion support for repository names.
     76
     77* [source:trunk/trac/perm.py#L578 trac.perm.PermissionAdmin][[br]]
     78  trac-admin command provider for permission system administration.
     79   * Implemented commands: ''permission *'' (where ''*'' is one of: ''list'', ''add'', ''remove'', ...)
     80   * Command completion support for user and permission action names.
     81
     82* [source:trunk/trac/wiki/admin.py#L38 trac.wiki.admin.WikiAdmin][[br]]
     83  trac-admin command provider for wiki administration.
     84   * Implemented commands: ''wiki *'' (where ''*'' is one of: ''list'', ''rename'', ''remove'', ''import'', ''export'', ''dump'', ''load'', ''replace'', ''upgrade'', ...)
     85   * Command completion support for wiki page names and filenames / paths.
     86   * Note the **reusable filename / path completion support** provided by {{{trac.admin.api.get_dir_list()}}}
     87
     88The ticket system alone provides several implementations for different aspects of ticket administration:
     89
     90* [source:trunk/trac/ticket/admin.py#L163 trac.ticket.admin.ComponentAdminPanel]
     91   * Implemented commands: ''component *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''remove'', ''chown'', ...)
     92   * Command completion support for user and component names.
     93
     94* [source:trunk/trac/ticket/admin.py#L342 trac.ticket.admin.MilestoneAdminPanel]
     95   * Implemented commands: ''milestone *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''due'', ''completed'', ''remove'', ...)
     96   * Command completion support for milestone names.
     97
     98* [source:trunk/trac/ticket/admin.py#L506 trac.ticket.admin.VersionAdminPanel]
     99   * Implemented commands: ''version *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''time'', ''remove'', ...)
     100   * Command completion support for the version field.
     101
     102* [source:trunk/trac/ticket/admin.py#L676 trac.ticket.admin.AbstractEnumAdminPanel][[br]]
     103  base class for trac-admin command providers for administration of the ticket enums Priority, Resolution, Severity and !TicketType
     104   * Implemented commands: ''priority *'', ''resolution *'', ''severity *'', ''ticket_type *'' (where ''*'' is one of: ''list'', ''add'', ''change'', ''remove'', ''order'', ...)
     105   * Command completion support for enum fields.
     106
     107* [source:trunk/trac/ticket/admin.py#L786 trac.ticket.admin.TicketAdmin]
     108   * Implemented commands: ''ticket *'' (where ''*'' is ''remove'')
     109   * No command completion support.
     110
     111== Additional Information and References ==
     112
     113 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.admin.api.IAdminCommandProvider-class.html epydoc]
     114 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_admin.html#trac.admin.IAdminCommandProvider API Reference]
     115 * Initial development: #7770, [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/4359 mailing list archive]
     116 * Enhancement requests for more commands:
     117   * ''ticket add'': #10049
     118   * ''ticket export'', ''ticket import'': #8383, #8998
     119   * ''permission export'', ''permission import'': #9336
     120 * Readline and command completion:
     121   * Workarounds implemented for readline changes: #8711
     122   * Mac OS X and libedit vs. pyreadline: #6695, [http://article.gmane.org/gmane.comp.version-control.subversion.trac.devel/6774 mailing list archive]
     123   * Windows command completion: #9336, requires [http://pypi.python.org/pypi/pyreadline pyreadline]
     124   * Completion for multi-word suggestions / suggestions with spaces: #6797
     125   * {{{ValueError: No closing quotation}}}: #6998
     126   * [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/6766 mailing list archive] discussion about command completion.