Filtering and Inhibiting Configuration
======================================

The ``exclude`` standard directive is provided for inhibiting unwanted
configuration. It is used to exclude processing of configuration files.
It is useful when including a configuration that includes some other
configuration that you don't want.

It must be used BEFORE including the files to be excluded.

First, let's look at an example.  The zope.configuration.tests.excludedemo
package has a ZCML configuration that includes some other configuration files.

We'll set a log handler so we can see what's going on:

    >>> import logging, sys
    >>> logger = logging.getLogger('config')
    >>> oldlevel = logger.level
    >>> logger.setLevel(logging.DEBUG)
    >>> handler = logging.StreamHandler(sys.stdout)
    >>> logger.addHandler(handler)
 
Now, we'll include the zope.configuration.tests.excludedemo config:

    >>> from zope.configuration import xmlconfig
    >>> _ = xmlconfig.string('<include package="zope.configuration.tests.excludedemo" />')
    include /zope.configuration/src/zope/configuration/tests/excludedemo/configure.zcml
    include /zope.configuration/src/zope/configuration/tests/excludedemo/sub/configure.zcml
    include /zope.configuration/src/zope/configuration/tests/excludedemo/spam.zcml

Each run of the configuration machinery runs with fresh state, so
rerunning gives the same thing:

    >>> _ = xmlconfig.string('<include package="zope.configuration.tests.excludedemo" />')
    include /zope.configuration/src/zope/configuration/tests/excludedemo/configure.zcml
    include /zope.configuration/src/zope/configuration/tests/excludedemo/sub/configure.zcml
    include /zope.configuration/src/zope/configuration/tests/excludedemo/spam.zcml

Now, we'll use the exclude directive to exclude the two files included
by the configuration file in zope.configuration.tests.excludedemo:

    >>> _ = xmlconfig.string(
    ... '''
    ... <configure  xmlns="http://namespaces.zope.org/zope">
    ...   <exclude package="zope.configuration.tests.excludedemo.sub" />
    ...   <exclude package="zope.configuration.tests.excludedemo" file="spam.zcml" />
    ...   <include package="zope.configuration.tests.excludedemo" />
    ... </configure>
    ... ''')
    include /zope.configuration/src/zope/configuration/tests/excludedemo/configure.zcml
    

.. cleanup

    >>> logger.setLevel(oldlevel)
    >>> logger.removeHandler(handler)