Packaging and Installation

The distribution of plugins, patterns and even applications can easily be done by using solutions from Python’s packaging ecosystem. For packaging the library setuptools is recommend. For package installation, the wide known tool pip should be used.

Create a package

You can add as many plugins, patterns and even applications to a single python package as you like.

All you need is a file called in the root folder of your package. Example:

from setuptools import setup, find_packages

    description="My awesome package for doing hot stuff",
    long_description="A longer description of my awesome package",
    packages=find_packages(exclude=['ez_setup', 'examples', 'tests']),
    install_requires=["groundwork", "Another_Package"],
        'console_scripts': ["my_app my_package.my_app:start_app"],
        'groundwork.plugin': [
            'my_plugin = my_package.my_plugin:MyPlugin',
            'my_plugin_2" = my_package.my_plugin_2:MyPlugin2']

For more details, take a look into the Developer’s Guide of setuptools or read one of the many tutorials about on the internet.


Entry points are used to “advertise” Python objects for use by other distributions.

groundwork uses them to find plugins in installed packages, without the need to use some hard coded imports like from another_package import PluginX.

Therefore groundwork knows all packaged plugins, which are available in system path of the currently used python interpreter. These plugins can be used by activation, without any need to register or import them:

from groundwork import App

my_app = App()

# GwPluginsInfo is provided by an entry_point inside the groundwork package


During activation, the plugins are identified by their names. So the plugin name must be known, which is not necessarily the plugin class name.

The entry_point of a plugin must provide a class, which inherits directly or indirectly from GwBasePattern:

# from groundwork package

from setuptools import setup, find_packages

       'groundwork.plugin': [
            'gw_plugins_info = groundwork.plugins.gw_plugins_info:GwPluginsInfo',

Package structure

The following structure is recommended for packaging multiple plugins, patters and applications:

|-- my_package
|   |
|   |-- applications
|   |   |-- my_app
|   |       |--
|   |
|   |-- patterns
|   |   |-- my_pattern
|   |       |--
|   |
|   |-- plugins
|       |-- my_plugin
|       |   |--
|       |
|       |-- my_plugin_2
|           |--
|-- docs
|   |-- index.rst
|   |-- my_app.rst
|   |-- my_pattern.rst
|   |-- my_plugin.rst
|   |-- my_plugin_2.rst
|-- tests

Install a package

Local packages

If you store your package locally and do not use PyPI for distribution, you need to use your file for all installation scenarios.

During development

During development it is recommend to install a package in development mode on your current virtual environment:

python develop

This lets you make changes on your code without the need to reinstall your package after each code change. This must be done only, if you make some changes to the file.

Final installation

To finally install your package inside the current used python environment, use install:

python install

This will copy all files to your python environment and new changes on your plugin do not have any impact on the installed package.


PyPI can be used to share your package globally and allows users to use pip for installation:

pip install my_package

The usage of PyPi is already explained in some great tutorials. A short selection: