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

# 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[, postorder, ...]) | 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
`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.
`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.
`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`(*values) | 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.
`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

`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