Skip to content

Module Reference

Module Reference

Complete API reference for the pyrs_yaml module.

Version compatibility

pyrs-yaml ships as an ABI3 wheel, so a single wheel works across Python 3.8–3.15 — no recompilation needed when upgrading Python.

Core Functions

parse()

Parse a YAML string or bytes into a YamlDocument.

parse(yaml: str | bytes, resolve_merges: bool = True, schema: str | dict = "core", max_depth: int = 1000, allow_duplicate_keys: bool = False) -> YamlDocument

Parameters:

  • yaml — YAML content as str or bytes
  • resolve_merges — Whether to resolve merge keys (<<: *alias) after parsing (default: True)
  • schema — Schema name ("core", "json", "failsafe", "yaml1.1", or a registered custom name), or an inline schema dict (see YAML Schema Language)
  • max_depth — Maximum nesting depth (default: 1000)
  • allow_duplicate_keys — Whether to allow duplicate mapping keys (default: False)

Returns: A YamlDocument containing the parsed YAML

Raises:

  • YamlParseError — Invalid YAML syntax
  • YamlTypeError — Schema not found
  • TypeError — Input is not str or bytes

Example:

doc = pyrs_yaml.parse("key: value")
doc = pyrs_yaml.parse(b"key: value")
doc = pyrs_yaml.parse(yaml_str, schema="json")
doc = pyrs_yaml.parse(
    "addr: 0xFF", schema={"extends": "core", "rules": [{"pattern": "^0x[0-9a-fA-F]+$", "type": "int"}]}
)

parse_file()

Parse a YAML file.

parse_file(path: str, schema: str | dict = "core", max_depth: int = 1000, allow_duplicate_keys: bool = False) -> YamlDocument

Parameters:

Returns: A YamlDocument

Raises:

  • IOError — File not found or unreadable
  • YamlParseError — Invalid YAML
  • YamlTypeError — Schema not found

Example:

doc = pyrs_yaml.parse_file("config.yaml")

parse_all_docs()

Parse multiple YAML documents from a string.

parse_all_docs(yaml: str, resolve_merges: bool = True, schema: str | dict = "core", max_depth: int = 1000, allow_duplicate_keys: bool = False) -> list[YamlDocument]

Parameters:

  • yaml — YAML content with one or more documents (--- separated)
  • schema — Schema name or inline dict (see YAML Schema Language)

Returns: A list of YamlDocument objects

Example:

docs = pyrs_yaml.parse_all_docs("a: 1\n---\nb: 2")

PyYAML-Compatible Functions

safe_load()

Parse a YAML string into a Python dict or list. Uses PyYAML-compatible API.

safe_load(yaml: str, schema: str | dict = "core", max_depth: int = 1000, allow_duplicate_keys: bool = False) -> dict[str, Any] | list[Any]

Parameters:

Raises: YamlParseError, YamlTypeError

Example:

d = pyrs_yaml.safe_load("key: value")
d = pyrs_yaml.safe_load(
    "addr: 0xFF", schema={"extends": "core", "rules": [{"pattern": "^0x[0-9a-fA-F]+$", "type": "int"}]}
)

safe_loads()

Parse multiple YAML documents from a string into Python dicts/lists.

safe_loads(yaml: str, schema: str | dict = "core", max_depth: int = 1000, allow_duplicate_keys: bool = False) -> list[dict[str, Any] | list[Any]]

Parameters:

  • yaml — YAML content with one or more documents
  • schema — Schema name or inline dict (see YAML Schema Language)

Equivalent to: yaml.safe_loads() in PyYAML

safe_dump()

Serialize a Python object to YAML.

safe_dump(data: dict[str, Any] | list[Any] | ndarray) -> str

Equivalent to: yaml.safe_dump() in PyYAML

Supported input types: dict, list, str, int, float, bool, None, and numpy.ndarray (all dimensions and numeric dtypes: int8/16/32/64, uint8/16/32/64, float32/64, complex64/128, bool)

Alias: safe_dumps() — identical to safe_dump().

:material-json: Conversion Functions

from_dict()

Convert a Python dict to YAML string. Also accepts numpy.ndarray as a value inside the dict.

from_dict(data: dict[str, Any]) -> str

from_json()

Convert a JSON string to YAML string.

from_json(json_str: str) -> str

dump_file()

Serialize a Python object to YAML and write to file. Accepts dict, list, or numpy.ndarray.

dump_file(data: Any, path: str) -> None

Pydantic Integration

dump_pydantic()

Serialize a Pydantic model to a YAML string.

dump_pydantic(model: BaseModel) -> str

Uses model_dump(mode='json') to preserve string types (e.g. a "10001" zip code stays a string) before delegating to safe_dump.

Raises:

  • ImportError — pydantic is not installed
  • TypeError — model is not a Pydantic BaseModel instance

Example:

