Package zope :: Package configuration :: Module config
[show private | hide private]
[frames | no frames]

Module zope.configuration.config

Configuration processor

See README.txt.

$Id: config.py,v 1.3 2005/06/24 16:52:27 nyergler Exp $


Classes
ComplexDirectiveDefinition Handler for defining complex directives
ComplexStackItem Complex stack item
ConfigurationAdapterRegistry Simple adapter registry that manages directives as adapters
ConfigurationContext Mix-in that implements IConfigurationContext
ConfigurationMachine Configuration machine
DirectiveSchema A field that contains a global variable value that must be a schema
DirectivesHandler Handler for the directives directive
GroupingContextDecorator Helper mix-in class for building grouping directives
GroupingStackItem Stack item for a grouping directive
IComplexDirectiveContext  
IDirectiveInfo Information common to all directive definitions have
IDirectivesContext  
IDirectivesInfo Schema for the directives directive
IFullInfo Information that all top-level directives (not subdirectives) have
IProvidesDirectiveInfo Information for a <meta:provides> directive
IStackItem Configuration machine stack items
IStandaloneDirectiveInfo Info for full directives defined outside a directives directives
RootStackItem  
SimpleStackItem Simple stack item

Exceptions
ConfigurationConflictError  
ConfigurationExecutionError An error occurred during execution of a configuration action

Function Summary
  defineGroupingDirective(context, name, schema, handler, namespace, usedIn)
Define a grouping directive
  defineSimpleDirective(context, name, schema, handler, namespace, usedIn)
Define a simple directive
  expand_action(discriminator, callable, args, kw, includepath, info, order)
  noop()
  provides(context, feature)
Declare that a feature is provided in context.
  resolveConflicts(actions)
Resolve conflicting actions
  subdirective(context, name, schema)
  toargs(context, schema, data)
Marshal data to an argument dictionary using a schema
  _bootstrap(context)

Variable Summary
str metans = 'http://namespaces.zope.org/meta'
str testns = 'http://namespaces.zope.org/test'
str zopens = 'http://namespaces.zope.org/zope'

Function Details

defineGroupingDirective(context, name, schema, handler, namespace='', usedIn=<InterfaceClass zope.configuration.interfaces.IConfigurat...)

Define a grouping directive

Define and register a factory that sets up a grouping directive.

If the namespace is '*', the directive is registered for all namespaces.

for example:

>>> context = ConfigurationMachine()
>>> from zope.configuration.tests.directives import f
>>> class Ixy(Interface):
...    x = zope.schema.TextLine()
...    y = zope.schema.TextLine()

We won't bother creating a special grouping directive class. We'll just use GroupingContextDecorator, which simply sets up a grouping context that has extra attributes defined by a schema:

>>> defineGroupingDirective(context, 'g', Ixy,
...                         GroupingContextDecorator, testns)
>>> context.begin((testns, "g"), x=u"vx", y=u"vy")
>>> context.stack[-1].context.x
u'vx'
>>> context.stack[-1].context.y
u'vy'
>>> context(('http://www.zope.com/t1', "g"), x=u"vx", y=u"vy")
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com/t1', 'g')
>>> context = ConfigurationMachine()
>>> defineGroupingDirective(context, 'g', Ixy,
...                         GroupingContextDecorator, "*")
>>> context.begin(('http://www.zope.com/t1', "g"), x=u"vx", y=u"vy")
>>> context.stack[-1].context.x
u'vx'
>>> context.stack[-1].context.y
u'vy'

defineSimpleDirective(context, name, schema, handler, namespace='', usedIn=<InterfaceClass zope.configuration.interfaces.IConfigurat...)

Define a simple directive

Define and register a factory that invokes the simple directive and returns a new stack item, which is always the same simple stack item.

If the namespace is '*', the directive is registered for all namespaces.

for example:

>>> context = ConfigurationMachine()
>>> from zope.configuration.tests.directives import f
>>> class Ixy(Interface):
...    x = zope.schema.TextLine()
...    y = zope.schema.TextLine()
>>> def s(context, x, y):
...    context.action(('s', x, y), f)
>>> defineSimpleDirective(context, 's', Ixy, s, testns)
>>> context((testns, "s"), x=u"vx", y=u"vy")
>>> context.actions
[(('s', u'vx', u'vy'), f)]
>>> context(('http://www.zope.com/t1', "s"), x=u"vx", y=u"vy")
Traceback (most recent call last):
...
ConfigurationError: ('Unknown directive', 'http://www.zope.com/t1', 's')
>>> context = ConfigurationMachine()
>>> defineSimpleDirective(context, 's', Ixy, s, "*")
>>> context(('http://www.zope.com/t1', "s"), x=u"vx", y=u"vy")
>>> context.actions
[(('s', u'vx', u'vy'), f)]

provides(context, feature)

Declare that a feature is provided in context.

>>> c = ConfigurationContext()
>>> provides(c, 'apidoc')
>>> c.hasFeature('apidoc')
True

