Developer API

The classes and functions documented here will be of use to developers who wish to create their own custom ASDF types and extensions.

asdf.types Module

Functions

format_tag(organization, standard, version, ...)

Format a YAML tag.

Classes

CustomType()

Base class for all user-defined types.

AsdfType()

Base class for all built-in ASDF types.

ExtensionType()

The base class of all custom types in the tree.

Class Inheritance Diagram

Inheritance diagram of asdf.types.CustomType, asdf.types.AsdfType, asdf.types.ExtensionType

asdf.tagged Module

This file manages a transient representation of the tree made up of simple Python data types (lists, dicts, scalars) wrapped inside of Tagged subclasses, which add a tag attribute to hold the associated YAML tag.

Below “basic data types” refers to the basic built-in data types defined in the core YAML specification. “Custom data types” are specialized tags that are added by ASDF or third-parties that are not in the YAML specification.

When YAML is loaded from disk, we want to first validate it using JSON schema, which only understands basic Python data types, not the Nodes that pyyaml uses as its intermediate representation. However, basic Python data types do not preserve the tag information from the YAML file that we need later to convert elements to custom data types. Therefore, the approach here is to wrap those basic types inside of Tagged objects long enough to run through the jsonschema validator, and then convert to custom data types and throwing away the tag annotations in the process.

Upon writing, the custom data types are first converted to basic Python data types wrapped in Tagged objects. The tags assigned to the Tagged objects are then used to write tags to the YAML file.

All of this is an implementation detail of the our custom YAML loader and dumper (yamlutil.AsdfLoader and yamlutil.AsdfDumper) and is not intended to be exposed to the end user.

Functions

tag_object(tag, instance[, ctx])

Tag an object by wrapping it in a Tagged instance.

get_tag(instance)

Get the tag associated with the instance, if there is one.

Classes

Tagged()

Base class of classes that wrap a given object and store a tag with it.

TaggedDict([data, tag])

A Python dict with a tag attached.

TaggedList([data, tag])

A Python list with a tag attached.

TaggedString(seq)

A Python string with a tag attached.

Class Inheritance Diagram

Inheritance diagram of asdf.tagged.Tagged, asdf.tagged.TaggedDict, asdf.tagged.TaggedList, asdf.tagged.TaggedString

asdf.extension Package

Support for plugins that extend asdf to serialize additional custom types.

Functions

get_cached_extension_manager(extensions)

Get a previously created ExtensionManager for the specified extensions, or create and cache one if necessary.

get_default_resolver()

Get the resolver that includes mappings from all installed extensions.

get_cached_asdf_extension_list(extensions)

Get a previously created AsdfExtensionList for the specified extensions, or create and cache one if necessary.

Classes

Extension()

Abstract base class defining an extension to ASDF.

ExtensionProxy(delegate[, package_name, ...])

Proxy that wraps an extension, provides default implementations of optional methods, and carries additional information on the package that provided the extension.

ManifestExtension(manifest, *[, ...])

Extension implementation that reads the extension URI, ASDF Standard requirement, and tag list from a manifest document.

ExtensionManager(extensions)

Wraps a list of extensions and indexes their converters by tag and by Python type.

TagDefinition(tag_uri, *[, schema_uris, ...])

Container for properties of a custom YAML tag.

Converter()

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

ConverterProxy(delegate, extension)

Proxy that wraps a Converter and provides default implementations of optional methods.

Compressor()

Abstract base class for plugins that compress binary data.

AsdfExtension()

Abstract base class defining a (legacy) extension to ASDF.

AsdfExtensionList(extensions)

Manage a set of extensions that are in effect.

BuiltinExtension()

This is the "extension" to ASDF that includes all the built-in tags.

Class Inheritance Diagram

Inheritance diagram of asdf.extension._extension.Extension, asdf.extension._extension.ExtensionProxy, asdf.extension._manifest.ManifestExtension, asdf.extension._manager.ExtensionManager, asdf.extension._tag.TagDefinition, asdf.extension._converter.Converter, asdf.extension._converter.ConverterProxy, asdf.extension._compressor.Compressor, asdf.extension._legacy.AsdfExtension, asdf.extension._legacy.AsdfExtensionList, asdf.extension._legacy.BuiltinExtension

asdf.resource Module

Support for plugins that provide access to resources such as schemas.

Functions

get_json_schema_resource_mappings()

Classes

ResourceMappingProxy(delegate[, ...])

Wrapper around a resource mapping that carries additional information on the package that provided the mapping.

DirectoryResourceMapping(root, uri_prefix[, ...])

A resource mapping that reads resource content from a directory or directory tree.

ResourceManager(resource_mappings)

