File naming conventions

ZCML configuration for a package should, in general, be placed in a file named configure.zcml. If a package performs meta configuration (defines new configuration directives), the meta configuration should go in a file named meta.zcml. The code that implements the meta configuration directives should (again, in general) go in a file named metaconfiguration.py.

Style guide

The ZCML style guide has been developed with the following qualities in mind:

  • Lines under 80 characters wherever possible

  • Indentation to reflect nesting

  • Ease of maintenance

  • Easy visual scanning through ZCML

Tabs and spaces

All whitespace to be made up of space characters. No chr(9) hard tabs.

Indentation of 2 characters to show nesting, 4 characters to list attributes on separate lines. This distinction makes it easier to see the difference between attributes and nested elements.

Logical sections

If a configuration file has many logical sections, then mark the sections with comments and indent the sections relative to the comments. For example:

<configure xmlns="http://namespaces.zope.org/zope">

  <!-- Configuration registries -->


  <!-- Adapter Service -->

  <content class="zope.app.services.adapter.AdapterService">



Always use the “usual” names for namespaces in the document:

default (no qualification needed)

for http://namespaces.zope.org/zope


for http://namespaces.zope.org/browser


for http://namespaces.zope.org/zmi


for http://namespaces.zope.org/security


for http://namespaces.zope.org/xmlrpc


for http://namespaces.zope.org/whatevername

Only define those namespaces used in the document. This is a similar rule to what imports to use in a Python module.

Opening tags

Close a one-line tag on the same line:

<class class="Foo">

Close a multi-line tag on a new line, at the same level of indentation as the tags attributes:


Empty tags

Close a one-line tag on the same line, insert a space after the last attribute::

<subscriber handler=".foo.OnFoo" />

Close a multi-line tag on a new line at the same level of indentation as the tag’s attributes:


Closing tags

Indent closing tags at the same level of indentation as the opening tags:

<class class=".foo.Foo">


If all the attributes fit on one line with the tag name, do that:

<class class=".foo.Foo">

If all the attribute fit on one line without the tag name, do that on the line after the tag, indented 4 spaces along from the tag:

    name="index.html" class=".foo.Foo" permission="zope.View"

Otherwise, put the first attribute on a new line, and use one line per attribute:


Use double quotes for attributes unless single quotes are needed to enclose double quotes.


Comments should be placed immediately above the declarations they apply to. Keep comments to one line where possible, and open and close the comment on the same line.