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.
Bases: dict
A mapping of component IDs to aglyph.componnent.Component objects.
context_id is a string that uniquely identifies this context.
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 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 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) |
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.