Skip to content

Commit

Permalink
Unify docs for xmlconfig.rst/py back into .py
Browse files Browse the repository at this point in the history
  • Loading branch information
@jamadden
jamadden committed Sep 27, 2018
1 parent 1b73d33 commit 8da1212
Show file tree
Hide file tree
Showing 3 changed files with 171 additions and 224 deletions.
9 changes: 4 additions & 5 deletions docs/api/exceptions.rst
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
:mod:`zope.configuration.exceptions`
====================================
===============================
zope.configuration.exceptions
===============================

.. module:: zope.configuration.exceptions

.. autoclass:: ConfigurationError
.. automodule:: zope.configuration.exceptions
214 changes: 4 additions & 210 deletions docs/api/xmlconfig.rst
View file
Original file line number Diff line number Diff line change
@@ -1,211 +1,5 @@
:mod:`zope.configuration.xmlconfig`
===================================
==============================
zope.configuration.xmlconfig
==============================

.. module:: zope.configuration.xmlconfig

.. autoclass:: ZopeXMLConfigurationError

Example

.. doctest::

>>> from zope.configuration.xmlconfig import ZopeXMLConfigurationError
>>> v = ZopeXMLConfigurationError("blah", AttributeError, "xxx")
>>> print(v)
'blah'
AttributeError: xxx

.. autoclass:: ZopeSAXParseException

Example

.. doctest::

>>> from zope.configuration.xmlconfig import ZopeSAXParseException
>>> v = ZopeSAXParseException("foo.xml:12:3:Not well formed")
>>> print(v)
File "foo.xml", line 12.3, Not well formed

.. autoclass:: ParserInfo
:members:
:member-order: bysource

Example

.. doctest::

>>> from zope.configuration.xmlconfig import ParserInfo
>>> info = ParserInfo('tests//sample.zcml', 1, 0)
>>> info
File "tests//sample.zcml", line 1.0

>>> print(info)
File "tests//sample.zcml", line 1.0

>>> info.characters("blah\\n")
>>> info.characters("blah")
>>> info.text
'blah\\nblah'

>>> info.end(7, 0)
>>> info
File "tests//sample.zcml", line 1.0-7.0

>>> print(info)
File "tests//sample.zcml", line 1.0-7.0
<configure xmlns='http://namespaces.zope.org/zope'>
<!-- zope.configure -->
<directives namespace="http://namespaces.zope.org/zope">
<directive name="hook" attributes="name implementation module"
handler="zope.configuration.metaconfigure.hook" />
</directives>
</configure>

.. autoclass:: ConfigurationHandler

.. automethod:: evaluateCondition

The ``have`` and ``not-have`` verbs each take one argument: the name
of a feature:

.. doctest::

>>> from zope.configuration.config import ConfigurationContext
>>> from zope.configuration.xmlconfig import ConfigurationHandler
>>> context = ConfigurationContext()
>>> context.provideFeature('apidoc')
>>> c = ConfigurationHandler(context, testing=True)
>>> c.evaluateCondition("have apidoc")
True
>>> c.evaluateCondition("not-have apidoc")
False
>>> c.evaluateCondition("have onlinehelp")
False
>>> c.evaluateCondition("not-have onlinehelp")
True

Ill-formed expressions raise an error:

.. doctest::

>>> c.evaluateCondition("want apidoc")
Traceback (most recent call last):
...
ValueError: Invalid ZCML condition: 'want apidoc'

>>> c.evaluateCondition("have x y")
Traceback (most recent call last):
...
ValueError: Only one feature allowed: 'have x y'

>>> c.evaluateCondition("have")
Traceback (most recent call last):
...
ValueError: Feature name missing: 'have'


The ``installed`` and ``not-installed`` verbs each take one argument:
the dotted name of a pacakge.

If the pacakge is found, in other words, can be imported,
then the condition will return true / false:

.. doctest::

>>> context = ConfigurationContext()
>>> c = ConfigurationHandler(context, testing=True)
>>> c.evaluateCondition('installed zope.interface')
True
>>> c.evaluateCondition('not-installed zope.interface')
False
>>> c.evaluateCondition('installed zope.foo')
False
>>> c.evaluateCondition('not-installed zope.foo')
True

Ill-formed expressions raise an error:

.. doctest::

>>> c.evaluateCondition("installed foo bar")
Traceback (most recent call last):
...
ValueError: Only one package allowed: 'installed foo bar'

>>> c.evaluateCondition("installed")
Traceback (most recent call last):
...
ValueError: Package name missing: 'installed'

.. autofunction:: processxmlfile

.. autofunction:: openInOrPlain

For example, the tests/samplepackage dirextory has files:

- configure.zcml
- configure.zcml.in
- foo.zcml.in

If we open configure.zcml, we'll get that file:

.. doctest::

>>> import os
>>> from zope.configuration.xmlconfig import __file__
>>> from zope.configuration.xmlconfig import openInOrPlain
>>> here = os.path.dirname(__file__)
>>> path = os.path.join(here, 'tests', 'samplepackage', 'configure.zcml')
>>> f = openInOrPlain(path)
>>> f.name[-14:]
'configure.zcml'
>>> f.close()

But if we open foo.zcml, we'll get foo.zcml.in, since there isn't a
foo.zcml:

.. doctest::

>>> path = os.path.join(here, 'tests', 'samplepackage', 'foo.zcml')
>>> f = openInOrPlain(path)
>>> f.name[-11:]
'foo.zcml.in'
>>> f.close()

Make sure other IOErrors are re-raised. We need to do this in a
try-except block because different errors are raised on Windows and
on Linux.

.. doctest::

>>> try:
... f = openInOrPlain('.')
... except IOError:
... print("passed")
... else:
... print("failed")
passed

.. autointerface:: IInclude
:members:
:member-order: bysource

.. autofunction:: include

.. autofunction:: exclude

.. autofunction:: includeOverrides

.. autofunction:: registerCommonDirectives

.. autofunction:: file

.. autofunction:: string

.. autoclass:: XMLConfig
:members:
:member-order: bysource

.. autofunction:: xmlconfig

.. autofunction:: testxmlconfig
.. automodule:: zope.configuration.xmlconfig
Loading

0 comments on commit 8da1212

Please sign in to comment.