from pydantic import BaseModel
import pyrs_yaml


class User(BaseModel):
    name: str
    age: int


yaml_str = pyrs_yaml.dump_pydantic(User(name="Alice", age=30))

parse_as()

Parse a YAML string and validate it against a Pydantic model.

parse_as(model: type[BaseModel], src: str, **yaml_kwargs: Any) -> BaseModel

Parameters:

  • model — A Pydantic BaseModel subclass
  • src — YAML string to parse
  • **yaml_kwargs — Keyword arguments forwarded to the YAML() constructor

Returns: An instance of model validating the parsed YAML.

Raises:

  • ImportError — pydantic is not installed
  • TypeError — model is not a Pydantic BaseModel subclass
  • pydantic.ValidationError — the parsed data fails model validation

Example:

user = pyrs_yaml.parse_as(User, "name: Alice\nage: 30")
print(user.name)  # Alice

PyrsYamlConfigSettingsSource

A pydantic-settings YAML source backed by pyrs-yaml. Drop-in replacement for pydantic_settings.YamlConfigSettingsSource that uses pyrs-yaml as the parser instead of PyYAML.

PyrsYamlConfigSettingsSource(
    settings_cls: type[BaseSettings],
    yaml_file: ConfigFileSourceType | None = DEFAULT_PATH,
    yaml_file_encoding: str | None = None,
    yaml_config_section: str | None = None,
    deep_merge: bool = False,
)

Loads settings from YAML file(s) declared via SettingsConfigDict(yaml_file=...) (or passed directly), then reads them with pyrs-yaml's parser under the YAML 1.2 core schema. All other pydantic-settings features — env-var and dotenv overlay, yaml_config_section (dot-notation paths included), deep_merge across multiple files, yaml_file_encoding — behave identically to YamlConfigSettingsSource.

Raises:

  • ImportError — pydantic-settings is not installed (install pyrs-yaml[settings])

Example:

from pydantic_settings import BaseSettings, SettingsConfigDict
import pyrs_yaml


class Settings(BaseSettings):
    app_name: str

    model_config = SettingsConfigDict(yaml_file="config.yaml")

    @classmethod
    def settings_customise_sources(
        cls, settings_cls, init_settings, env_settings, dotenv_settings, file_secret_settings
    ):
        return (
            init_settings,
            env_settings,
            dotenv_settings,
            file_secret_settings,
            pyrs_yaml.PyrsYamlConfigSettingsSource(settings_cls),
        )

Note: the class is exported lazily — import pyrs_yaml never requires pydantic-settings. Accessing pyrs_yaml.PyrsYamlConfigSettingsSource without pydantic-settings installed raises ImportError with installation hints.

Tag Registry

register_tag()

Register a custom tag handler. Supports both decorator and imperative forms.

register_tag(name: str, handler: Callable | None = None, priority: int = 0) -> Callable

Example:

@pyrs_yaml.register_tag("!custom")
def handler(node):
    return f"custom:{node}"

pyrs_yaml.register_tag("!custom", handler_fn, priority=1)

remove_tag()

Remove a tag handler.

remove_tag(name: str) -> None

clear_tag_handlers()

Remove all registered tag handlers.

clear_tag_handlers() -> None

YAML Schema Language

register_schema()

Register a custom YAML schema from a schema definition string.

register_schema(name: str, schema_yaml: str) -> None

Parameters:

  • name — Schema name, used as YAML(schema=name)
  • schema_yaml — Schema definition in YAML format

The schema definition supports a rules list mapping regex patterns to YAML types, and an optional extends base schema:

pyrs_yaml.register_schema(
    "myapp",
    """
name: myapp
extends: core
rules:
  - pattern: ^0x[0-9a-fA-F]+$
    type: int
  - pattern: ^\\d{4}-\\d{2}-\\d{2}$
    type: str
""",
)

doc = pyrs_yaml.parse("addr: 0xFF", schema="myapp")
assert doc.get("addr") == 255

Raises: YamlParseError — Invalid schema definition

Schema as inline dict

The schema parameter of YAML(), parse(), parse_file(), parse_all_docs(), safe_load(), and safe_loads() also accepts an inline dict, which is serialized and registered automatically:

doc = pyrs_yaml.safe_load(
    "addr: 0xFF",
    schema={
        "extends": "core",
        "rules": [{"pattern": "^0x[0-9a-fA-F]+$", "type": "int"}],
    },
)
assert doc["addr"] == 255

Community Plugins

CustomType

Base class for custom YAML node types. Subclass it to define a type that can be used with YAML tags.

class CustomType:
    python_type = None  # set to a Python type for isinstance checks

    def can_parse(self, node) -> bool: ...
    def from_yaml(self, value: str): ...
    def to_yaml(self, obj) -> str: ...
    def validate(self, obj) -> bool: ...

