Setuptools Entrypoints Explained

Python's setuptools has a rather interesting feature called "entry points" which facilitates plugin discovery. I'm using this in imhotep to allow linters to live as separate packages.

So how does it work?

In your setup.py, you defined a property called entry_points which is a dictionary mapping the entry point key to a list of values. The values take the form of .py = imhotep_pylint.plugin:PyLint. This is another mapping in string form from a user-defined string to a dotted module name (and optionally, as here, an object to import).

from setuptools import setup
setup(
    # ...
    entry_points={
        'imhotep_linters': [
            '.py = imhotep_pylint.plugin:PyLint'
        ],
    },
    # ...
)

Taking an example from imhoteppylint, you can see that this package defines an entrypoint for "imhoteplinters". This string is part of the imhotep API and plugins have to register their entrypoints with that. From there, we define a list of one item, which says that the .py string should map to the PyLint object living in imhotep_pylint.plugin.

How do I discover these?

You can use the pkg_resources package to discover these plugins at run-time. It looks something like this (pulled from imhotep):

def load_plugins():
    tools = []
    for ep in pkg_resources.iter_entry_points(group='imhotep_linters'):
        klass = ep.load()
        tools.append(klass(run))
    return tools

This uses the group name we've mutually agreed upon, imhotep_linters, to return an iterable of entrypoints. From there, we call the load() method, which will materialize the entrypoint into a class object. From there, it's just like any other sort of class which you can instantiate and use.

This is actually all there is to implementing a plugin system for your package. Python's setuptools makes this quite easy! You can find more official docs here.

© 2012 - 2020 · Home — Theme Simpleness