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

asdf.exceptions Module

Classes

AsdfConversionWarning	Warning class used for failures to convert data into custom types.
AsdfDeprecationWarning	A warning class to indicate a deprecated feature.
AsdfLazyReferenceError	Indicates that the lazy tree node failed to resolve a reference to an AsdfFile instance.
AsdfManifestURIMismatchWarning	A warning indicaing that an extension registered with a manifest contains a id that does not match the uri of the manifest.
AsdfPackageVersionWarning	A warning indicating a package version mismatch
AsdfProvisionalAPIWarning	Used for provisional features where breaking API changes might be introduced at any point (including minor releases).
AsdfSerializationError	An object failed serialization by asdf and by yaml.
AsdfWarning	The base warning class from which all ASDF warnings should inherit.
DelimiterNotFoundError	Indicates that a delimiter was not found when reading or seeking through a file.
ValidationError(message[, validator, path, ...])	An instance was invalid under a provided schema.

Class Inheritance Diagram

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.

Classes

Compressor()	Abstract base class for plugins that compress binary data.
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.
Extension()	Abstract base class defining an extension to ASDF.
ExtensionManager(extensions)	Wraps a list of extensions and indexes their converters by tag and by Python type.
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.
SerializationContext(version, ...)	Container for parameters of the current (de)serialization.
TagDefinition(tag_uri, *[, schema_uris, ...])	Container for properties of a custom YAML tag.
Validator()	Abstract base class for plugins that handle custom validators in ASDF schemas.

Class Inheritance Diagram

asdf.resource Module

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

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

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

load_yaml(init[, tagged])	Load just the yaml portion of an ASDF file
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.
get_file_type(fd)	Determine the file type of an open GenericFile instance.

Classes

FileType(value[, names, module, qualname, ...])

Enum representing if a file is ASDF, FITS or UNKNOWN.

Class Inheritance Diagram

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)	Deprecated.
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

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.
load_schema(url[, resolver, resolve_references])	Load a schema from the given URL.

asdf.tags.core Package

Classes

AsdfObject([dict])
Constant(value)
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.
NDArrayType(source, shape, dtype, offset, ...)
Stream(shape, dtype[, strides])	Used to put a streamed array into the tree.

asdf.testing.helpers Module

Helpers for writing unit tests of ASDF support.

Functions

format_tag(organization, standard, version, ...)	Format a YAML tag.
roundtrip_object(obj[, version])	Add the specified object to an AsdfFile's tree, write the file to a buffer, then read it back in and return the deserialized object.
yaml_to_asdf(yaml_content[, version])	Given a string of YAML content, adds the extra pre- and post-amble to make it an ASDF file.

asdf.lazy_nodes Module

Objects that act like dict, list, OrderedDict but allow lazy conversion of tagged ASDF tree nodes to custom objects.

Classes

AsdfDictNode([data, af_ref])	An class that acts like a dict.
AsdfListNode([data, af_ref])	An class that acts like a list.
AsdfOrderedDictNode([data, af_ref])	An class that acts like a collections.OrderedDict.

Class Inheritance Diagram