Source code for osprey_connectors.yaml_loader
"""PyYAML safe loading and dumping on libyaml when it is installed.
``yaml.safe_load`` always runs PyYAML's pure-Python scanner, even when the
``yaml`` wheel shipped the libyaml bindings — the C scanner is only reached by
naming ``yaml.CSafeLoader`` explicitly. The two loaders share the constructor
and the resolver, so a document parses to the same objects either way; only the
scanning speed differs, by an order of magnitude. Every hot parse of a
deployment's YAML (``osprey build`` re-reads its rendered ``config.yml`` many
times per build) goes through :func:`safe_load` here rather than through
``yaml.safe_load`` directly. The emitter is the same story: ``yaml.safe_dump``
never reaches libyaml, and the two emitters write the same bytes for the
block-style documents a build writes, so every hot write goes through
:func:`safe_dump`.
"""
from __future__ import annotations
from typing import IO, Any, overload
import yaml
__all__ = [
"safe_dump",
"safe_load",
"safe_loader",
]
[docs]
def safe_loader() -> type[yaml.CSafeLoader] | type[yaml.SafeLoader]:
"""The safe loader class to parse with: libyaml's when present, else PyYAML's.
Resolved at call time rather than at import, so a build that runs without
the C bindings falls back on the same code path a test can exercise by
removing ``yaml.CSafeLoader``.
"""
return yaml.CSafeLoader if hasattr(yaml, "CSafeLoader") else yaml.SafeLoader
[docs]
def safe_load(stream: str | bytes | IO[str] | IO[bytes]) -> Any:
"""Parse one YAML document the way ``yaml.safe_load`` does, on the fastest loader.
Args:
stream: The document — a string, bytes, or an open file.
Returns:
The document as plain Python objects; ``None`` for an empty document.
Raises:
yaml.YAMLError: On a document that does not parse.
"""
return yaml.load(stream, Loader=safe_loader())
def _safe_dumper() -> type[yaml.CSafeDumper] | type[yaml.SafeDumper]:
"""The safe dumper class to emit with: libyaml's when present, else PyYAML's.
Resolved at call time, like :func:`safe_loader`.
"""
return yaml.CSafeDumper if hasattr(yaml, "CSafeDumper") else yaml.SafeDumper
@overload
def safe_dump(data: object, stream: None = None, **kwargs: Any) -> str: ...
@overload
def safe_dump(data: object, stream: IO[str], **kwargs: Any) -> None: ...
[docs]
def safe_dump(data: object, stream: IO[str] | None = None, **kwargs: Any) -> str | None:
"""Emit one YAML document the way ``yaml.safe_dump`` does, on the fastest dumper.
Args:
data: Plain Python objects; anything else is refused, as ``yaml.safe_dump`` refuses it.
stream: An open text file to write to; ``None`` returns the text.
**kwargs: The emitter options ``yaml.safe_dump`` takes (``sort_keys``,
``default_flow_style``, ``allow_unicode``, ``width``, ...).
Returns:
The document text when ``stream`` is ``None``, else ``None``.
Raises:
yaml.representer.RepresenterError: On an object the safe dumper cannot represent.
"""
text: str | None = yaml.dump(data, stream, Dumper=_safe_dumper(), **kwargs)
return text