aglyph.context
— Defining component contexts¶
Release: | 2.1.1 |
---|
The classes in this module are used to define collections (“contexts”) of related components and templates.
A context can be created in pure Python. This approach involves use of the following API classes:
aglyph.component.Template
aglyph.component.Component
aglyph.component.Reference
(used to indicate that one component depends on another component)aglyph.component.Evaluator
(used as a partial function to lazily evaluate component initialization arguments and attributes)aglyph.context.Context
New in version 1.1.0: aglyph.binder.Binder
offers an alternative approach to
programmatic configuration, which is more succinct than using the
API classes noted above.
Alternatively, a context can be defined using a declarative XML syntax
that conforms to the Aglyph context 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.
Changed in version 2.0.0: IronPython applications that use XML contexts are no longer required to pass an aglyph.compat.ipyetree.XmlReaderTreeBuilder
instance to XMLContext.__init__()
. Aglyph now uses an appropriate default parser based on the current Python implementation.
-
class
aglyph.context.
Context
(context_id, after_inject=None, before_clear=None)[source]¶ Bases:
dict
A mapping of unique IDs to
Component
andTemplate
objects.Parameters: - context_id (str) – a unique ID for this context
- after_inject (str) – specifies the name of the method that will be called (if it exists) on all component objects after all of their dependencies have been injected
- before_clear (str) – specifies the name of the method that will be called (if it exists) on all singleton, borg, and weakref objects immediately before they are cleared from cache
-
context_id
¶ The unique context ID (read-only).
-
after_inject
¶ The name of the component object method that will be called after all dependencies have been injected into that component object.
-
before_clear
¶ The name of the component object method that will be called immediately before the object is cleared from cache.
Warning
This property is not applicable to “prototype” component objects, and is not guaranteed to be called for “weakref” component objects.
-
get_component
(component_id)[source]¶ Return the
Component
identified by component_id.Parameters: component_id (str) – a unique ID that identifies a Component
Returns: the Component
identified by component_idReturn type: Component
if component_id is mapped in this context, elseNone
-
iter_components
()[source]¶ Yield all definitions in this context that are instances of
Component
.Returns: a Component
generator
-
add
(obj)[source]¶ Add obj, which must be a component or template, to this context.
Parameters: obj – the Component
orTemplate
to add to this contextRaises: AglyphError – if obj.unique_id is already mapped Deprecated since version 2.1.0: use the
dict.__contains__()
anddict.__setitem__()
protocols instead.
-
add_or_replace
(obj)[source]¶ Add obj (which must be a component or template) to this context, replacing any component or template with the same ID that is already mapped.
Parameters: obj – the Component
orTemplate
to add to this contextReturns: the component or template that was replaced, or None
if obj.unique_id is not already mappedReturn type: Component
orTemplate
Note
This method will not replace a component with a template or vice-versa; if the object that would be replaced is not the same type as the replacement,
TypeError
is raised.Deprecated since version 2.1.0: use the standard
dict.__setitem__()
protocol instead.
-
remove
(unique_id)[source]¶ Remove the component or template identified by id_ from this context.
Parameters: unique_id (str) – identifies the component or template to remove Returns: the component or template that was removed, or None
if unique_id is not mappedReturn type: Component
orTemplate
Deprecated since version 2.1.0: use the
dict.__contains__()
anddict.__delitem__()
protocols instead.
-
class
aglyph.context.
XMLContext
(source, parser=None, default_encoding='utf-8')[source]¶ Bases:
aglyph.context.Context
A mapping of unique IDs to
Component
andTemplate
objects.Components and templates are declared in an XML document that conforms to the
Aglyph context DTD
(included in the resources/ directory of the distribution).Parameters: - source – a filename or stream from which XML data is read
- parser (xml.etree.ElementTree.XMLParser) – the ElementTree parser to use (instead of Aglyph’s default)
- default_encoding (str) – the default character set used to encode certain element content
In most cases, parser should be left unspecified. Aglyph’s default parser will be sufficient for all but extreme edge cases.
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 the system-dependent value ofsys.getdefaultencoding()
. This is not related to the document encoding!Changed in version 2.0.0: IronPython applications are no longer required to specify a parser. See aglyph.compat.ipyetree — an ElementTree parser for IronPython for more information.
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
¶ The default encoding of
<bytes>
or<str>
(under Python 2) element content when an @encoding attribute is not specified.Note
This is unrelated to the document encoding!