#247: Automate ZCML Loading for Plone Plug-ins

Contents
  1. Definitions
  2. Motivation
  3. Assumptions
  4. Proposal
  5. Implementation
  6. Deliverables
  7. Risks
  8. Participants

Enable automatic plugins for Plone with z3c.autoinclude

Proposed by
Ethan Jucovy
Seconded by
Martin Aspeli
Proposal type
Architecture
Assigned to release
State
completed

Definitions

autoinclude: z3c.autoinclude, a package (http://pypi.python.org/pypi/z3c.autoinclude) for automatically including ZCML files from dependencies and plugins.

Plugin package: a package providing some extended functionality to Plone activated by execution of ZCML configuration.

Motivation

Installation of packages that extend Plone's functionality is currently somewhat burdensome. Most extension packages will provide ZCML that must be loaded in order for the package to function properly. The standard way of installing these plugin packages is to use ZCML slugs in the package-includes directory, typically marked in a buildout.cfg file for replicability. However, this is a burdensome process: editing the installed plugins involves editing the buildout.cfg file and re-running buildout, or adding and removing symlinks and files on the filesystem; there is no straightforward way to share different permutations of plugins without making nearly identical copies of buildout.cfg files; and the process involves unnecessary repetition of package names as requirements and plugins, a subtlety that integrators, particularly beginners, might easily overlook. A more automated and implicit system of loading plugins would eliminate this error-prone process.

Assumptions

Packages signal to autoinclude that they are plugin candidates by setting a setuptools entry_point, so plugin packages must be packaged as setuptools eggs.

Proposal

Explicitly invoke autoinclusion of plugins for Plone. This would look like:

<includePlugins package="plone.app" />

at the end of the CMFPlone/configure.zcml file, within the <configure> directive.

Plugin packages would then signal that they should be included by adding:

setup(...
entry_points="""
...
[z3c.autoinclude.plugin]
target = plone
...)
"""

to their setup.py file.

Implementation

See Proposal above.

Deliverables

See Proposal above.

Risks

autoinclude computes the packages to include at Zope startup, when each <include*> directive is executed, so it slows down the startup time. The execution time of the algorithm used is dependent on the number of entries in sys.path, so this slowdown may become unacceptable in environments with many eggs installed. This can be mitigated by future improvements in z3c.autoinclude like optimizations to the algorithm or a "freeze" script to compute autoinclusion packages once and output to a ZCML file.

Participants

Ethan Jucovy