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:
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")