Spaces are not allowed in feature names (this is reserved for providing many features with a single directive in the futute).

>>> provides(c, 'apidoc onlinehelp')
Traceback (most recent call last):
  ...
ValueError: Only one feature name allowed
>>> c.hasFeature('apidoc onlinehelp')
False

resolveConflicts(actions)

Resolve conflicting actions

Given an actions list, identify and try to resolve conflicting actions. Actions conflict if they have the same non-null discriminator. Conflicting actions can be resolved if the include path of one of the actions is a prefix of the includepaths of the other conflicting actions and is unequal to the include paths in the other conflicting actions.

Here are some examples to illustrate how this works:

>>> from zope.configuration.tests.directives import f
>>> from pprint import PrettyPrinter
>>> pprint=PrettyPrinter(width=60).pprint
>>> pprint(resolveConflicts([
...    (None, f),
...    (1, f, (1,), {}, (), 'first'),
...    (1, f, (2,), {}, ('x',), 'second'),
...    (1, f, (3,), {}, ('y',), 'third'),
...    (4, f, (4,), {}, ('y',), 'should be last', 99999),
...    (3, f, (3,), {}, ('y',)),
...    (None, f, (5,), {}, ('y',)),
... ]))
[(None, f),
 (1, f, (1,), {}, (), 'first'),
 (3, f, (3,), {}, ('y',)),
 (None, f, (5,), {}, ('y',)),
 (4, f, (4,), {}, ('y',), 'should be last')]
>>> try:
...     v = resolveConflicts([
...        (None, f),
...        (1, f, (2,), {}, ('x',), 'eek'),
...        (1, f, (3,), {}, ('y',), 'ack'),
...        (4, f, (4,), {}, ('y',)),
...        (3, f, (3,), {}, ('y',)),
...        (None, f, (5,), {}, ('y',)),
...     ])
... except ConfigurationConflictError, v:
...    pass
>>> print v
Conflicting configuration actions
  For: 1
    eek
    ack

toargs(context, schema, data)

Marshal data to an argument dictionary using a schema

Names that are python keywords have an underscore added as a suffix in the schema and in the argument list, but are used without the underscore in the data.

The fields in the schema must all implement IFromUnicode.

All of the items in the data must have corresponding fields in the schema unless the schema has a true tagged value named 'keyword_arguments'.

Here's an example:

>>> from zope import schema
>>> class schema(Interface):
...     in_ = zope.schema.Int(constraint=lambda v: v > 0)
...     f = zope.schema.Float()
...     n = zope.schema.TextLine(min_length=1, default=u"rob")
...     x = zope.schema.BytesLine(required=False)
...     u = zope.schema.URI()
>>> context = ConfigurationMachine()
>>> from pprint import PrettyPrinter
>>> pprint=PrettyPrinter(width=50).pprint
>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org' }))
{'f': 1.2,
 'in_': 1,
 'n': u'bob',
 'u': 'http://www.zope.org',
 'x': 'x.y.z'}

If we have extra data, we'll get an error:

>>> toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'})
Traceback (most recent call last):
...
ConfigurationError: ('Unrecognized parameters:', 'a')

Unless we set a tagged value to say that extra arguments are ok:

>>> schema.setTaggedValue('keyword_arguments', True)
>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': u'1',
 'f': 1.2,
 'in_': 1,
 'n': u'bob',
 'u': 'http://www.zope.org',
 'x': 'x.y.z'}

If we ommit required data we get an error telling us what was omitted:

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z'}))
Traceback (most recent call last):
...
ConfigurationError: ('Missing parameter:', 'u')

Although we can omit not-required data:

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2', 'n': u'bob',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': u'1',
 'f': 1.2,
 'in_': 1,
 'n': u'bob',
 'u': 'http://www.zope.org'}

And we can ommit required fields if they have valid defaults (defaults that are valid values):

>>> pprint(toargs(context, schema,
...        {'in': u'1', 'f': u'1.2',
...          'u': u'http://www.zope.org', 'a': u'1'}))
{'a': u'1',
 'f': 1.2,
 'in_': 1,
 'n': u'rob',
 'u': 'http://www.zope.org'}

We also get an error if any data was invalid:

>>> pprint(toargs(context, schema,
...        {'in': u'0', 'f': u'1.2', 'n': u'bob', 'x': u'x.y.z',
...          'u': u'http://www.zope.org', 'a': u'1'}))
Traceback (most recent call last):
...
ConfigurationError: ('Invalid value for', 'in', '0')

Variable Details

metans

Type:
str
Value:
'http://namespaces.zope.org/meta'                                      

testns

Type:
str
Value:
'http://namespaces.zope.org/test'                                      

zopens

Type:
str
Value:
'http://namespaces.zope.org/zope'                                      

Generated by Epydoc 2.1 on Fri Jun 24 12:01:22 2005 http://epydoc.sf.net