Pydantic-YAML

1.6.0 · active · verified Sat Apr 11

Pydantic-YAML (version 1.6.0) is an active Python library that extends Pydantic models with YAML reading and writing capabilities. It enables seamless serialization of Pydantic models to YAML strings and deserialization of YAML data back into Pydantic model instances. The library maintains an active release cadence, with ongoing development and support for modern Python and Pydantic versions.

Warnings

breaking Pydantic-YAML v1 introduces breaking changes regarding the `YamlModel` and `YamlModelMixin` base classes. For Pydantic v2 (and later), these mixin classes have been removed. Users should instead directly use the `parse_yaml_raw_as` and `to_yaml_str` functions.
Fix: Migrate from inheriting `YamlModel` or `YamlModelMixin` to directly calling `pydantic_yaml.parse_yaml_raw_as(YourModel, yaml_data)` and `pydantic_yaml.to_yaml_str(your_instance)`.
gotcha Pydantic-YAML requires an underlying YAML parser (like `ruamel.yaml` or `PyYAML`) to be explicitly installed. Installing `pydantic-yaml` alone will not provide YAML parsing capabilities.
Fix: Install with optional dependencies: `pip install pydantic-yaml[ruamel]` (recommended) or `pip install pydantic-yaml[pyyaml]`.
breaking Support for Python 3.7 has been dropped. The library now requires Python 3.10 or newer.
Fix: Upgrade your Python environment to 3.10 or newer. If you must use Python 3.7, `pydantic-yaml` version `1.1.3` is the last compatible release.
gotcha While `pydantic-yaml` leverages Pydantic's JSON dumping internally, direct YAML-specific configuration options (beyond indentation) are limited. More specific YAML configuration is planned for a future major version (v2).
Fix: Currently, configure YAML output using `to_yaml_str` keyword arguments like `indent`. For more advanced YAML-specific serialization, manual intervention with `ruamel.yaml` or `PyYAML` might be necessary.

Install

pip install pydantic-yaml Base installation
pip install pydantic-yaml[ruamel] Recommended with ruamel.yaml
pip install pydantic-yaml[pyyaml] Alternative with PyYAML

Imports

parse_yaml_raw_as

from pydantic_yaml import parse_yaml_raw_as

to_yaml_str
```
from pydantic_yaml import to_yaml_str
```
YamlModel
```
from pydantic_yaml import YamlModel
```
The `YamlModel` and `YamlModelMixin` base classes were removed in `pydantic-yaml` v1 for Pydantic v2 and later; use `parse_yaml_raw_as` and `to_yaml_str` directly instead. This functionality may be re-added for Pydantic < 2.x in future `pydantic-yaml` v1 releases.
YamlModelMixin
```
from pydantic_yaml import YamlModelMixin
```
The `YamlModel` and `YamlModelMixin` base classes were removed in `pydantic-yaml` v1 for Pydantic v2 and later; use `parse_yaml_raw_as` and `to_yaml_str` directly instead. This functionality may be re-added for Pydantic < 2.x in future `pydantic-yaml` v1 releases.

Quickstart

This example demonstrates how to define a Pydantic model with nested structures and enums, then serialize an instance to a YAML string, and finally deserialize that YAML string back into a Pydantic model using `pydantic-yaml`'s `to_yaml_str` and `parse_yaml_raw_as` functions. It also shows how Pydantic validators are preserved.

from enum import Enum
from pydantic import BaseModel, validator
from pydantic_yaml import parse_yaml_raw_as, to_yaml_str

class MyEnum(str, Enum):
    a = "a"
    b = "b"

class InnerModel(BaseModel):
    fld: float = 1.0

class MyModel(BaseModel):
    x: int = 1
    e: MyEnum = MyEnum.a
    m: InnerModel = InnerModel()

    @validator("x")
    def _chk_x(cls, v: int) -> int:
        assert v > 0
        return v

m1 = MyModel(x=2, e="b", m=InnerModel(fld=1.5))

# Dump to YAML string
yml_string = to_yaml_str(m1, add_comments=True)
print("\n--- Dumped YAML ---\n", yml_string)

# Parse YAML string back into model
m2 = parse_yaml_raw_as(MyModel, yml_string)
print("\n--- Parsed Model ---\n", m2)
assert m1 == m2

view raw JSON →