aglyph.context — Defining component contexts — Aglyph 3.0.0 documentation

# `aglyph.context` — Defining component contexts

Release: | 3.0.0

The classes in this module are used to define collections (“contexts”) of related components and templates.

A context can be created in pure Python using 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 like a partial function to lazily evaluate component initialization arguments and attributes)
- `aglyph.context.Context` or a subclass

New in version 3.0.0: For easier programmatic configuration, refer to The Aglyph Context fluent API.

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.

class `aglyph.context.` `Context`(context_id, after_inject=None, before_clear=None)

  Bases: `dict`, `aglyph.context._ContextBuilder`

  A mapping of unique IDs to `Component` and `Template` objects.

  Parameters: | context_id (str) – an identifier 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

  `register`(definition)

    Add a component or template definition to this context.

    Parameters: | definition – a `Component` or `Template` object
    Raises: | AglyphError – if a component or template with the same unique ID is already registered in this context

    Note

    To replace an already-registered component or template with the same unique ID, use `dict.__setitem__()` directly.

  `get_component`(component_id)

    Return the `Component` identified by component_id.

    Parameters: | component_id (str) – a unique ID that identifies a `Component`
    Returns: | the `Component` identified by component_id
    Return type: | `Component` if component_id is mapped, else `None`

  `iter_components`(strategy=None)

    Yield all definitions in this context that are instances of `Component`, optionally filtered by strategy.

    Parameters: | strategy (str) – only yield component definitions that use this assembly strategy (by default, all component definitions are yielded)
    Returns: | a `Component` generator

  `borg`(component_id_spec, parent=None)

    Return a `borg` `Component` builder for a component identified by component_id_spec.

    Parameters: | component_id_spec – a context-unique identifier for this component; or the object whose dotted name will identify this component parent – the context-unique identifier for this component’s parent template or component definition; or the object whose dotted name identifies this component’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

  `component`(component_id_spec, parent=None)

    Return a fluent `Component` builder for component_id_spec.

    Parameters: | component_id_spec – a context-unique identifier for this component; or the object whose dotted name will identify this component parent – the context-unique identifier for this component’s parent template or component definition; or the object whose dotted name identifies this component’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

  `prototype`(component_id_spec, parent=None)

    Return a `prototype` `Component` builder for a component identified by component_id_spec.

    Parameters: | component_id_spec – a context-unique identifier for this component; or the object whose dotted name will identify this component parent – the context-unique identifier for this component’s parent template or component definition; or the object whose dotted name identifies this component’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

  `singleton`(component_id_spec, parent=None)

    Return a `singleton` `Component` builder for a component identified by component_id_spec.

    Parameters: | component_id_spec – a context-unique identifier for this component; or the object whose dotted name will identify this component parent – the context-unique identifier for this component’s parent template or component definition; or the object whose dotted name identifies this component’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

  `template`(template_id_spec, parent=None)

    Return a `Template` builder for a template identified by template_spec.

    Parameters: | template_id_spec – a context-unique identifier for this template; or the object whose dotted name will identify this template parent – the context-unique identifier for this template’s parent template or component definition; or the object whose dotted name identifies this template’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

  `weakref`(component_id_spec, parent=None)

    Return a `weakref` `Component` builder for a component identified by component_id_spec.

    Parameters: | component_id_spec – a context-unique identifier for this component; or the object whose dotted name will identify this component parent – the context-unique identifier for this component’s parent template or component definition; or the object whose dotted name identifies this component’s parent definition

    New in version 3.0.0: This method is an entry point into The Aglyph Context fluent API.

class `aglyph.context.` `XMLContext`(source, parser=None, default_encoding='utf-8')

  Bases: `aglyph.context.Context`

  A mapping of unique IDs to `Component` and `Template` 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
  Raises: | AglyphError – if unexpected elements are encountered, or if expected elements are not encountered, in the document structure

  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 of `sys.getdefaultencoding()`. This is not related to the document encoding!

  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.

  An `AglyphError` will be raised under certain conditions (an unexpected element is encounted, or an expected element is not encountered), but Aglyph does not “reinvent the wheel” by implementing strict validation in the parsing logic.

  Warning

  Although Aglyph contexts are `dict` types, `XMLContext` does not permit the same unique ID to be (re-)mapped multiple times.

  Attempting to define more than one `<component>` or `<template>` with the same ID will raise `AglyphError` when the document is parsed.

  After an Aglyph `<context>` document has been successfully parsed, a unique component or template ID can be re-mapped using standard `dict` protocols.

  See also

  Validity constraint: ID
    https://www.w3.org/TR/REC-xml/#id
  `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!