Metadata-Version: 2.2
Name: z3c.zcmlhook
Version: 3.0
Summary: Easily hook into the ZCML processing machinery
Home-page: https://github.com/zopefoundation/z3c.zcmlhook
Author: Martin Aspeli
Author-email: zope-dev@zope.dev
License: ZPL
Keywords: zope zcml hook
Classifier: Development Status :: 6 - Mature
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Zope Public License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
License-File: LICENSE.txt
Requires-Dist: setuptools
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: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

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.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]
