z3c.autoinclude 1.0

includeDependencies

“includeDependencies”指令会遍历您的setup.py文件中的依赖项（install_requires），并包含它找到的这些包中的ZCML文件。包含顺序与setup.py文件中的顺序匹配。您可以传递要包含依赖项的包的路径，但通常您会传递当前包，如下所示

<includeDependencies package="." />

使用此指令，您不再需要为项目中每个新的依赖项显式添加<include package=new.dependency>。

Grok和grokproject默认使用此功能。grokproject命令将自动将includeDependencies指令添加到它生成的项目的ZCML中。然后，在大多数情况下，您可以停止担心手动ZCML包含。

includePlugins

“includePlugins” 指令使用入口点来查找已安装的软件包，这些软件包将自己广播为特定基本软件包的插件。您可以传递您想要包含插件的软件包的路径，但通常您会传递当前软件包，如下所示

<includePlugins package="." />

要将软件包广播为名为“my_base”的基本软件包的插件，请将以下行添加到插件软件包的 setup.py

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

设置

为了使 z3c.autoinclude 指令可用于您的应用程序或框架，您需要将其包含在内（例如，在您的 meta.zcml 中），如下所示

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

Grok 已经为您自动完成。

禁用 z3c.autoinclude

在调试目的或测试运行中，禁用 z3c.autoinclude 的功能通常很有用。要禁用自动包含，设置环境变量“Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED”和“Z3C_AUTOINCLUDE_PLUGINS_DISABLED”。

当自动包含被禁用时，自动包含指令将在日志中发出警告而不执行任何操作。

当设置环境变量“Z3C_AUTOINCLUDE_DEBUG”时，我们将记录正在自动包含的软件包。我们将以您可以复制到 configure.zcml 文件的形式执行此操作。

ZCML 文件名

includeDependencies 指令会自动包含位于主软件包目录中的 configure.zcml 和 meta.zcml 文件。对于自动包含依赖项的覆盖，有一个 <includeDependenciesOverrides> 指令。

在某些情况下，软件包可能使用不寻常的名称或位置来存储其 ZCML 文件。在这种情况下，您需要自行修改软件包的 configure.zcml 和 meta.zcml，以使用手动 include 指令包含 ZCML。

includePlugins 指令默认会自动包含 configure.zcml 和 meta.zcml 文件，includePluginsOverrides 指令默认会自动包含 overrides.zcml 文件。但是，与“<include>”类似，这些指令也有可选的“file”参数，因此您可以像这样自动包含软件包插件中的所有 foo.zcml 文件

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

includeDependencies 指令很快也将提供此选项。

1.0 (2023-03-01)

破坏性更改

• 取消对 Python 2.7、3.5、3.6 的支持。

新功能

• 添加对 Python 3.9、3.10、3.11 的支持。

0.4.1 (2020-11-12)

错误修复

• zc.buildout 不是安装依赖项，仅在测试中使用。

0.4.0 (2020-04-21)

破坏性更改

• 取消对 Python 3.4 的支持。

新功能

• 当设置环境变量 Z3C_AUTOINCLUDE_DEBUG 时，记录正在自动包含的软件包。以您可以复制到 configure.zcml 文件的形式执行此操作。

• 添加对 Python 3.8 的支持。

0.3.9 (2019-03-02)

错误修复

• 捕获并忽略 module.__file__ 的 AttributeError。修复 问题 6。[maurits]

0.3.8 (2018-11-04)

新功能

• 添加对 Python 3.6 和 3.7 的支持。

错误修复

• 修复 includePlugins 指令，使其在 Python 3 中以本地字符串读取文件名。

0.3.7 (2016-08-24)

• 添加对 Python 3.4、Python 3.5 和 PyPy 的支持。

• 在选择提供相同命名空间的多（等效）软件包之间时，如果没有命名空间仅软件包，请选择项目名称与命名空间匹配的软件包（如果命名空间中没有点），或者按项目名称排序后的第一个。以前，从迭代 sys.path 和请求 pkg_resources 分布的组合生成的列表中的第一个被选中。这应该会增加测试的可重复性，但预计不会在其他方面引起注意。请参阅 PR 3 以进行讨论。

0.3.6 (2016-01-29)

• 标准化命名空间 __init__。

• 修复损坏的测试。

0.3.5 (2013-09-12)

• 如果无法解析模块，但引发 ImportError，记录警告并继续。这修复了由于一个或多个模块导入问题导致确定可包含包失败的问题。例如，gobject 模块提供对 GObject 的 Python 绑定。在最近的 API 弃用中，不再允许同时导入 gi 和 gobject。

0.3.4 (2011-03-11)

• 从 PluginFinder 中移除不必要的分发查找。

0.3.3 (2010-05-06)

• 在测试中忽略大小写，以便在 Windows 上通过测试。

• 明确指定许可证为 ZPL（不是公共领域，如之前所声称的那样）。

0.3.2 (2009-12-19)

• 让 subpackageDottedNames 总是返回一个按名称排序的包名列表，因为 os.listdir 在某些平台上不会这样做。

0.3.1 (2009-05-04)

• z3c.autoinclude 不再（错误地）依赖于 PasteScript。

0.3 (2009-03-03)

• 允许为包指定虚拟命名空间包，例如 'plone'。我认为这可能需要对依赖情况进行更多思考。

• 允许 ZCML includePlugins 指令指定要尝试从插件加载的特定 ZCML 文件，以便可以在三个 ZCML 文件中拆分元数据、配置和覆盖的加载。您可以指定如下文件：<includePlugins package="." file="silly.zcml" />。

• 提供单独的 includePluginsOverrides 指令用于加载覆盖，不再在默认情况下使用 includePlugins 查找 'overrides.zcml' 文件。

• 删除了已弃用的 autoinclude 和 autoincludeOverrides 指令。

• 允许禁用自动包含 通过设置 os.environ['Z3C_AUTOINCLUDE_PLUGINS_DISABLED'] 和 os.environ['Z3C_AUTOINCLUDE_DEPENDENCIES_DISABLED'] 实现，这可能对测试运行程序或调试会话有用。

有关许多这些更改的背景，请参阅 PLIP #247 讨论。

0.2.2 (2008-04-22)

• 优雅地捕获 namespaceForDottedName 中的 KeyErrors；get_metadata_lines 有时会抛出此错误，尤其是在某些类型的分发中。特别是，一些系统自身的 Python 版本可能被包装在引发此错误的分发中，导致在此修复之前 z3c.autoinclude 的系统相关不可恢复损坏。

0.2.1 (2008-04-21)

• 修复了当基本包的命名空间被其他已安装包扩展时阻止正确包含包的bug。

• 重写了 distributionForPackage 函数。

• 为 includePlugins 和实用函数添加了额外的测试。

• 修复了使 z3c.autoinclude 在嵌套命名空间包的命名空间中查找 ZCML 的bug（例如，如果 x/y/configure.zcml 不正确地位于具有 x.y 命名空间的 x.y.z 包中，则会被包含；这是不正确的。）

0.2 (2008-04-18)

• 添加了新的 includePlugins 指令。

• 将 autoinclude 指令重命名为 includeDependencies。

• 弃用了 autoinclude 指令。

0.1 (2008-02-25)

• 初始公开发布。