Package: plone.autoinclude
plone.autoincludeAutomatically include zcml of a package when it is loaded in a Plone site.FeaturesIt is an alternative toz3c.autoinclude.When a package registers an autoinclude entry point, we load its Python code at Zope/Plone startup.And we load its zcml.Works with Buildout-installed packages.Works with pip-installed packages.CompatibilityThis is made for Python 3.6+.
Since Plone 6.0.0a2 it is included in core Plone.
SeePLIP 3339.It also works on Plone 5.2.For add-on authorsWhen you have an existing package that has some zcml, you probably already have something like this in yoursetup.py:entry_points="""
[z3c.autoinclude.plugin]
target = plone
"""or in a dictionary:entry_points={
    "z3c.autoinclude.plugin": [
        "target = plone",
    ],
}or insetup.cfg:[options.entry_points]
z3c.autoinclude.plugin =
    target=ploneThis still works!
You do not need to change anything.But if you do not care about compatibility withz3c.autoinclude, you could use this new entry point:entry_points="""
[plone.autoinclude.plugin]
target = plone
"""It does the same thing, but it only works withplone.autoinclude.Note: you shouldnotaddplone.autoincludein yourinstall_dependencies.
It is the responsibility of the framework (usually Plone) to do this.Entry point detailsThis is an entry point with all options specified:entry_points="""
[plone.autoinclude.plugin]
target = plone
module = example.alternative
"""You must specify at least one option, otherwise the entry point does not exist.targetIn which framework should your zcml be loaded?
For a Plone add-on you would useplone.
If Zope ever wants to use something similar, it could add configuration to look for packages withtarget="zope".
You can come up with targets yourself, and load them in a policy package, maybe: cms, frontend, companyname, customername, nl/de (language).
If target is empty, or the option is not there, the zcml will get loaded by all frameworks.moduleUse this when your package name is different from what you import in Python.
See also the next section.Different project and module nameUsually the project name of an add-on (what is insetup.pyorsetup.cfg) is the same as how you would import it in Python code.
It could be different though.
In that case, you may get aModuleNotFoundErroron startup:plone.autoincludetries to import the project name and this fails.The easiest way to solve this, is to switch fromz3c.autoinclude.plugintoplone.autoinclude.plugin, if you have not done so already,
and specify the module.
Insetup.py:setup(
    name="example.different2",
    entry_points="""
    [plone.autoinclude.plugin]
    module = example.somethingelse2
    """,
)If you must still support Plone 5.2 and are tied toz3c.autoinclude.plugin, or if you cannot edit the problematic package, you can work around it.
You set an environment variableAUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR.
To acceptModuleNotFoundErrorin all packages:export AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=1To acceptModuleNotFoundErroronly in specific packages, use a comma-separated list of project names, with or without spaces:export AUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=example.different,example.different2In the logs you will see a traceback so you can investigate, but startup continues.
You should make sure the zcml of this package is loaded in some other way.Comparison withz3c.autoincludez3c.autoincludesupportsincludeDependenciesin a zcml file in your package.
This would look in thesetup_requiresof the package to find dependencies.
For each, it would load the zcml.
This can take quite long.
It might not work for packages installed bypip, but this is not confirmed.
In the Plone community this is discouraged, and Plone already disables this in the tests.plone.autoincludedoes not support this.
You should load the zcml of the dependencies explicitly in theconfigure.zcmlof your package.z3c.autoincludetries hard to find packages in non-standard places, installed in weird or old ways,
or with a module name that differs from the package name, with code especially suited for eggs that buildout installs.plone.autoincludesimply usesimportlib.import_moduleon the module name.
If there is a mismatch between package name and module name, you can setmodule = modulenamein your entry point.z3c.autoincludedoes not support empty targets.
The target of the entry point must match the target that is being loaded.plone.autoincludedoessupport empty targets: they will always get loaded.
This is not good or bad, it is just a different choice.z3c.autoincludesupports disabling loading the plugins, via either an environment variable or an api call.plone.autoincludedoes not.
ButProducts.CMFPlonecurrently loads thez3c.autoincludeplugins unless a zcml condition is true:not-havedisable-autoinclude.
WhenProducts.CMFPloneswitches toplone.autoinclude, it can use this same condition.In general,plone.autoincludeis a bit more modern, as it only started in 2020, and only supports Python 3.Usage in Plone 5.2Since Plone 6.0.0a2 this is included in core, so nothing needs to be done there.
If you want to use it in Plone 5.2, this is possible.
First add it to your buildout:[instance]
...
eggs +=
    plone.autoinclude
zcml +=
    plone.autoinclude.ploneinclude-meta
    plone.autoinclude.ploneinclude
    plone.autoinclude.ploneinclude-overridesThis will include three zcml files from theploneincludedirectory.
It will do this:Disable the original z3c.autoinclude.Load CMFPlone meta.zcml, so the order in which zcml is loaded stays mostly the same.Load plone.autoinclude meta.zcml.Automatically include the meta.zcml of all plone plugins.Load CMFPlone configure.zcml.Automatically include the configure.zcml of all plone plugins.Load CMFPlone overrides.zcml.Automatically include the overrides.zcml of all plone plugins.For other frameworksYou can take the above section as example, and take care of the followingInclude theplone.autoincludepackage ininstall_requires.In your meta.zcml load the meta.zcml of plone.autoinclude.In your meta.zcml load the meta.zcml of your plugins:<autoIncludePluginstarget="your-framework"file="meta.zcml"/>In your configure.zcml load the configure.zcml of your plugins:<autoIncludePluginstarget="your-framework"file="configure.zcml"/>In your overrides.zcml load the meta.zcml of your plugins in override mode:<autoIncludePluginsOverridestarget="your-framework"file="meta.zcml"/>Installation with pipLet’s leave buildout completely out of the picture and only use pip, in this case with plone 5.2.5.
We use the legacy resolver from pip, to avoid some possible problems that have nothing to do with 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.iniContribute or get supportIf you are having issues, please let us know in the issue tracker:https://github.com/plone/plone.autoinclude/issuesThe source code is on GitHub:https://github.com/plone/plone.autoincludeLicenseThe project is licensed under the GPLv2.Changelog1.0.1 (2022-12-10)Bug fixes:Revert “Use setuptools/pkg_resources regex to compute safe name for a project” to fix an error importing packages with dashes. [davisagli] (#22)1.0.0 (2022-12-01)Bug fixes:Use setuptools/pkg_resources regex to compute safe name for a project.
[gforcada] (#17)1.0.0a5 (2022-05-24)New features:Raise an exception when a module is not found.
When environment variableAUTOINCLUDE_ALLOW_MODULE_NOT_FOUND_ERROR=1is set, we log an error and continue.
To acceptModuleNotFoundErroronly in specific packages, use a comma-separated list of project names, with or without spaces.
Seeissue 19.
[maurits] (#19)1.0.0a4 (2022-02-23)Bug fixes:Replace dash with lowdash in project_name, as Python Project are normally divided by dash and modul name uses lowdash [MrTango] (#16)1.0.0a3 (2021-12-03)Bug fixes:Decrease verbosity when loading packages (#11)1.0.0a2 (2021-10-20)Bug fixes:Improved documentation, especially on how to include this.
Added zcml in a ploneinclude directory to make this easier for now.
[maurits] (#1)1.0.0a1 (2021-10-15)New features:Initial release.
[maurits, tschorr]