aglyph.context — Defining component contexts

The classes in this module are used to define collections of related components (aglyph.component.Component instances), called “contexts” in Aglyph.

A context can be created in pure Python. This approach involves use of the following API classes:

Changed in version 1.1.0: The preferred approach to programmatic configuration is now aglyph.binder.Binder, which is more succinct than using Context and Component directly.

Alternatively, a context can be defined using a declarative XML syntax that conforms to the aglyph-context-1.0.0 DTD (included in the resources/ directory of the distribution). This approach requires only the aglyph.context.XMLContext class, which parses the XML document and then uses the API classes mentioned above to populate the context.

Note

An additional class is needed in IronPython applications that use XML contexts: aglyph.compat.ipyetree.XmlReaderTreeBuilder.

class aglyph.context.Context(context_id)[source]

Bases: dict

A mapping of component IDs to aglyph.componnent.Component objects.

context_id is a string that uniquely identifies this context.

context_id[source]

a read-only property for the context ID

add(component)[source]

Add component to this context.

component is an aglyph.component.Component.

Raises aglyph.AglyphError:
 if component.component_id is already contained in this context
add_or_replace(component)[source]

Add component to this context, replacing any component with the same component_id that already exists.

component is an aglyph.component.Component.

Returns:the component that was replaced
Return type:aglyph.component.Component (or None if no replacement was made)
remove(component_id)[source]

Remove a component from this context.

component is an aglyph.component.Component.

Returns:the component that was removed
Return type:aglyph.component.Component (or None if component.component_id was not in this context)
class aglyph.context.XMLContext(source, parser=None, default_encoding='ascii')[source]

Bases: aglyph.context.Context

Populate a new context by parsing an XML document.

The XML document must conform to the aglyph-context-1.0.0 DTD (included in the resources/ directory of the distribution).

source is a filename or stream from which XML data is read.

parser, if specified, is an ElementTree parser; it is passed as the second argument to xml.etree.ElementTree.ElementTree.parse(). In most cases it is unnecessary to specify a value for parser (as the default works fine on most Python implementations - see the warning below).

default_encoding is the character set used to encode <bytes> or <str> (under Python 2) element content when an @encoding attribute is not specified on those elements. It defaults to sys.getdefaultencoding(). This is not related to the document encoding!

Warning

IronPython developers must specify a parser because the default Python XML parser (expat) is not available in IronPython. Please see aglyph.compat.ipyetree — an ElementTree parser for IronPython.

Note

Aglyph uses a non-validating XML parser by default, so DTD conformance is not enforced at runtime. It is recommended that XML contexts be validated at least once (manually) during testing.

default_encoding[source]

a read-only property for the default encoding

This is not related to the document encoding!

Previous topic

aglyph.component — Defining components and their dependencies

Next topic

aglyph.compat.ipyetree — an ElementTree parser for IronPython

This Page