ASDF Astropy Serialization Support

0.11.0 · active · verified Thu Apr 16

asdf-astropy is an extension library that provides ASDF (Advanced Scientific Data Format) serialization support for various Astropy objects. It allows for portable, hierarchical, and human-readable representation of data, including astronomical coordinates, units, and models. This package supersedes older ASDF plugins that were built directly into Astropy. The current version is 0.11.0, with releases generally synchronized with major Astropy and ASDF releases.

Common errors

```
Running tests from astropy.test() fails when asdf-astropy is installed #16165
```
cause Conflict or incompatibility in how astropy's internal test runner interacts with the `asdf-astropy` package's test setup, specifically affecting doctests.

fix Use the `pytest` command-line tool to run tests instead of `astropy.test()`. For example: `pytest --pyargs astropy`.
```
asdf.exceptions.ValidationError: tag:stsci.edu:asdf/core/xxx-1.0.0 is not a valid tag
```
cause Attempting to serialize an Astropy object for which `asdf-astropy` does not have a registered converter, or `asdf-astropy` is not correctly installed/loaded. The 'xxx' would be a specific type like 'complex' or a custom Astropy object.

fix Ensure `asdf-astropy` is installed in your environment (`pip install asdf-astropy`). If using custom Astropy-like classes, verify that `asdf-astropy` supports them or consider writing a custom ASDF converter.
```
UserWarning: The plugins in astropy.io.misc.asdf are superseded by asdf-astropy
```
cause This is a warning indicating that you have both the older, built-in Astropy ASDF plugins and `asdf-astropy` installed. `asdf-astropy` takes precedence.

fix This is generally not a critical error, but it signals a deprecated path. Ensure you are relying on `asdf-astropy` for serialization. The `astropy.io.misc.asdf` module will eventually be removed from Astropy, so transition any explicit usage away from it.

Warnings

breaking asdf-astropy 0.11.0 drops support for Python versions older than 3.11. Users on Python 3.8 or 3.10 must upgrade their Python environment to use this version.
Fix: Upgrade Python to 3.11 or newer (`python -m pip install --upgrade python` or via conda/system package manager).
breaking The `astropy.io.misc.asdf` module's functionality is superseded by `asdf-astropy`. When `asdf-astropy` is installed, Astropy's built-in plugins are ignored. The `astropy.io.misc.asdf` module will be removed in a future version of Astropy.
Fix: Ensure `asdf-astropy` is installed and rely on its auto-registered converters rather than explicit imports or usage of `astropy.io.misc.asdf`.
gotcha Running tests directly via `astropy.test()` can fail when `asdf-astropy` is installed, due to conflicts in test discovery or execution. Running `pytest` from the command line, however, typically works correctly.
Fix: Instead of `astropy.test()`, use `pytest` from your terminal (e.g., `pytest --pyargs astropy` or `pytest path/to/astropy/tests`).
gotcha When saving custom Astropy map subclasses to ASDF, they may be loaded back as `sunpy.map.GenericMap` instead of their specific class if the custom subclass is not registered with `sunpy.map.Map` upon loading, or if ASDF is invoked before the custom map sources are imported.
Fix: Ensure all custom Astropy/SunPy map subclasses are imported and registered *before* any ASDF file operations (loading or saving) involving them.

Install

pip install asdf-astropy PyPI

Imports

AsdfFile
```
from asdf import AsdfFile
```
Main class for creating and managing ASDF files.
open
```
from asdf import open
```
Function for loading an ASDF file.
SkyCoord
```
from astropy.coordinates import SkyCoord
```
Example of an Astropy object commonly serialized (no direct asdf-astropy import needed, as plugins auto-register).

Quickstart

This example demonstrates how to create an Astropy `SkyCoord` object, embed it within an ASDF tree, save it to a `.asdf` file, and then load it back. The `asdf-astropy` package automatically registers the necessary converters upon installation, allowing `asdf` to seamlessly handle Astropy types.

import asdf
from astropy.coordinates import SkyCoord
from astropy import units as u

# Create an Astropy object (e.g., a SkyCoord)
coord = SkyCoord(ra=10.68458 * u.deg, dec=41.26917 * u.deg, frame='icrs')

# Create an ASDF tree (a dictionary mapping keys to objects)
tree = {'my_coordinate': coord}

# Create an AsdfFile object
ff = asdf.AsdfFile(tree)

# Save the ASDF tree to a file
file_path = 'my_astropy_coord.asdf'
ff.write_to(file_path)
print(f"Saved SkyCoord to {file_path}")

# Load the ASDF file and access the object
with asdf.open(file_path) as af:
    loaded_coord = af['my_coordinate']
    print(f"Loaded SkyCoord: {loaded_coord}")
    assert loaded_coord == coord

view raw JSON →