Creating PyDitz plugins

Several aspects of PyDitz can be extended by writing plugins. There are currently two kinds of plugin available:

Other kinds may be available in future. This section gives general information which applies to all kinds of plugin.

Anatomy of a plugin

A PyDitz plugin is simply a python module or package, which contains a class derived from one of the PyDitz plugin classes, and put in a certain location (see the next section).

Plugins you create should set at least the following class attributes:

Plugin.name = None

Plugin name. If None, it is not registered.

Plugin.description = 'no description'

One-line plugin description. Appears in help text.

There are several others which can also be set:

Plugin.version = '0.1'

Plugin version. At the moment nothing is done with this; it’s for information only.

Plugin.author = 'unknown'

Plugin author. At the moment nothing is done with this; it’s for information only.

Plugin.package = None

Package name, if it is part of a package. This is used to locate auxiliary files bundled in the package.

Registering a plugin

There are several ways for your plugin to be picked up by PyDitz:

  • You can put it in plugins subdirectory of HOMEDIR/.ditz. The plugin will only be available to you.
  • You can put it in a plugins subdirectory of a PyDitz project’s issue directory. The plugin will be available to everyone using PyDitz on this project.
  • You can put the plugin in a package and register it as a setuptools ditz.plugin entrypoint. The plugin will be available on the system where the module is installed.

Any suitably-derived class found in one of these locations is automagically registered; you don’t have to do anything else.

You can check whether your plugin is being seen by PyDitz by invoking it with the --verbose option.

Making a standalone plugin

Here’s an example of a plugin. Suppose PyDitz provided an API to send high-five comments to social media whenever an issue is resolved. (Not yet, but watch this space GRIN.) There would be an advertised base class (say, called SocialMedia) which you could subclass to create your plugin, like this:

from ditz.social import SocialMedia

class FriendFace(SocialMedia):
    name = "friendface"
    description = "post to http://friendface.co.uk"
    author = "Moss"

    def post(self, comment):
        ...

To make this plugin visible to PyDitz, you would just put it in one of the plugins directories mentioned in Registering a plugin.

Making a setuptools plugin

To convert the standalone plugin to a setuptools one (assuming it’s in a file called friendface.py), you need a setup.py something like this (note how the package and plugin versions are kept in sync):

from setuptools import setup
from friendface import FriendFace

setup(name = "pyditz-friendface",
      py_modules = ["friendface"],
      version = FriendFace.version,
      install_requires = ['pyditz >= 0.8'],
      entry_points = {
          'ditz.plugin': 'friendface = friendface:FriendFace'
      }
)

See the setuptools documentation for the details. The advantages of doing it this way are several:

  1. You can distribute it on PyPI for others to use.
  2. You get all the cool versioning and dependency stuff that setuptools supports.

Of course, you can put as many plugins as you want in a single package, in which case the versioning hack above may not be appropriate.