Edgewall Software

Extension Point : IAdminCommandProvider

InterfaceIAdminCommandProviderSince0.12
Moduletrac.adminSourceapi.py​

The IAdminCommandProvider allows adding commands to the console administration interface 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 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 TracDev/ComponentArchitecture and of course 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 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. 

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:

  • trac.config.ConfigurationAdmin​
    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.env.EnvironmentAdmin​
    trac-admin command provider for environment administration
    • Implemented commands: deploy, hotcopy, upgrade
    • No command completion support.
  • trac.versioncontrol.admin.VersionControlAdmin​
    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.perm.PermissionAdmin​
    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.wiki.admin.WikiAdmin​
    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:

  • trac.ticket.admin.AbstractEnumAdminPanel​
    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.

Additional Information and References

Last modified 7 years ago Last modified on Aug 14, 2017, 12:51:41 AM
Note: See TracWiki for help on using the wiki.