Quickstart

Applications

Create an app

Create a file named my_app.py and add the following code:

from groundwork import App

if __name__ == "__main__":
    my_app = App()
    my_app.plugins.activate(["GwPluginInfo"])
    my_app.commands.start_cli()

This code performs the following actions:

• It creates a groundwork application app via my_app = App()

• It activates the plugin GwPluginInfo, which is part of groundwork itself.

  • During activation, GWPluginInfo registers a command called plugin_list by its own.

• It starts the command line interface

Run an app

Open a command line interface, change to folder, which contains my_app.py, and execute:

python my_app.py

This will start groundwork and its command line interface.

Because no command was added as parameter, groundwork complains about it. To change this, simply add the needed command

python my_app.py plugin_list

This will print a list of all available plugins, including some helpful information about them.

Plugins

Activate registered plugins

Activating already registered plugins like GwPluginInfo is easy. All you need to know is the name of a plugin.:

my_app.activate(["GwPluginInfo", "GwCommandsInfo", "GwSignalInfo"])

groundwork knows these names, because it automatically scans the used python environment for packages, which are providing groundwork plugins. See Plugin registration for more details or Packaging and Installation for using this mechanism for own plugins.

Create own plugins

The easiest way of creating a groundwork plugin is by defining a class, which inherits from GwBasePattern. But before activation, it also needs to be registered, what can be done during application initialisation:

from groundwork import App
from groundwork.patterns import GwBasePattern

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

    def activate(self): pass

    def deactivate(self): pass


my_app = App(plugins=[MyPlugin])    # Register your plugin class
my_app.plugins.activate(["My Plugin"])      # And activate it

You can also use the plugin object itself to perform the activation:

# Instead of
# my_app = App(plugins=[MyPlugin])
# my_app.activate(["My Plugin"])
my_app = App()
my_plugin = MyPlugin(app=my_app)
my_plugin.activate()

Note

If a plugin inherits from any pattern, GwBasePattern is no longer needed as the pattern itself does already inherit from this class.

Warning

The __init__ routine of a plugin class must always set a name and call the next __init__ routine in the inheritance chain (in this order!).

Also make sure that your __init__ can handle app as the first argument and additional, optional keyword arguments.

If this is missed, the patterns and their objects are not initialized and configured the right way.

So always use:

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

Patterns

Using patterns

Patterns are used to inject new functionality to a plugin. There are patterns for registering commands, generating different types of documentation, activating web support and much more.

A plugin can inherit multiple patterns:

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

This code example gives MyPlugin functions to register new commands and new documents.

If your are using a coding environment with code completion, just type self. to see all available functions , including the inherited ones.

Writing patterns

A pattern is more or less a plugin without any activation or deactivation function. Like plugins, it must also inherit from GwBasePattern.

A pattern is allowed to multiply inherit from other patterns as well.

You can find an example with multiple inheritance in the Pattern Example Code.