# Converter

class asdf.extension.Converter

  Bases: `abc.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.

  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.
  `select_tag`(obj, tags, ctx) | Select the tag to use when converting an object to YAML.
  `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

  abstract 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.

    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.asdf.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.

  select_tag(obj, tags, ctx)

    Select the tag to use when converting an object to YAML. Typically only one tag will be active in a given context, but converters that map one type to many tags must provide logic to choose the appropriate tag.

    Parameters
      obj object

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

      tags list of str

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

      ctx asdf.asdf.SerializationContext

        Context of the current serialization request.

    Returns
      str

        The selected tag. Should be one of the tags passed to this method in the `tags` parameter.

  abstract 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.asdf.SerializationContext

        The context of the current serialization request.

    Returns
      dict or list or str

        The YAML node representation of the object.