 how to use entry points to create a plugin mechansim which allows new types of content to be added to a content management system but we are going to start by looking at the plugin.
Say the standard way the CMS creates a plugin is with the
make_plugin() function. In order for a plugin to be a plugin it must therefore have the function which takes the same arguments as the
make_plugin() function and returns a plugin. We are going to add some image plugins to the CMS so we setup a project with the following directory structure:
+ image_plugins + __init__.py + setup.py
The
image_plugins/__init__.py file looks like this:
def make_jpeg_image_plugin(): return "This would return the JPEG image plugin" def make_png_image_plugin(): return "This would return the PNG image plugin"
We have now defined our plugins so we need to define our entry points. First lets write a basic
setup.py for the project:
from setuptools import setup, find_packages setup( name='ImagePlugins', version="1.0", description="Image plugins for the imaginary CMS 1.0 project", author="James Gardner", packages=find_packages(), include_package_data=True, )
When using
setuptools we can specify the
find_packages() function and
include_package_data=True rather than having to manually list all the modules and package data like we had to do in the old
distutils
setup.py.
Because the plugin is designed to work with the (imaginary) CMS 1.0 package, we, separated by a
. character and then use a name that describes what the entry point does. For our example
cms.plugin might be an appropriate name for the entry point. Since the
image_plugin module contains two plugins we will need two entries. Add the following to the
setup.py function:
entry_points=""" [cms.plugin] jpg_image=image_plugin:make_jpeg_image_plugin png_image=image_plugin:make_jpeg.
There are two more things we need to do to complete the plugin. The first is to include an
ez_setup module so that if the user installing the plugin doesn’t have
setuptools installed, it will be installed for them. We do this by adding the following to the very top of the
setup.py file before the import:
from ez_setup import use_setuptools use_setuptools()
We also need to download the
ez_setup.py file into our project directory at the same level as
setup.py.
Note
If you keep your project in SVN there is a trick you can use with the `SVN:externals to keep the
ez_setup.py file up to date.
Finally in order for the CMS to find the plugins we need to install them. We can do this with:
$ python setup.py install
as usual or, since we might go on to develop the plugins further we can install them using a special development mode which sets up the paths to run the plugins from the source rather than installing them to Python’s
site-packages directory:
$ python setup.py develop
Both commands will download and install
setuptools if you don’t already have it installed. the following output:
This would return the JPEG image plugin This would return the PNG image plugin
The
iter_entry_points() function has looped though all the objects in the
cms.plugin group and returned the function they were associated with. The application then called the function that the entry point was pointing to.
We hope that we have demonstrated the power of entry points for building extensible code and developers are encouraged to read the pkg_resources module documentation to learn about some more features of the eggs format.