{"id":7009,"library":"asdf","title":"ASDF Python Library","description":"Python implementation of the ASDF Standard, a language-agnostic serialization format for scientific data. It handles serialization of Python objects (including NumPy arrays, Astropy objects, and custom types) into ASDF files, which are YAML-based with support for binary data. The library is actively developed with several releases per year, and the current version is 5.2.0.","status":"active","version":"5.2.0","language":"en","source_language":"en","source_url":"https://github.com/asdf-format/asdf","tags":["data serialization","scientific data","astronomy","ASDF","yaml","numpy","astropy"],"install":[{"cmd":"pip install asdf","lang":"bash","label":"Install core library"},{"cmd":"pip install 'asdf[astropy,all]'","lang":"bash","label":"Install with common optional dependencies"}],"dependencies":[{"reason":"Essential for serialization and deserialization of array data.","package":"numpy","optional":false},{"reason":"Used for parsing and emitting YAML content.","package":"pyyaml","optional":false},{"reason":"Required for ASDF schema validation.","package":"jsonschema","optional":false},{"reason":"Widely used for astronomical data, provides many types directly supported by ASDF.","package":"astropy","optional":true}],"imports":[{"note":"While technically correct, the top-level import is preferred and canonical.","wrong":"from asdf.asdffile import AsdfFile","symbol":"AsdfFile","correct":"from asdf import AsdfFile"},{"symbol":"open","correct":"import asdf; asdf.open(...)"}],"quickstart":{"code":"import asdf\nimport numpy as np\nimport os\n\n# Create some data\ntree = {\n    'scientific_name': 'M42',\n    'coordinates': {\n        'ra': 83.822083,\n        'dec': -5.391111\n    },\n    'data': np.array([[1, 2], [3, 4]], dtype=np.int64)\n}\n\n# Create an ASDF file object\nff = asdf.AsdfFile(tree)\n\n# Define file path\nfile_path = \"example.asdf\"\n\n# Write the file\nff.write_to(file_path)\n\nprint(f\"ASDF file written to {file_path}\")\n\n# Read the file back\nwith asdf.open(file_path) as af:\n    print(f\"Read data:\\n{af.tree['data']}\")\n    print(f\"Read coordinates: {af.tree['coordinates']}\")\n\n# Clean up the created file\nos.remove(file_path)","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Upgrade your Python environment to version 3.10 or newer. Refer to the official Python documentation for upgrade instructions.","message":"Minimum Python version increased to 3.10. Users on older Python versions will encounter `ImportError` or environment resolution issues.","severity":"breaking","affected_versions":">=5.0.0"},{"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()`.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to directly replace the entire `AsdfFile.tree` attribute in `asdf` version 5.0 or later.","error":"AttributeError: property 'tree' of 'AsdfFile' object has no setter"},{"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.","cause":"ASDF cannot find a registered converter for a custom Python object type that was attempted to be serialized or deserialized.","error":"asdf.exceptions.ValidationError: <unknown>: 'tag:stsci.edu:asdf/custom-type-1.0.0' is not a valid ASDF tag."},{"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()`.","cause":"Using `mode='r+'` when opening an ASDF file with `asdf.open()` in versions 4.0 or newer.","error":"ValueError: 'r+' is not a supported mode for AsdfFile.open()"}]}