Commands

Commands are used to provide access to different function via a command line interface (CLI).

groundwork cares automatically about CLI setup, help messages and command arguments.

However the command line interface must be started by the application itself.

Starting the CLI

To start the cli, be sure that at least one plugin gets activated, which is using the pattern GwCommandsPattern.

After application initialisation and plugin activations, start_cli() must be called:

from groundwork import App
from groundword.plugins import GwCommandInfo

my_app = App()
my_app.plugins.activate(["GwCommandInfo"])
my_app.commands.start_cli()

Registering commands

To register commands, a plugin must inherit from GwCommandsPattern and use the function register().

from groundwork.patterns import GwCommandsPattern

class MyPlugin(GwCommandsPattern):
    def __init__(self, app, **kwargs)
        self.name = "My Plugin"
        super().__init__(app, **kwargs)

    def activate(self):
        self.commands.register(command="my_command",
                               description="executes something",
                               function=self.my_command,
                               params=[])

    def my_command(self, plugin, **kwargs):
        print("Yehaaa")

Using arguments and options

groundworks’s command line support is based on click.

For arguments and options, groundwork is using the definition and native classes of click:

  • Arguments are positional parameters to a command
  • Options are usually optional value on a command.

To use them, you have to pass instances of them to the params parameter of the function register().

from groundwork.patterns import GwCommandsPattern
from click import Argument, Option

class MyPlugin(GwCommandsPattern):
    def __init__(self, app, **kwargs)
        self.name = "My Plugin"
        super().__init__(app, **kwargs)

    def activate(self):
        self.commands.register(command="my_command",
                               description="executes something",
                               function=self.my_command,
                               params=[Option(("--force", "-f"),
                                              required=False,
                                              help="Will force something...",
                                              default=False,
                                              is_flag=True)])

    def my_command(self, plugin, force, **kwargs):
        if force:
            print("FORCE Yehaaa")
        else:
            print("Maybe Yehaaa")

For detailed parameter description, please take a look into the documentation of click for arguments and options

Unregister a command

A command can also be unregistered during runtime.

Simply use unregister() and pass the name of the command:

...

def deactivate(self):
    self.commands.unregister("my_command")