Hide navigation sidebar
Hide table of contents sidebar
Skip to content
ASDF Projects Tutorials Community
Back to top
View this page
Toggle table of contents sidebar

# Converter

class asdf.extension.Converter

  Bases: `ABC`

  Abstract base class for plugins that convert nodes from the parsed YAML tree into custom objects, and vice versa.

  Implementing classes must provide the `tags` and `types` properties and `to_yaml_tree` and `from_yaml_tree` methods. The `select_tag` method is optional.

  If implemented, `select_tag` should accept 3 parameters

  > objobject

  >   Instance of the custom type being converted. Guaranteed to be an instance of one of the types listed in the `types` property.

  > tagslist of str

  >   List of active tags to choose from. Guaranteed to match one of the tag patterns listed in the ‘tags’ property.

  > ctxasdf.extension.SerializationContext

  >   Context of the current serialization request.

  and return a str, the selected tag (should be one of tags) or `None` which will trigger the result of `to_yaml_tree` to be used to look up the next converter for this object.

  The `lazy` attribute is optional. If `True` asdf will pass “lazy” objects to the converter. If `False` (or not defined) asdf will convert all child objects before calling `from_yaml_tree`.

  The `to_info` method is optional. If implemented it must accept 1 parameter `obj` which is a tree node/custom object and return a container (list, tuple, dict) containing information about that object to display during ``AsdfFile.info`.

  Attributes Summary

  `tags` | Get the YAML tags that this converter is capable of handling.
  `types` | Get the Python types that this converter is capable of handling.

  Methods Summary

  `from_yaml_tree`(node, tag, ctx) | Convert a YAML node into an instance of a custom type.
  `to_yaml_tree`(obj, tag, ctx) | Convert an object into a node suitable for YAML serialization.

  Attributes Documentation

  tags

    Get the YAML tags that this converter is capable of handling. URI patterns are permitted, see `asdf.util.uri_match` for details.

    Returns:
      iterable of str

        Tag URIs or URI patterns.

  types

    Get the Python types that this converter is capable of handling.

    Returns:
      iterable of str or type

        If str, the fully qualified class name of the type.

  Methods Documentation

  abstractmethod from_yaml_tree(node, tag, ctx)

    Convert a YAML node into an instance of a custom type.

    For container types received by this method (dict or list), the children of the container will have already been converted by prior calls to from_yaml_tree implementations unless `lazy_tree` was set to `True` for `asdf.open`. With a lazy tree the container types will be `asdf.lazy_nodes` (which act like dict or list but convert child objects when accessed).

    Note on circular references: trees that reference themselves among their descendants must be handled with care. Most implementations need not concern themselves with this case, but if the custom type supports circular references, then the implementation of this method will need to return a generator. Consult the documentation for more details.

    Parameters:
      node dict or list or str

        The YAML node to convert.

      tag str

        The YAML tag of the object being converted.

      ctx asdf.extension.SerializationContext

        The context of the current deserialization request.

    Returns:
      object

        An instance of one of the types listed in the `types` property, or a generator that yields such an instance.

  abstractmethod to_yaml_tree(obj, tag, ctx)

    Convert an object into a node suitable for YAML serialization. This method is not responsible for writing actual YAML; rather, it converts an instance of a custom type to a built-in Python object type (such as dict, list, str, or number), which can then be automatically serialized to YAML as needed.

    For container types returned by this method (dict or list), the children of the container need not themselves be converted. Any list elements or dict values will be converted by subsequent calls to to_yaml_tree implementations.

    The returned node must be an instance of `dict`, `list`, or `str`. Children may be any type supported by an available Converter.

    Parameters:
      obj object

        Instance of a custom type to be serialized. Guaranteed to be an instance of one of the types listed in the `types` property.

      tag str

        The tag identifying the YAML type that `obj` should be converted into. Selected by a call to this converter’s select_tag method.

      ctx asdf.extension.SerializationContext

        The context of the current serialization request.

    Returns:
      dict or list or str

        The YAML node representation of the object.