Welcome, guest | Sign In | My Account | Store | Cart

Notice! PyPM is being replaced with the ActiveState Platform, which enhances PyPM’s build and deploy capabilities. Create your free Platform account to download ActivePython or customize Python with the packages you require and get automatic updates.

pypm install z3c.autoinclude

How to install z3c.autoinclude

  1. Download and install ActivePython
  2. Open Command Prompt
  3. Type pypm install z3c.autoinclude
 Python 2.7Python 3.2Python 3.3
Windows (32-bit)
0.3.5Never BuiltWhy not?
0.3.4 Available View build log
0.3.3 Available View build log
Windows (64-bit)
0.3.5Never BuiltWhy not?
0.3.4 Available View build log
0.3.3 Available View build log
Mac OS X (10.5+)
0.3.5Never BuiltWhy not?
0.3.4 Available View build log
0.3.3 Available View build log
Linux (32-bit)
0.3.5Never BuiltWhy not?
0.3.4 Available View build log
0.3.3 Available View build log
Linux (64-bit)
0.3.5 Available View build log
0.3.4 Available View build log
0.3.3 Available View build log
Depended by
Lastest release
version 0.3.5 on Jan 9th, 2014


This package adds two new ZCML directives to automatically detect ZCML files to include: "includeDependencies" and "includePlugins".

When you want to include a Zope-based package in your application, you have to repeat yourself in two places: you have to add the package itself (in a setup.py, buildout, etc) and you also have to include its ZCML with an <include> directive or a package-includes slug. Because you have to repeat yourself, you can easily make an error where you add a new package but forget to include its ZCML.

z3c.autoinclude lets you circumvent this error-prone process with automatic detection and inclusion of ZCML files.


The "includeDependencies" directive searches through the dependencies in your setup.py file (install_requires), and includes the ZCML files in those packages that it finds. Inclusion order matches the order in the setup.py file. You can pass a path for the package you want to include dependencies for, but typically you pass in the current package, as follows:

<includeDependencies package="." />

With this directive, you no longer have to add an explicit <include package=new.dependency> for every new dependency of your project.

Grok and grokproject use this functionality out of the box. The grokproject command will automatically add the includeDependencies directive in the ZCML of the project it generates. You can then stop worrying about manual ZCML inclusion in the vast majority of cases.


The "includePlugins" directive uses entry points to find installed packages that broadcast themselves as plugins to a particular base package. You can pass a path for the package you want to include plugins for, but typically you pass in the current package, as follows:

<includePlugins package="." />

To broadcast a package as a plugin to a base package called "my_base", add the following lines to the plugin package's setup.py:

target = my_base

The Details


To make the z3c.autoinclude directives available for use in your application or framework, you need to include it (in your meta.zcml for instance), like this:

<include package="z3c.autoinclude" file="meta.zcml" />

Grok already does this for you automatically.

Disabling z3c.autoinclude

It is often useful to disable z3c.autoinclude's functionality for debugging purposes or test runs. To disable autoinclusion, set the environment variables "Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED" and "Z3C_AUTOINCLUDE_PLUGINS_DISABLED".

When autoinclusion is disabled, the autoinclusion directives will issue a warning to the log and do nothing.

ZCML Filenames

The includeDependencies directive automatically includes configure.zcml and meta.zcml files that live in the main package directories. For automatic inclusion of dependencies' overrides, there is an <includeDependenciesOverrides> directive.

In some cases, a package may use unusual names or locations for its ZCML files. In that case you will need to modify your package's configure.zcml and meta.zcml yourself to include the ZCML using the manual include directive.

The includePlugins directive automatically includes configure.zcml and meta.zcml files by default, and the includePluginsOverrides directive automatically includes overrides.zcml files by default. But, like "<include>", these directives also have an optional "file" parameter, so you can automatically include all foo.zcml files in your package's plugins like this:

<includePlugins package="." file="foo.zcml" />

The includeDependencies directives will soon offer this option as well.


0.3.5 (2013-09-12)
  • If a module cannot be resolved, but raises ImportError, log a warn and continue. This fixes an issue where the determining the includable packages would fail due to a problem with the importation of one or potentially more modules. An example is the gobject module which provides a Python binding to GObject. In a recent API deprecation, one is no longer allowed to both import gi and gobject.
0.3.4 (2011-03-11)
  • Remove unnecessary distribution lookup in the PluginFinder.
0.3.3 (2010-05-06)
  • Ignore case in tests in order to pass tests on Windows.
  • Clearly specify license as ZPL (not public domain, as it was claiming before).
0.3.2 (2009-12-19)
  • Let subpackageDottedNames always return a sorted list of package names as os.listdir doesn't on some platforms.
0.3.1 (2009-05-04)
  • z3c.autoinclude no longer (spuriously) depends on PasteScript.
0.3 (2009-03-03)
  • Allow virtual namespace packages like 'plone' to be specified for the package. I think this may need more thought for the dependency case.
  • Allow ZCML includePlugins directive to specify a particular ZCML file to try to load from plugins, so that loading of meta, configure and overrides can be split across three ZCML files if desired. You can specify a file like: <includePlugins package="." file="silly.zcml" />.
  • Provide a separate includePluginsOverrides directive to be used when loading overrides, and no longer look for 'overrides.zcml' files by default with includePlugins.
  • Removed the deprecated autoinclude and autoincludeOverrides directives.
  • Allow autoinclusion to be disabled by setting os.environ['Z3C_AUTOINCLUDE_PLUGINS_DISABLED'] and os.environ['Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED'], potentially useful for test runners or debugging sessions. See http://lists.plone.org/pipermail/framework-team/2009-February/002689.html for discussion.
0.2.2 (2008-04-22)
  • Gracefully catch KeyErrors in namespaceForDottedName; get_metadata_lines will sometimes throw this for certain distribution types, apparently. In particular, some systems' version of Python itself will be wrapped in a distribution which throws this error, resulting in system-dependent unresumable breakage of z3c.autoinclude prior to this fix.
0.2.1 (2008-04-21)
  • Fixed bug which prevented proper inclusion of packages when the base package's namespace has been extended by other installed packages.
  • Rewrote distributionForPackage function.
  • Added additional tests for includePlugins and utility functions.
  • Fixed bug which made z3c.autoinclude look for ZCML in namespaces of nested namespace packages (eg, if there happened to -- improperly -- be an x/y/configure.zcml in a x.y.z package with an x.y namespace, it would have been included; this is incorrect.)
0.2 (2008-04-18)
  • Added new directive includePlugins.
  • Renamed autoinclude directive to includeDependencies.
  • Deprecated autoinclude directive.
0.1 (2008-02-25)
  • Initial public release.

Subscribe to package updates

Last updated Jan 9th, 2014

Download Stats

Last month:3

What does the lock icon mean?

Builds marked with a lock icon are only available via PyPM to users with a current ActivePython Business Edition subscription.

Need custom builds or support?

ActivePython Enterprise Edition guarantees priority access to technical support, indemnification, expert consulting and quality-assured language builds.

Plan on re-distributing ActivePython?

Get re-distribution rights and eliminate legal risks with ActivePython OEM Edition.