Annotated YAML

1.0.2 · active · verified Thu Apr 16

Annotated YAML is a Python library that provides advanced YAML parsing and dumping capabilities, supporting secrets management and deep integration with Python's type hinting system. It builds upon `ruamel.yaml` and targets modern Python environments. The current version is 1.0.2, with a frequent release cadence, primarily for bug fixes and platform support within the 1.x series.

Common errors

```
ModuleNotFoundError: No module named 'annotatedyaml'
```
cause The correct Python package name is `annotated_yaml`, not `annotatedyaml` for imports.

fix Change your import statements from `import annotatedyaml` to `import annotated_yaml` or `from annotated_yaml import ...`.
```
ImportError: cannot import name 'load' from 'annotated_yaml.loader'
```
cause You are attempting to import an internal module path, which is not part of the stable public API and may change.

fix Import `load` directly from the top-level package: `from annotated_yaml import load`.
```
RuntimeError: encrypted_secrets_key must be set when secrets are used
```
cause YAML content contains `!secret` tags, but the `ENCRYPTED_SECRETS_KEY` environment variable is either unset or empty, or the `secrets` optional dependency is not installed.

fix Ensure `pip install annotatedyaml[secrets]` is run, and set a non-empty string value for `os.environ["ENCRYPTED_SECRETS_KEY"]` before calling `annotated_yaml.load()`.
```
TypeError: 'int' object is not subscriptable
```
cause You are attempting to access a dictionary-like item (e.g., `config['key']['subkey']`) on a value that is an integer (or another non-subscriptable type) in the YAML structure.

fix Review your YAML structure and Python code. The path you are trying to access might contain a scalar value where you expect a mapping. Consider using `AnnotatedBase` to define typed structures and catch such errors early.

Warnings

breaking Annotated YAML requires Python 3.13 or newer. Projects on older Python versions (e.g., 3.10, 3.11, 3.12) are not supported and will fail during installation or runtime.
Fix: Upgrade your Python environment to 3.13 or higher. If unable to upgrade, consider using an older version of `annotatedyaml` if available and compatible, or an alternative YAML library.
breaking Version 1.0.0 introduced significant internal refactoring and updated its core `ruamel.yaml` dependency to `>=0.18.0`. While primary `load`/`dump` APIs are generally stable, users relying on specific `ruamel.yaml` internals or behaviors might experience subtle changes from pre-1.0 versions.
Fix: Thoroughly test existing YAML configurations and loading logic when upgrading from `0.x.x` to `1.0.0+`. Consult the `ruamel.yaml` changelog for `0.18.0` if you suspect behavior differences.
gotcha Handling encrypted secrets requires the `cryptography` library to be installed (`pip install annotatedyaml[secrets]`) and the `ENCRYPTED_SECRETS_KEY` environment variable to be set with a valid key. Missing either will lead to runtime errors when accessing `!secret` values.
Fix: Ensure you install `annotatedyaml[secrets]`. Before loading YAML with secrets, set `os.environ["ENCRYPTED_SECRETS_KEY"]` to your decryption key. Generate a strong key for production use.
gotcha Annotated YAML uses `ruamel.yaml` internally, which has some behavioral differences compared to `PyYAML` (e.g., preserving comments, handling duplicate keys differently). Users accustomed to `PyYAML` might encounter unexpected parsing results or serialization outputs.
Fix: Familiarize yourself with `ruamel.yaml`'s documentation, especially regarding round-trip preservation and comment handling. Test your YAML inputs thoroughly with `annotatedyaml`.

Install

pip install annotatedyaml Basic Install
pip install annotatedyaml[secrets] Install with Secrets Support

Imports

load
wrong:
```
from annotated_yaml.loader import load
```
correct:
```
from annotated_yaml import load
```
Top-level `load` function is the primary API; avoid importing from internal modules like `loader` directly as paths may change.
dump
wrong:
```
from annotated_yaml.dumper import dump
```
correct:
```
from annotated_yaml import dump
```
Top-level `dump` function is the primary API; avoid importing from internal modules like `dumper` directly as paths may change.
AnnotatedBase
wrong:
```
from annotated_yaml import AnnotatedBase
```
correct:
```
from annotated_yaml.base import AnnotatedBase
```
`AnnotatedBase` for creating typed configuration models resides in the `base` submodule.
Secrets
```
from annotated_yaml.base import Secrets
```
The `Secrets` class for handling encrypted values is located in the `base` submodule.

Quickstart

This quickstart demonstrates basic loading and dumping of YAML data. For secrets support, install `annotatedyaml[secrets]` and set the `ENCRYPTED_SECRETS_KEY` environment variable.

import io
from annotated_yaml import load, dump

yaml_config_str = io.StringIO("""
app_name: MyConfigApp
version: 1.0.0
database:
  host: localhost
  port: 5432
features:
  - user_profiles
  - notifications
""")

# Load configuration from a string (or file-like object)
config = load(yaml_config_str)

print(f"Application Name: {config['app_name']}")
print(f"Database Host: {config['database']['host']}")
print(f"Enabled Features: {', '.join(config['features'])}")

# You can also dump the configuration back to YAML
print("\n--- Dumped YAML ---")
dump(config, io.StringIO().write) # Dumps to a string, or sys.stdout to print directly

view raw JSON →