Wraps multiple resource mappings into a single interface with some friendlier error handling.

JsonschemaResourceMapping()

Resource mapping that fetches metaschemas from the jsonschema package.

Class Inheritance Diagram

Inheritance diagram of asdf.resource.ResourceMappingProxy, asdf.resource.DirectoryResourceMapping, asdf.resource.ResourceManager, asdf.resource.JsonschemaResourceMapping

asdf.yamlutil Module

Functions

custom_tree_to_tagged_tree(tree, ctx[, ...])

Convert a tree, possibly containing custom data types that aren't directly representable in YAML, to a tree of basic data types, annotated with tags.

tagged_tree_to_custom_tree(tree, ctx[, ...])

Convert a tree containing only basic data types, annotated with tags, to a tree containing custom data types.

asdf.treeutil Module

Utility functions for managing tree-like data structures.

Functions

walk(top, callback)

Walking through a tree of objects, calling a given function at each node.

iter_tree(top)

Iterate over all nodes in a tree, in depth-first order.

walk_and_modify(top, callback[, ...])

Modify a tree by walking it with a callback function.

get_children(node)

Retrieve the children (and their dict keys or list/tuple indices) of an ASDF tree node.

is_container(node)

Determine if an ASDF tree node is an instance of a "container" type (i.e., value may contain child nodes).

asdf.util Module

Functions

human_list(line[, separator])

Formats a list for human readability.

get_array_base(arr)

For a given Numpy array, finds the base array that "owns" the actual data.

get_base_uri(uri)

For a given URI, return the part without any fragment.

filepath_to_url(path)

For a given local file path, return a file:// url.

iter_subclasses(cls)

Returns all subclasses of a class.

calculate_padding(content_size, pad_blocks, ...)

Calculates the amount of extra space to add to a block given the user's request for the amount of extra space.

resolve_name(name)

Resolve a name like module.object to an object and return it.

is_primitive(value)

Determine if a value is an instance of a "primitive" type.

uri_match(pattern, uri)

Determine if a URI matches a URI pattern with possible wildcards.

get_class_name(obj[, instance])

Given a class or instance of a class, returns a string representing the fully specified path of the class.

asdf.versioning Module

This module deals with things that change between different versions of the ASDF spec.

Functions

split_tag_version(tag)

Split a tag into its base and version.

join_tag_version(name, version)

Join the root and version of a tag back together.

Classes

AsdfVersion(version)

This class adds features to the existing Version class from the semantic_version module.

AsdfSpec(*args, **kwargs)

AsdfVersionMixin()

This mix-in is required in order to impose the total ordering that we want for AsdfVersion, rather than accepting the total ordering that is already provided by Version from semantic_version.

Class Inheritance Diagram

Inheritance diagram of asdf.versioning.AsdfVersion, asdf.versioning.AsdfSpec, asdf.versioning.AsdfVersionMixin

asdf.schema Module

Functions

validate(instance[, ctx, schema, ...])

Validate the given instance (which must be a tagged tree) against the appropriate schema.

fill_defaults(instance, ctx[, reading])

For any default values in the schema, add them to the tree if they don't exist.

remove_defaults(instance, ctx)

For any values in the tree that are the same as the default values specified in the schema, remove them from the tree.

check_schema(schema[, validate_default])

Check a given schema to make sure it is valid YAML schema.

asdf.tags.core Package

Classes

AsdfObject

Software

HistoryEntry

ExtensionMetadata

SubclassMetadata

The tagged object supported by this class is part of an experimental feature that has since been dropped from this library.

ConstantType()

NDArrayType(source, shape, dtype, offset, ...)

ComplexType()

Class Inheritance Diagram

Inheritance diagram of asdf.tags.core.AsdfObject, asdf.tags.core.Software, asdf.tags.core.HistoryEntry, asdf.tags.core.ExtensionMetadata, asdf.tags.core.SubclassMetadata, asdf.tags.core.constant.ConstantType, asdf.tags.core.ndarray.NDArrayType, asdf.tags.core.complex.ComplexType

asdf.tests.helpers Module

Functions

get_test_data_path(name[, module])

assert_tree_match(old_tree, new_tree[, ctx, ...])

Assert that two ASDF trees match.

assert_roundtrip_tree(*args, **kwargs)

Assert that a given tree saves to ASDF and, when loaded back, the tree matches the original tree.

yaml_to_asdf(yaml_content[, yaml_headers, ...])

Given a string of YAML content, adds the extra pre- and post-amble to make it an ASDF file.

get_file_sizes(dirname)

Get the file sizes in a directory.

display_warnings(_warnings)

Return a string that displays a list of unexpected warnings