Package: z3c.autoinclude
OverviewThis 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.includeDependenciesThe “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.Grokandgrokprojectuse this functionality out of the box. The
grokproject command will automatically add theincludeDependenciesdirective in the ZCML of the project it generates.  You can then stop
worrying about manual ZCML inclusion in the vast majority of cases.includePluginsThe “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’ssetup.py:entry_points="""
[z3c.autoinclude.plugin]
target = my_base
"""The DetailsSetupTo make the z3c.autoinclude directives available for use in your
application or framework, you need to include it (in yourmeta.zcmlfor instance), like this:<include package="z3c.autoinclude" file="meta.zcml" />Grok already does this for you automatically.Disabling z3c.autoincludeIt 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 FilenamesThe includeDependencies directive automatically includesconfigure.zcmlandmeta.zcmlfiles 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’sconfigure.zcmlandmeta.zcmlyourself to
include the ZCML using the manualincludedirective.The includePlugins directive automatically includesconfigure.zcmlandmeta.zcmlfiles by default, and the includePluginsOverrides
directive automatically includesoverrides.zcmlfiles by default.
But, like “<include>”, these directives also have an optional “file”
parameter, so you can automatically include allfoo.zcmlfiles in
your package’s plugins like this:<includePlugins package="." file="foo.zcml" />The includeDependencies directives will soon offer this option as well.Changes1.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 variableZ3C_AUTOINCLUDE_DEBUGis set,
log which packages are being automatically included.
Do this in a form that you can copy to aconfigure.zcmlfile.Add support for Python 3.8.0.3.9 (2019-03-02)Bug fixes:Catch and ignore AttributeError formodule.__file__.
Fixesissue 6.
[maurits]0.3.8 (2018-11-04)New features:Add support for Python 3.6 and 3.7.Bug fixes:Fix theincludePluginsdirective 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 iteratingsys.pathand askingpkg_resourcesfor distributions was picked. This should increase test
repeatability but is not expected to be otherwise noticeable. SeePR 3for 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 raisesImportError, 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 thegobjectmodule which provides a Python binding toGObject. In a recent
API deprecation, one is no longer allowed to both importgiandgobject.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)LetsubpackageDottedNamesalways return a sorted list of package names asos.listdirdoesn’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 ZCMLincludePluginsdirective 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 separateincludePluginsOverridesdirective to be used when
loading overrides, and no longer look for ‘overrides.zcml’ files by default
withincludePlugins.Removed the deprecatedautoincludeandautoincludeOverridesdirectives.Allow autoinclusion to be disabledby settingos.environ['Z3C_AUTOINCLUDE_PLUGINS_DISABLED']andos.environ['Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED'], potentially useful for
test runners or debugging sessions.For context on many of these changes, seethe PLIP #247 discussion.0.2.2 (2008-04-22)Gracefully catch KeyErrors innamespaceForDottedName; 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.RewrotedistributionForPackagefunction.Added additional tests forincludePluginsand 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 directiveincludePlugins.Renamedautoincludedirective toincludeDependencies.Deprecatedautoincludedirective.0.1 (2008-02-25)Initial public release.