API Reference

main

Main module to run the Gordon Janitor service.

The service expects a gordon-janitor.toml and/or a gordon-janitor-user.toml file for configuration in the current working directory, or in a provided root directory.

Any configuration defined in gordon-janitor-user.toml overwrites those in gordon-janitor.toml.

Example:

$ python gordon_janitor/main.py
$ python gordon_janitor/main.py -c /etc/default/
$ python gordon_janitor/main.py --config-root /etc/default/
gordon_janitor.main.setup(config_root='')[source]

Service configuration and logging setup.

Configuration defined in gordon-janitor-user.toml will overwrite gordon-janitor.toml.

Parameters:config_root (str) – where configuration should load from, defaults to current working directory.
Returns:A dict for Gordon service configuration
gordon_janitor.main.setup(config_root='')[source]

Service configuration and logging setup.

Configuration defined in gordon-janitor-user.toml will overwrite gordon-janitor.toml.

Parameters:config_root (str) – where configuration should load from, defaults to current working directory.
Returns:A dict for Gordon service configuration

plugins_loader

Module for loading plugins distributed via third-party packages.

Plugin discovery is done via entry_points defined in a package’s setup.py, registered under 'gordon.plugins'. For example:

# setup.py
from setuptools import setup

setup(
    name=NAME,
    # snip
    entry_points={
        'gordon.plugins': [
            'gcp.gpubsub = gordon_gcp.gpubsub:EventClient',
            'gcp.gce.a = gordon_gcp.gce.a:ReferenceSourceClient',
            'gcp.gce.b = gordon_gcp.gce.b:ReferenceSourceClient',
            'gcp.gdns = gordon_gcp.gdns:DNSProviderClient',
        ],
    },
    # snip
)

Plugins are initialized with any config defined in gordon-user.toml and gordon.toml. See Configuring the Gordon Janitor Service for more details.

Once a plugin is found, the loader looks up its configuration via the same key defined in its entry point, e.g. gcp.gpubsub.

The value of the entry point (e.g. gordon_gcp.gpubsub:EventClient) must point to a class. The plugin class is instantiated with its config.

A plugin will not have access to another plugin’s configuration. For example, the gcp.gpusub will not have access to the configuration for gcp.gdns.

See Gordon Janitor’s Plugin System for details on how to write a plugin for Gordon.

gordon.plugins_loader.load_plugins(config, plugin_kwargs)[source]

Discover and instantiate plugins.

Parameters:
  • config (dict) – loaded configuration for the Gordon service.
  • plugin_kwargs (dict) – keyword arguments to give to plugins during instantiation.
Returns:

list of names of plugins, list of instantiated plugin objects, and any errors encountered while loading/instantiating plugins. A tuple of three empty lists is returned if there are no plugins found or activated in gordon config.

Return type:

Tuple of 3 lists

gordon.plugins_loader.load_plugins(config, plugin_kwargs)[source]

Discover and instantiate plugins.

Parameters:
  • config (dict) – loaded configuration for the Gordon service.
  • plugin_kwargs (dict) – keyword arguments to give to plugins during instantiation.
Returns:

list of names of plugins, list of instantiated plugin objects, and any errors encountered while loading/instantiating plugins. A tuple of three empty lists is returned if there are no plugins found or activated in gordon config.

Return type:

Tuple of 3 lists