ASDF Python Library

Common errors

• AttributeError: property 'tree' of 'AsdfFile' object has no setter

  cause Attempting to directly replace the entire `AsdfFile.tree` attribute in `asdf` version 5.0 or later.
  fix Use `asdf_file.update(new_dict)` to modify the contents of the tree, or create a new `asdf.AsdfFile` instance if a complete replacement of the tree structure is needed.

• asdf.exceptions.ValidationError: <unknown>: 'tag:stsci.edu:asdf/custom-type-1.0.0' is not a valid ASDF tag.

  cause ASDF cannot find a registered converter for a custom Python object type that was attempted to be serialized or deserialized.
  fix Ensure that the custom type has a corresponding `asdf.extension.Tag` and `asdf.extension.Converter` registered with ASDF. This usually involves defining an `asdf.extension.Extension` and adding it to the ASDF context.

• ValueError: 'r+' is not a supported mode for AsdfFile.open()

  cause Using `mode='r+'` when opening an ASDF file with `asdf.open()` in versions 4.0 or newer.
  fix Remove the `mode='r+'` argument. Open the file in read-only mode (`'r'`), then if modifications are required, load the data, apply changes, and save the updated data to a new ASDF file using `AsdfFile.write_to()`.

Warnings

• breaking The `AsdfFile.tree` attribute is now read-only. Direct assignment like `ff.tree = new_tree` will raise an `AttributeError` in `asdf` 5.0 and later.
  Fix: Instead of reassigning `ff.tree`, use `ff.update(new_dict)` to update the tree's content or create a new `AsdfFile` instance with the modified tree.
• breaking Minimum Python version increased to 3.10. Users on older Python versions will encounter `ImportError` or environment resolution issues.
  Fix: Upgrade your Python environment to version 3.10 or newer. Refer to the official Python documentation for upgrade instructions.
• breaking The `AsdfFile.open()` function no longer supports `mode='r+'` for read-write operations. Using it will raise a `ValueError` in `asdf` 4.0 and later.
  Fix: Open the file in read mode (`'r'`), make any necessary modifications to the loaded data, and then write the data to a new file or overwrite the existing one using `AsdfFile.write_to()`.
• gotcha Custom Python types require explicit registration with ASDF. Without proper registration (via an `Extension`, `Tag`, and `Converter`), ASDF may not be able to serialize/deserialize them correctly, often leading to `ValidationError` or loss of type information.
  Fix: Implement a custom `asdf.extension.Extension` (which typically includes a `Tag` and `Converter`) and register it using `asdf.converters.add_extension` or by installing a package that provides the extension.

Install

• pip install asdf Install core library
• pip install 'asdf[astropy,all]' Install with common optional dependencies

Imports

• AsdfFile
  wrong:

  from asdf.asdffile import AsdfFile

  correct:

  from asdf import AsdfFile

  While technically correct, the top-level import is preferred and canonical.
• open

  import asdf; asdf.open(...)

Quickstart

This quickstart demonstrates how to create a simple ASDF data structure, write it to a file, and then read the data back. It uses a dictionary for the tree structure and includes a NumPy array, a common use case for ASDF.

import asdf
import numpy as np
import os

# Create some data
tree = {
    'scientific_name': 'M42',
    'coordinates': {
        'ra': 83.822083,
        'dec': -5.391111
    },
    'data': np.array([[1, 2], [3, 4]], dtype=np.int64)
}

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

# Define file path
file_path = "example.asdf"

# Write the file
ff.write_to(file_path)

print(f"ASDF file written to {file_path}")

# Read the file back
with asdf.open(file_path) as af:
    print(f"Read data:\n{af.tree['data']}")
    print(f"Read coordinates: {af.tree['coordinates']}")

# Clean up the created file
os.remove(file_path)