z3c.autoinclude 1.0

Automatically include ZCML

Overview

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.

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

The Details

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.

When environment variable “Z3C_AUTOINCLUDE_DEBUG” is set, we log which packages are being automatically included. We do this in a form that you can copy to a configure.zcml file.

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.

Changes

1.0 (2023-03-01)

Breaking changes:

• Drop support for Python 2.7, 3.5, 3.6.

New features:

• Add support for Python 3.9, 3.10, 3.11.

0.4.1 (2020-11-12)

Bug fixes:

• zc.buildout is not an install dependency, only used in testing.

0.4.0 (2020-04-21)

Breaking changes:

• Drop support for Python 3.4.

New features:

• When environment variable Z3C_AUTOINCLUDE_DEBUG is set, log which packages are being automatically included. Do this in a form that you can copy to a configure.zcml file.

• Add support for Python 3.8.

0.3.9 (2019-03-02)

Bug fixes:

• Catch and ignore AttributeError for module.__file__. Fixes issue 6. [maurits]

0.3.8 (2018-11-04)

New features:

• Add support for Python 3.6 and 3.7.

Bug fixes:

• Fix the includePlugins directive to read filenames as native strings in Python 3.

0.3.7 (2016-08-24)

• Add support for Python 3.4, Python 3.5 and PyPy.

• When choosing between multiple (equivalent) packages that offer the same namespace and there are no namespace-only packages, choose either the one whose project name matches the namespace (if there are no dots in the namespace), or the first when sorted by project name. Previously, the first in the list generated from the combination of iterating sys.path and asking pkg_resources for distributions was picked. This should increase test repeatability but is not expected to be otherwise noticeable. See PR 3 for discussion.

0.3.6 (2016-01-29)

• Standardize namespace __init__.

• Fix broken tests.

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.

For context on many of these changes, see the PLIP #247 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.