Creating PyDitz plugins¶
Several aspects of PyDitz can be extended by writing plugins. There are currently two kinds of plugin available:
- Plugins to define new commands
- Plugins to define new export formats
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. 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 ofHOMEDIR/.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 .) 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:
- You can distribute it on PyPI for others to use.
- 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.