Methods:

  • python_type — Optional Python type used during serialization (isinstance)
  • can_parse(node) — Whether this type handles a given node
  • from_yaml(value) — Convert a YAML string to a Python object (load)
  • to_yaml(obj) — Convert a Python object to a YAML string (dump)
  • validate(obj) — Validate a Python object's type and value

Built-in plugins include !timestamp (maps to datetime), !date (datetime.date), !time (datetime.time), !uuid (uuid.UUID), !decimal (decimal.Decimal), !binary (bytes, base64-encoded), !regex (re.Pattern), and !set.

register_type()

Register a CustomType instance or class.

register_type(name: str, handler: CustomType | None = None) -> CustomType

Imperative form:

class TimestampType(pyrs_yaml.CustomType):
    python_type = datetime

    def from_yaml(self, value):
        return datetime.fromisoformat(value)

    def to_yaml(self, obj):
        return obj.isoformat()


pyrs_yaml.register_type("!timestamp", TimestampType())

Decorator form:

@pyrs_yaml.register_type("!timestamp")
class TimestampType(pyrs_yaml.CustomType): ...


doc = pyrs_yaml.parse("when: !timestamp 2026-08-11T10:30:00")
assert isinstance(doc.get("when"), datetime)

remove_type()

remove_type(name: str) -> None

Remove a registered custom type handler.

clear_type_handlers()

clear_type_handlers() -> None

Remove all registered custom type handlers.

Compliance

compliance_report()

Compute the YAML Test Suite compliance report.

compliance_report() -> dict

Returns the YAML Test Suite pass rate and per-test results.

Streaming Events

parse_stream()

Parse YAML incrementally, yielding raw event dicts.

parse_stream(yaml: str) -> StreamIterator

Returns a StreamIterator yielding one event dict per step. Unlike YAML().load_stream() (which resolves into Python values), this exposes the raw token stream.

YamlStream

The YamlStream class is a lazy event iterator returned by YAML().load_stream() and YAML().load_stream_file(). It yields parsed event dicts one at a time without loading the entire document into memory.

stream = yaml.load_stream_file("large.yaml")
for event in stream:
    print(event)

See YamlStream for full API details.

Async Functions

Async I/O wrappers via asyncio.run_in_executor. Non-blocking in event loop context.

safe_dump_async()

Serialize a Python object to a YAML string (async). Alias: safe_dumps_async().

async def safe_dump_async(data: Any) -> str

safe_loads_async()

Parse a YAML string into native Python objects (async).

async def safe_loads_async(yaml: str, schema: str = "core") -> Any

safe_load_async()

Parse a YAML string into native Python objects (async).

async def safe_load_async(yaml: str, schema: str = "core") -> Any

Example:

import asyncio, pyrs_yaml


async def main():
    yaml = await pyrs_yaml.safe_dumps_async({"a": 1})
    data = await pyrs_yaml.safe_loads_async(yaml)
    print(data)  # {'a': 1}


asyncio.run(main())

Markdown Frontmatter

read_markdown()

Extract YAML frontmatter from a Markdown file.

read_markdown(path: str, schema: str | dict = "core", max_depth: int = 1000) -> tuple[dict[str, Any] | None, str]

Returns: (frontmatter_dict, content_string). If no frontmatter, frontmatter is None.

read_markdown_str()

Extract YAML frontmatter from a Markdown string.

read_markdown_str(content: str, schema: str | dict = "core", max_depth: int = 1000) -> tuple[dict[str, Any] | None, str]

i18n Functions

set_language()

Set the language for error messages.

set_language(lang: str) -> None

Supported: "en", "zh-CN", "ja-JP", "ko-KR"

get_language()

Get the current language.

get_language() -> str

list_languages()

List all supported languages.

list_languages() -> list[str]

detect_language()

Auto-detect user's preferred language from environment variables.

detect_language() -> str

negotiate_language()

BCP 47 language negotiation.

negotiate_language(user_locales: list[str], default: str = "en") -> str

Exceptions

  • YamlParseError — YAML parsing error (inherits from ValueError)
  • YamlSerializeError — YAML serialization error (inherits from ValueError)
  • YamlTypeError — Type conversion error (inherits from TypeError)
  • YamlValidateError — JSON Schema validation error (inherits from ValueError)
  • YamlEditError — In-place edit failure (inherits from ValueError)
  • YamlPathError — Malformed/non-editable path (inherits from ValueError)
  • YamlDocumentError — Stale Node access (inherits from Exception)
  • YamlDuplicateKeyError — Duplicate mapping key detected (inherits from ValueError)
  • YamlMaxDepthError — Exceeded maximum nesting depth (inherits from ValueError)
  • YamlTagError — Invalid tag handler registration (inherits from ValueError)
  • YamlTagSkip — Sentinel raised by a tag handler to skip a node (inherits from Exception)

See Exceptions for full details.

Version

__version__ = "0.14.0"