Extension Point : IAdminCommandProvider
The IAdminCommandProvider allows adding commands to the console administration interface trac-admin.
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 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.
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 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
The second callback is the actual command to be executed, with the command arguments passed as positional arguments.
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.
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)
There are several implementations in various core parts of Trac:
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.
trac-admin command provider for environment administration
- Implemented commands: deploy, hotcopy, upgrade
- No command completion support.
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.
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.
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
The ticket system alone provides several implementations for different aspects of ticket administration:
- Implemented commands: component * (where * is one of: list, add, rename, remove, chown, …)
- Command completion support for user and component names.
- Implemented commands: milestone * (where * is one of: list, add, rename, due, completed, remove, …)
- Command completion support for milestone names.
- Implemented commands: version * (where * is one of: list, add, rename, time, remove, …)
- Command completion support for the version field.
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.
- Implemented commands: ticket * (where * is remove)
- No command completion support.
Additional Information and References
- API Reference
- Initial development: #7770, mailing list archive
- Enhancement requests for more commands:
- Readline and command completion:
- Workarounds implemented for readline changes in #8711, removed in #12884.
- Mac OS X and libedit vs. pyreadline: #6695, mailing list archive
- Windows command completion: #9336, requires pyreadline
- Completion for multi-word suggestions / suggestions with spaces: #6797
ValueError: No closing quotation: #6998
- mailing list archive discussion about command completion.