== Extension Point : ''IAdminCommandProvider'' ==

||'''Interface'''||''IAdminCommandProvider''||'''Since'''||[wiki:TracDev/ApiChanges/0.12#IAdminCommandProvider 0.12]||
||'''Module'''||''trac.admin''||'''Source'''||[source:trunk/trac/admin/api.py#/IAdminCommandProvider api.py]||


The ''IAdminCommandProvider'' allows adding commands to the console administration interface [wiki:TracAdmin trac-admin].

== Purpose ==

Trac 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.

== Usage ==

Implementing the interface follows the standard guidelines found in [wiki:TracDev/ComponentArchitecture] and of course [wiki:TracDev/PluginDevelopment].

The 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.

The 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}}})

The second callback is the actual command to be executed, with the command arguments passed as positional arguments.

== Examples ==

The 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.

{{{#!python
from trac.core import *
from trac.admin import IAdminCommandProvider
from trac.util.text import print_table, printout

class GreetingsAdminCommandProvider(Component):

    implements(IAdminCommandProvider)

    # IAdminCommandProvider methods

    greetings = ['hi', 'hello', 'salut', 'hola', 'ciao']

    def get_admin_commands(self):
        yield ('greeting list', '',
               'Get a list of greetings',
               None, self._do_list)
        yield ('greeting say', '<greeting>',
               'Say a greeting',
               self._complete_greeting, self._do_say_greeting)

    def _do_list(self):
        print_table([self.greetings])

    def _complete_greeting(self, args):
        return self.greetings

    def _do_say_greeting(self, greeting):
        printout(greeting)
}}}

== Available Implementations ==

There are several implementations in various core parts of Trac:

* [source:trunk/trac/config.py#/ConfigurationAdmin trac.config.ConfigurationAdmin][[br]]
  trac-admin command provider for trac.ini administration.
   * Implemented commands: ''config *'' (where ''*'' is one of: ''get'', ''set'', ''remove'', ...)
   * Command completion support for config sections and per-section options.

* [source:trunk/trac/env.py#/EnvironmentAdmin trac.env.EnvironmentAdmin][[br]]
  trac-admin command provider for environment administration
   * Implemented commands: ''deploy'', ''hotcopy'', ''upgrade''
   * No command completion support.

* [source:trunk/trac/versioncontrol/admin.py#/VersionControlAdmin trac.versioncontrol.admin.VersionControlAdmin][[br]]
  trac-admin command provider for version control administration.
   * Implemented commands: ''changeset *'' (where ''*'' is one of: ''added'', ''modified'', ...) and ''repository  *'' (where ''*'' is one of: ''list'', ''sync'', ''resync'', ...)
   * Command completion support for repository names.

* [source:trunk/trac/perm.py#/PermissionAdmin trac.perm.PermissionAdmin][[br]]
  trac-admin command provider for permission system administration.
   * Implemented commands: ''permission *'' (where ''*'' is one of: ''list'', ''add'', ''remove'', ...)
   * Command completion support for user and permission action names.

* [source:trunk/trac/wiki/admin.py#/WikiAdmin trac.wiki.admin.WikiAdmin][[br]]
  trac-admin command provider for wiki administration.
   * Implemented commands: ''wiki *'' (where ''*'' is one of: ''list'', ''rename'', ''remove'', ''import'', ''export'', ''dump'', ''load'', ''replace'', ''upgrade'', ...)
   * Command completion support for wiki page names and filenames / paths.
   * Note the **reusable filename / path completion support** provided by {{{trac.admin.api.get_dir_list()}}}

The ticket system alone provides several implementations for different aspects of ticket administration:

* [source:trunk/trac/ticket/admin.py#/ComponentAdminPanel trac.ticket.admin.ComponentAdminPanel]
   * Implemented commands: ''component *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''remove'', ''chown'', ...)
   * Command completion support for user and component names.

* [source:trunk/trac/ticket/admin.py#/MilestoneAdminPanel trac.ticket.admin.MilestoneAdminPanel]
   * Implemented commands: ''milestone *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''due'', ''completed'', ''remove'', ...)
   * Command completion support for milestone names.

* [source:trunk/trac/ticket/admin.py#/VersionAdminPanel trac.ticket.admin.VersionAdminPanel]
   * Implemented commands: ''version *'' (where ''*'' is one of: ''list'', ''add'', ''rename'', ''time'', ''remove'', ...)
   * Command completion support for the version field.

* [source:trunk/trac/ticket/admin.py#/AbstractEnumAdminPanel trac.ticket.admin.AbstractEnumAdminPanel][[br]]
  base class for trac-admin command providers for administration of the ticket enums Priority, Resolution, Severity and !TicketType 
   * Implemented commands: ''priority *'', ''resolution *'', ''severity *'', ''ticket_type *'' (where ''*'' is one of: ''list'', ''add'', ''change'', ''remove'', ''order'', ...)
   * Command completion support for enum fields.

* [source:trunk/trac/ticket/admin.py#?TicketAdmin trac.ticket.admin.TicketAdmin]
   * Implemented commands: ''ticket *'' (where ''*'' is ''remove'')
   * No command completion support.

== Additional Information and References ==

 * [http://www.edgewall.org/docs/trac-trunk/epydoc/trac.admin.api.IAdminCommandProvider-class.html epydoc]
 * [http://www.edgewall.org/docs/trac-trunk/html/api/trac_admin.html#trac.admin.IAdminCommandProvider API Reference]
 * Initial development: #7770, [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/4359 mailing list archive]
 * Enhancement requests for more commands:
   * ''ticket add'': #10049
   * ''ticket export'', ''ticket import'': #8383, #8998
   * ''permission export'', ''permission import'': #9336
 * Readline and command completion:
   * Workarounds implemented for readline changes: #8711
   * Mac OS X and libedit vs. pyreadline: #6695, [http://article.gmane.org/gmane.comp.version-control.subversion.trac.devel/6774 mailing list archive]
   * Windows command completion: #9336, requires [http://pypi.python.org/pypi/pyreadline pyreadline]
   * Completion for multi-word suggestions / suggestions with spaces: #6797
   * {{{ValueError: No closing quotation}}}: #6998
   * [http://thread.gmane.org/gmane.comp.version-control.subversion.trac.devel/6766 mailing list archive] discussion about command completion.