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 an object by wrapping it in a |
|
Get the tag associated with the instance, if there is one. |
Classes
|
Base class of classes that wrap a given object and store a tag with it. |
|
A Python dict with a tag attached. |
|
A Python list with a tag attached. |
|
A Python string with a tag attached. |
Class Inheritance Diagram
asdf.exceptions Module
Classes
Warning class used for failures to convert data into custom types. |
|
A warning class to indicate a deprecated feature. |
|
Indicates that the lazy tree node failed to resolve a reference to an AsdfFile instance. |
|
A warning indicaing that an extension registered with a manifest contains a id that does not match the uri of the manifest. |
|
A warning indicating a package version mismatch |
|
Used for provisional features where breaking API changes might be introduced at any point (including minor releases). |
|
An object failed serialization by asdf and by yaml. |
|
The base warning class from which all ASDF warnings should inherit. |
|
Indicates that a delimiter was not found when reading or seeking through a file. |
|
|
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 a previously created ExtensionManager for the specified extensions, or create and cache one if necessary. |
Classes
Abstract base class for plugins that compress binary data. |
|
Abstract base class for plugins that convert nodes from the parsed YAML tree into custom objects, and vice versa. |
|
|
Proxy that wraps a |
Abstract base class defining an extension to ASDF. |
|
|
Wraps a list of extensions and indexes their converters by tag and by Python type. |
|
Proxy that wraps an extension, provides default implementations of optional methods, and carries additional information on the package that provided the extension. |
|
Extension implementation that reads the extension URI, ASDF Standard requirement, and tag list from a manifest document. |
|
Container for parameters of the current (de)serialization. |
|
Container for properties of a custom YAML tag. |
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
|
Wrapper around a resource mapping that carries additional information on the package that provided the mapping. |
|
A resource mapping that reads resource content from a directory or directory tree. |
|
Wraps multiple resource mappings into a single interface with some friendlier error handling. |
Resource mapping that fetches metaschemas from the jsonschema package. |
Class Inheritance Diagram
asdf.yamlutil Module
Functions
|
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. |
|
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
|
Walking through a tree of objects, calling a given function at each node. |
|
Iterate over all nodes in a tree, in depth-first order. |
|
Modify a tree by walking it with a callback function. |
|
Retrieve the children (and their dict keys or list/tuple indices) of an ASDF tree 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 just the yaml portion of an ASDF file |
|
For a given Numpy array, finds the base array that "owns" the actual data. |
|
For a given URI, return the part without any fragment. |
|
Calculates the amount of extra space to add to a block given the user's request for the amount of extra space. |
|
Determine if a URI matches a URI pattern with possible wildcards. |
|
Given a class or instance of a class, returns a string representing the fully specified path of the class. |
|
Determine the file type of an open GenericFile instance. |
Classes
|
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 a tag into its base and version. |
|
Join the root and version of a tag back together. |
Classes
|
This class adds features to the existing |
This mix-in is required in order to impose the total ordering that we want for |
Class Inheritance Diagram
asdf.schema Module
Functions
|
Validate the given instance (which must be a tagged tree) against the appropriate schema. |
|
For any default values in the schema, add them to the tree if they don't exist. |
|
For any values in the tree that are the same as the default values specified in the schema, remove them from the tree. |
|
Check a given schema to make sure it is valid YAML schema. |
|
Load a schema from the given URL. |
asdf.testing.helpers Module
Helpers for writing unit tests of ASDF support.
Functions
|
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. |
|
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
|
An class that acts like a |
|
An class that acts like a |
|
An class that acts like a |