z3c.autoinclude 0.3.2

includeDependencies

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.

includePlugins

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:

entry_points="""
[z3c.autoinclude.plugin]
target = my_base
"""

Setup

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.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.