Metadata-Version: 2.4
Name: z3c.zcmlhook
Version: 3.1
Summary: Easily hook into the ZCML processing machinery
Author-email: Martin Aspeli <zope-dev@zope.dev>
Maintainer-email: Plone Foundation and contributors <zope-dev@zope.dev>
License-Expression: ZPL-2.1
Project-URL: Source, https://github.com/zopefoundation/z3c.zcmlhook
Project-URL: Issues, https://github.com/zopefoundation/z3c.zcmlhook/issues
Project-URL: Changelog, https://raw.githubusercontent.com/zopefoundation/z3c.zcmlhook/master/CHANGES.rst
Keywords: zope,zcml,hook
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: zope.component
Requires-Dist: zope.interface
Requires-Dist: zope.schema
Requires-Dist: zope.configuration
Provides-Extra: test
Requires-Dist: zope.component[test]; extra == "test"
Dynamic: license-file

Introduction
============

This package provides means of hooking into the Zope (ZCML) configuration
process.

Custom ZCML actions
-------------------

It is sometimes useful to execute a function during the execution of
configuration actions, for example to perform one-off configuration that does
not warrant a new directive. The ``<zcml:customAction />`` directive is
provided for this purpose.

For example, you may want to call a function called
``my.package.finalConfiguration()`` "late" in the configuration action
execution cycle. This can be achieved with the following ZCML statements::

    <configure
        xmlns="http://namespaces.zope.org/zope"
        xmlns:zcml="http://namespaces.zope.org/zcml"
        i18n_domain="my.package">

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

        <zcml:customAction
            handler="my.package.finalConfiguration"
            order="9999"
            />

    </configure>

The ``handler`` attribute gives the name of a function to execute. The
function should take no arguments. The ``order`` attribute is optional, and
can be used to influence when in the configuration cycle the function is
executed. The default value for this, as for most Zope configuration actions,
is ``0``.

Overriding custom actions
-------------------------

If you want to override the invocation of a custom handler in an
``overrides.zcml``, you need to tell ``zope.configuration`` which handler to
override. You can do that by setting the *discriminator* explicitly. A
discriminator is used to uniquely identify a configuration action. In the
case of the ``<zcml:customAction />`` directive, the discriminator is based
on the full dotted name to the function by default. Thus, you could override
the function call above like so::

        <zcml:customAction
            handler="my.otherpackage.overrideFinalConfiguration"
            discriminator="my.package.finalConfiguration"
            order="9999"
            />

Using a handler more than once
------------------------------

The ``discriminator`` attribute can also be used to explicitly allow using
the same handler more than once. If you wanted to call
``my.package.finalConfiguration`` again, you would normally get a
configuration conflict. However, with a (unique) custom discriminator, the
second call is allowed::

        <zcml:customAction
            handler="my.package.finalConfiguration"
            discriminator="my.package.finalConfiguration:early"
            order="-9999"
            />

        <zcml:customAction
            handler="my.package.finalConfiguration"
            discriminator="my.package.finalConfiguration:late"
            order="9999"
            />

Here, we are attempting to call our configuration action "very early" as
well as "very late" in the configuration process.

Changelog
=========

3.1 (2026-09-25)
----------------

- Move package metadata from setup.py to pyproject.toml.

- Add support for Python 3.14.

- Drop support for Python 3.9.


3.0 (2025-04-14)
----------------

- Drop support for ``pkg_resources`` namespace and replace it with PEP 420
  native namespace.


2.1 (2025-03-31)
----------------

- Add support for Python 3.12, 3.13.

- Drop support for Python 3.7, 3.8.


2.0 (2023-02-24)
----------------

- Add support for Python 3.10, 3.11.

- Drop support for Python 2.7, 3.5, 3.6.


1.1 (2021-02-15)
----------------

- Add support for Python 3.5, 3.6, 3.7, 3.8 and 3.9.

- Add test extra to declare test dependency on ``zope.component
  [test]``. [icemac]


1.0b1 (2010-01-02)
------------------

* Initial release
  [optilude]
