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

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

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 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:

nodedict or list or str

The YAML node to convert.

tagstr

The YAML tag of the object being converted.

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

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:

objobject

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

tagstr

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

ctxasdf.extension.SerializationContext

The context of the current serialization request.

Returns:

dict or list or str

The YAML node representation of the object.