Zope Configuration Markup Language (ZCML)

7.1 · active · verified Wed Apr 15

zope.configuration provides the Zope Configuration Markup Language (ZCML), a declarative XML-based configuration system used extensively in the Zope and Plone ecosystems. It allows applications to register components, utilities, and services, defining application behavior and structure through XML directives. The current stable version is 7.1, with releases typically tied to Zope/Plone ecosystem needs and Python compatibility.

Warnings

breaking Python 3.10 or newer is now required. Older Python 3 versions (3.6-3.9) are no longer supported since version 7.0.
Fix: Upgrade your Python environment to 3.10 or a newer compatible version.
gotcha ZCML directives like `factory` and `provides` reference Python objects (classes, interfaces) by dotted names (e.g., `my.package.MyClass`). These objects must be discoverable and importable by Python's module system when ZCML is processed. If ZCML cannot find the referenced module or class, it will raise an `ImportError` or `ConfigurationError`.
Fix: Ensure the Python modules containing your classes/interfaces are correctly installed and on the `sys.path`, or for quickstarts/tests, temporarily add them to `sys.modules` as demonstrated in the quickstart.
gotcha Missing or incorrect namespace declarations (`xmlns`, `xmlns:prefix`) in ZCML files can lead to directives not being recognized or parsing errors. Every ZCML file and every custom directive from another package needs its proper namespace declaration.
Fix: Always include the default Zope namespace (`xmlns="http://namespaces.zope.org/zope"`) and any specific namespaces for directives used from other packages (e.g., `xmlns:browser="http://namespaces.zope.org/browser"`) in your `<configure>` tag or relevant directive tags.
gotcha The order of ZCML configuration matters. Later declarations can override earlier ones, particularly when registering utilities, adapters, or views with the same name/interface/for parameters. This can lead to unexpected behavior if not understood.
Fix: Be mindful of the order in which ZCML files are loaded (e.g., through `include` directives or programmatic loading) and how directives are declared. If you intend to override, ensure the overriding declaration comes after the original.

Install

pip install zope.configuration Install latest version

Imports

xmlconfig
wrong:
```
import zope.configuration.xmlconfig
```
correct:
```
from zope.configuration import xmlconfig
```
While technically correct, direct import is less common; 'from ... import ...' is preferred for specific symbols.

ConfigurationContext

from zope.configuration.config import ConfigurationContext

ConfigurationError

from zope.configuration.exceptions import ConfigurationError

Quickstart

Demonstrates how to load a ZCML string, register a utility (a common use case), and retrieve it using `zope.component`. This example simulates a Python module to allow ZCML to reference classes by dotted name, which is crucial for ZCML's operation. Note: `zope.interface` and `zope.component` are fundamental for ZCML's utility and component registration features.

import sys
from zope.interface import Interface, implementer
from zope.configuration import xmlconfig
from zope.component import getUtility, ComponentLookupError

# --- Step 1: Define an interface and an implementation ---
# These would typically reside in a real Python module.
# For this self-contained quickstart, we simulate a module.
class IMyService(Interface):
    """An interface for a dummy service."""
    def do_something():
        """Perform a dummy action."""

@implementer(IMyService)
class MyService:
    """A simple implementation of IMyService."""
    def do_something(self):
        return "Service action complete from ZCML!"

# Simulate a module for ZCML to find the classes
# In a real application, 'quickstart_module' would be a package with your classes.
class DummyModule:
    IMyService = IMyService
    MyService = MyService
sys.modules['quickstart_module'] = DummyModule

# --- Step 2: Define a ZCML configuration string ---
zcml_content = """
<configure
    xmlns="http://namespaces.zope.org/zope"
    i18n_domain="my.package">

  <utility
      factory="quickstart_module.MyService"
      provides="quickstart_module.IMyService"
      name="my.unique.service"
      />

</configure>
"""

# --- Step 3: Load and process the ZCML configuration ---
try:
    # xmlconfig.string processes the ZCML and registers components
    context = xmlconfig.string(zcml_content)

    # --- Step 4: Verify the utility was registered ---
    service = getUtility(IMyService, name="my.unique.service")
    print(f"Utility loaded successfully. Action: {service.do_something()}")
except ComponentLookupError:
    print("Error: Utility not found after ZCML processing. Check ZCML registration.")
except Exception as e:
    print(f"An error occurred during ZCML loading: {e}")
finally:
    # Clean up the dummy module to avoid side effects in other tests/runs
    if 'quickstart_module' in sys.modules:
        del sys.modules['quickstart_module']

view raw JSON →