Permalink
Switch branches/tags
Nothing to show
Find file Copy path
4c41470 Oct 22, 2017
1 contributor

Users who have contributed to this file

83 lines (56 sloc) 1.61 KB

Gather

.. toctree::
   :maxdepth: 2

Overview

The gather package allows easily gathering up plugins. The basic class defined is the Collector.

import gather
THINGS = gather.Collector()

In order to register an object as a plugin, we merely decorate it:

@THINGS.register()
def some_function():
    pass

Note that the decorator always returns the function -- some_function remains perfectly usable.

Finding all the things collected is simple:

registered = THINGS.collect()

The return value is a dictionary, mapping names to registered objects.

If an alternative name is needed for registration, one can be provided explicitly:

@THINGS.register(name='register_as_this_name')
def generic():
    pass

When registering functions that expect an argument list, like sys.argv, the run function can be used to run them directly:

gather.run(
    commands=THINGS.collect(),
    version='1.2.3',
    argv=sys.argv[1:],
    output=sys.stdout
)

It is important to remember that all the gathering depends on registering an entry point in the setup.py:

entry_points={
    'gather': [
         "gather=ROOT_PACKAGE",
    ]

Putting the package name there is enough -- gather will automatically collect from any sub-modules, recursing any number of levels. This is also enough to register it for any gather-using plugins.

API

.. automodule:: gather.api
   :members: