plone.autoinclude 1.0.1

特性

• 这是z3c.autoinclude的替代方案。

• 当一个包注册了自动包含入口点时，我们在Zope/Plone启动时加载其Python代码。

• 并加载其zcml。

• 与Buildout安装的包兼容。

• 与pip安装的包兼容。

兼容性

这是为Python 3.6+制作的。从Plone 6.0.0a2开始，它已包含在核心Plone中。参见PLIP 3339。

它也适用于Plone 5.2。

对于插件作者

当你有一个包含一些zcml的现有包时，你可能在你的setup.py

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

或在一个字典中

entry_points={
    "z3c.autoinclude.plugin": [
        "target = plone",
    ],
}

或在一个setup.cfg

[options.entry_points]
z3c.autoinclude.plugin =
    target=plone

这仍然有效！你不需要做任何更改。

但是，如果你不关心与z3c.autoinclude的兼容性，你可以使用这个新的入口点

entry_points="""
[plone.autoinclude.plugin]
target = plone
"""

它执行相同的功能，但仅与 plone.autoinclude 兼容。

注意：你 不应 在你的 install_dependencies 中添加 plone.autoinclude。这通常是框架（通常是Plone）的责任来执行。

入口点详细信息

这是一个包含所有选项指定的入口点

entry_points="""
[plone.autoinclude.plugin]
target = plone
module = example.alternative
"""

你必须指定至少一个选项，否则入口点不存在。

目标

你的 zcml 应该在哪个框架中加载？对于 Plone 扩展，你会使用 plone。如果 Zope 今后想使用类似的东西，它可以添加配置来查找具有 target="zope" 的包。你可以自己创建目标，并在策略包中加载它们，比如：cms、前端、公司名称、客户名称、nl/de（语言）。如果目标为空，或者没有此选项，则 zcml 将由所有框架加载。

模块

当你的包名与你在 Python 中导入的名称不同时使用此选项。另请参阅下一节。

不同项目和模块名称

通常，扩展的项目名称（在 setup.py 或 setup.cfg 中）与你在 Python 代码中导入的方式相同。但它可能不同。在这种情况下，你可能会在启动时遇到 ModuleNotFoundError：plone.autoinclude 尝试导入项目名称，但失败了。

要解决这个问题，最简单的方法是如果你还没有这样做，从 z3c.autoinclude.plugin 切换到 plone.autoinclude.plugin，并在 setup.py 中指定模块。

setup(
    name="example.different2",
    entry_points="""
    [plone.autoinclude.plugin]
    module = example.somethingelse2
    """,
)

如果你必须继续支持 Plone 5.2 并绑定到 z3c.autoinclude.plugin，或者如果你不能编辑有问题的包，你可以通过设置环境变量 AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR 来解决这个问题。为了接受所有包中的 ModuleNotFoundError

export AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=1

要仅接受特定包中的 ModuleNotFoundError，请使用以逗号分隔的项目名称列表，其中可以有或没有空格

export AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=example.different,example.different2

在日志中，你会看到跟踪回溯，以便你可以进行调查，但启动会继续。你应该确保以其他方式加载此包的 zcml。

与 z3c.autoinclude 的比较

• z3c.autoinclude 支持在你的包中的 zcml 文件中的 includeDependencies。这将在包的 setup_requires 中查找依赖项。对于每个依赖项，它将加载 zcml。这可能需要相当长的时间。它可能不适用于由 pip 安装的包，但这尚未得到证实。在 Plone 社区中，这是不推荐的，Plone 已经在测试中禁用了这个功能。plone.autoinclude 不支持此功能。你应该在包的 configure.zcml 中显式加载依赖项的 zcml。

• z3c.autoinclude 尽力在非标准位置查找包，这些包以奇怪或过时的方式安装，或者模块名称与包名称不同，其代码专门适用于 eggs，由 buildout 安装。而 plone.autoinclude 简单地使用 importlib.import_module 在模块名称上。如果包名称和模块名称不匹配，你可以在入口点中设置 module = modulename。

• z3c.autoinclude 不支持空目标。入口点的目标必须与正在加载的目标匹配。plone.autoinclude 确实 支持空目标：它们将始终被加载。这既不是好也不是坏，只是不同的选择。

• z3c.autoinclude 支持通过环境变量或API调用禁用插件加载。而 plone.autoinclude 不支持。但是，Products.CMFPlone 目前默认加载 z3c.autoinclude 插件，除非满足 zcml 条件：not-have disable-autoinclude。当 Products.CMFPlone 切换到 plone.autoinclude 时，它可以使用相同的条件。

总的来说，plone.autoinclude 比较现代，因为它从 2020 年才开始使用，并且只支持 Python 3。

Plone 5.2 中的使用

从 Plone 6.0.0a2 开始，这被包含在核心中，因此不需要在那里做任何事情。如果您想在 Plone 5.2 中使用它，这是可能的。首先将其添加到您的 buildout 中

[instance]
...
eggs +=
    plone.autoinclude
zcml +=
    plone.autoinclude.ploneinclude-meta
    plone.autoinclude.ploneinclude
    plone.autoinclude.ploneinclude-overrides

这将包含来自 ploneinclude 目录的三个 zcml 文件。它会这样做

• 禁用原始的 z3c.autoinclude。

• 加载 CMFPlone meta.zcml，以便 zcml 加载的顺序保持大致相同。

• 加载 plone.autoinclude meta.zcml。

• 自动包含所有 plone 插件的 meta.zcml。

• 加载 CMFPlone configure.zcml。

• 自动包含所有 plone 插件的 configure.zcml。

• 加载 CMFPlone overrides.zcml。

• 自动包含所有 plone 插件的 overrides.zcml。

对于其他框架

您可以将上述部分作为示例，并注意以下事项

• 在 install_requires 中包含 plone.autoinclude 包。

• 在您的 meta.zcml 中加载 plone.autoinclude 的 meta.zcml。

• 在您的 meta.zcml 中加载您插件的 meta.zcml：<autoIncludePlugins target="your-framework" file="meta.zcml" />

• 在您的 configure.zcml 中加载您插件的 configure.zcml：<autoIncludePlugins target="your-framework" file="configure.zcml" />

• 在您的 overrides.zcml 中以覆盖模式加载您插件的 meta.zcml：<autoIncludePluginsOverrides target="your-framework" file="meta.zcml" />

使用 pip 进行安装

让我们完全排除 buildout，只使用 pip，在这种情况下使用 plone 5.2.5。我们使用 pip 的传统解析器，以避免与 autoinclude 无关的一些可能问题

# Create virtual environment in the current directory:
python3.8 -mvenv .
# Install Plone and Paste:
bin/pip install -c https://dist.plone.org/release/5.2.5/constraints.txt Products.CMFPlone Paste --use-deprecated legacy-resolver
# Install plone.autoinclude from the current git checkout:
bin/pip install -e .
# or 'bin/pip install plone.autoinclude' to get the latest from PyPI.
# Create the Zope WSGI instance:
bin/mkwsgiinstance -d . -u admin:admin
# Copy our zcml that disables z3c.autoinclude and enables our own.
cp -a package-includes etc/
# Start Zope:
bin/runwsgi -v etc/zope.ini

贡献或获取支持

• 如果您遇到问题，请在问题跟踪器中告诉我们：https://github.com/plone/plone.autoinclude/issues

• 源代码在 GitHub 上：https://github.com/plone/plone.autoinclude

许可证

该项目受 GPLv2 许可证许可。

1.0.1 (2022-12-10)

错误修复

• 撤销“使用 setuptools/pkg_resources regex 计算项目的安全名称”以修复导入带短划线包的错误。[davisagli] (#22)

1.0.0 (2022-12-01)

错误修复

• 使用 setuptools/pkg_resources regex 计算项目的安全名称。[gforcada] (#17)

1.0.0a5 (2022-05-24)

新功能

• 当找不到模块时引发异常。当设置环境变量 AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=1 时，我们记录错误并继续。要仅在特定包中接受 ModuleNotFoundError，请使用以逗号分隔的项目名称列表，可带可不带空格。请参阅 问题 19。[maurits] (#19)

1.0.0a4 (2022-02-23)

错误修复

• 将 project_name 中的短划线替换为 lowdash，因为 Python 项目通常由短划线分隔，而模块名使用 lowdash。[MrTango] (#16)

1.0.0a3 (2021-12-03)

错误修复

• 在加载包时降低冗余。[#11]

1.0.0a2 (2021-10-20)

错误修复

• 改进了文档，特别是如何包含此内容的说明。目前通过在ploneinclude目录中添加zcml来简化操作。[maurits] (#1)

1.0.0a1 (2021-10-15)

新功能

• 初始版本。 [maurits, tschorr]