モジュール リファレンス

pyrs_yaml モジュールの完全な API リファレンス。

コア関数¶

parse()¶

YAML 文字列またはバイト列をパースして YamlDocument に変換します。

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

パラメータ:

• yaml — str または bytes の YAML コンテンツ
• resolve_merges — パース後にマージキー (<<: *alias) を解決するかどうか (デフォルト: True)
• schema — スキーマ名 ("core", "json", "failsafe", "yaml1.1" または登録済みカスタム名)、またはインラインスキーマ dict（YAML スキーマ言語 参照）
• max_depth — 最大ネスト深度 (デフォルト: 1000)
• allow_duplicate_keys — 重複マッピングキーを許可するかどうか (デフォルト: False)

戻り値: パースされた YAML を含む YamlDocument

スロー:

• YamlParseError — 無効な YAML 構文
• YamlTypeError — 指定されたスキーマが見つかりません
• TypeError — 入力が str または bytes でない

例:

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()¶

YAML ファイルをパースします。

parse_file(path: str) -> YamlDocument

パラメータ:

• path — YAML ファイルへのパス

戻り値: YamlDocument

スロー:

• IOError — ファイルが見つからないまたは読み取り不可
• YamlParseError — 無効な YAML

例:

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

parse_all_docs()¶

文字列から複数の YAML ドキュメントをパースします。

parse_all_docs(yaml: str) -> list[YamlDocument]

戻り値: YamlDocument オブジェクトのリスト

例:

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

PyYAML 互換関数¶

safe_load()¶

YAML をパースしてネイティブ Python 型を返します。

safe_load(yaml: str) -> dict[str, Any] | list[Any]

以下と同等: PyYAML の yaml.safe_load()

例:

data = pyrs_yaml.safe_load("key: value")  # {'key': 'value'}

safe_loads()¶

複数の YAML ドキュメントをパースします。

safe_loads(yaml: str) -> list[dict[str, Any] | list[Any]]

以下と同等: PyYAML の yaml.safe_loads()

safe_dump()¶

Python オブジェクトを YAML にシリアライズします。

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

以下と同等: PyYAML の yaml.safe_dump()

サポートされる入力型: dict, list, str, int, float, bool, None, および numpy.ndarray (すべての次元と数値 dtype: int8/16/32/64, uint8/16/32/64, float32/64, complex64/128, bool)

safe_dumps()¶

safe_dump() のエイリアス。

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

:material-json: 変換関数¶

from_dict()¶

Python dict を YAML 文字列に変換します。dict の値として numpy.ndarray も受け付けます。

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

from_json()¶

JSON 文字列を YAML 文字列に変換します。

from_json(json_str: str) -> str

dump_file()¶

Python オブジェクトを YAML にシリアライズしてファイルに書き込みます。dict, list, または numpy.ndarray を受け付けます。

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

Pydantic 統合¶

dump_pydantic()¶

Pydantic モデルを YAML 文字列にシリアライズします。

dump_pydantic(model: BaseModel) -> str

model_dump(mode='json') を使用して文字列型を保持してから（例："10001" の郵便番号は文字列のまま）、safe_dump に委譲します。

スロー:

• ImportError — pydantic がインストールされていない
• TypeError — model が Pydantic の BaseModel インスタンスでない

例:

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()¶

YAML 文字列をパースし、Pydantic モデルに対して検証します。

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

パラメータ:

• model — Pydantic の BaseModel サブクラス
• src — パースする YAML 文字列
• **yaml_kwargs — YAML() コンストラクタに転送されるキーワード引数

スロー:

• ImportError — pydantic がインストールされていない
• TypeError — model が Pydantic の BaseModel サブクラスでない
• pydantic.ValidationError — パースされたデータがモデル検証に失敗

例:

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

PyrsYamlConfigSettingsSource¶

pydantic-settings の YAML ソースを pyrs-yaml で実現するクラス。pydantic_settings.YamlConfigSettingsSource のドロップイン代替で、PyYAML の代わりに pyrs-yaml をパーサとして使用します。

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,
)

SettingsConfigDict(yaml_file=...)（または直接渡された）で宣言された YAML ファイルから設定を読み込み、pyrs-yaml のパーサ（YAML 1.2 コアスキーマ）で解析します。環境変数・dotenv 上書き、yaml_config_section（ドット記法パス対応）、複数ファイルの deep_merge、yaml_file_encoding など、他の pydantic-settings の機能は YamlConfigSettingsSource と同一に動作します。

例外:

• ImportError — pydantic-settings がインストールされていない場合（pyrs-yaml[settings] をインストール）

例:

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),
        )

注: このクラスは遅延エクスポートされます — import pyrs_yaml に pydantic-settings は不要です。pydantic-settings が未インストールの状態で pyrs_yaml.PyrsYamlConfigSettingsSource にアクセスすると、インストール方法を示す ImportError が発生します。

タグレジストリ¶

register_tag()¶

カスタムタグハンドラを登録します。デコレータ形式と命令形式の両方をサポートします。

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

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

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

remove_tag()¶

タグハンドラを削除します。

remove_tag(name: str) -> None

clear_tag_handlers()¶

登録済みのすべてのタグハンドラを削除します。

clear_tag_handlers() -> None

YAML スキーマ言語¶

カスタムスキーマを定義して、プレーンスカラーが Python 型にどのように解決されるかを制御します。

register_schema()¶

カスタムスキーマを登録します。

register_schema(name: str, schema: str | dict) -> None

パラメーター:

• name — スキーマ名
• schema — YAML 文字列または dict（extends、rules、validate キーを含む）

例:

import pyrs_yaml

# YAML 文字列からカスタムスキーマを登録
pyrs_yaml.register_schema(
    "hex",
    """
name: hex
extends: core
rules:
  - pattern: ^0x[0-9a-fA-F]+$
    type: int
""",
)

# カスタムスキーマを使用
y = pyrs_yaml.YAML(schema="hex")
doc = y.parse("addr: 0xFF")
assert doc.get("addr") == 255

d = pyrs_yaml.safe_load("addr: 0x1F", schema="hex")
assert d["addr"] == 31

インラインスキーマ dict¶

登録せずに dict を直接渡す：

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

• extends — オプションのベーススキーマ（core、json、failsafe、yaml1.1）
• rules — 順序付きの {pattern, type} リスト；最初にマッチしたものが適用
• validate — オプションの構造検証ルール：パス修飾型（$.port: int）、コンテナチェック（sequence_of、mapping_of）、required 存在確認；validate_against_schema(data, schema_yaml) でドキュメントを検証
• 対応型：null、bool、int、float、str
• 組み込み Core スキーマは引き続きゼロコスト match ディスパッチを使用（影響なし）
• ファイル I/O — load_schema(name, path) で YAML ファイルからスキーマを読み込み；list_schemas() で登録済みの全スキーマを取得

コミュニティプラグイン¶

カスタム YAML ノードタイプを定義して、シリアライズとデシリアライズに統合します。

CustomType¶

カスタムタイプの基底クラス。

class CustomType:
    python_type: type

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

register_type()¶

カスタムタイプを登録します。

register_type(tag: str, type_handler: CustomType, priority: int = 0) -> None

例:

from datetime import datetime


class TimestampType(pyrs_yaml.CustomType):
    python_type = datetime

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

    def to_yaml(self, obj) -> str:
        return obj.isoformat()


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

# ロード：タグ付きスカラー → Python オブジェクト
doc = pyrs_yaml.parse("when: !timestamp 2026-08-11T10:30:00")
assert isinstance(doc.get("when"), datetime)

# ダンプ：Python オブジェクト → タグ付きスカラー
data = {"ts": datetime(2026, 8, 11, 10, 30)}
out = pyrs_yaml.safe_dump(data)
# out には次が含まれる：ts: !timestamp 2026-08-11T10:30:00

remove_type()¶

登録済みのタイプを削除します。

remove_type(name: str) -> None

clear_type_handlers()¶

登録済みのすべてのタイプハンドラを削除します。

clear_type_handlers() -> None

コンプライアンス¶

compliance_report()¶

YAML テストスイートのコンプライアンスレポートを計算します。

compliance_report() -> dict

YAML テストスイートの合格率とテストごとの結果を返します。

ストリーミングイベント¶

parse_stream()¶

YAML をインクリメンタルにパースし、生のイベント dict を生成します。

parse_stream(yaml: str) -> StreamIterator

各ステップで 1 つのイベント dict を生成する StreamIterator を返します。YAML().load_stream()（Python 値に解決される）とは異なり、生のトークンストリームを公開します。

YamlStream¶

YamlStream クラスは、YAML().load_stream() と YAML().load_stream_file() が返す遅延イベントイテレータです。ドキュメント全体をメモリに読み込まずに、パース済みのイベント dict を一度に 1 つ生成します。

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

完全な API の詳細は YamlStream を参照してください。

非同期関数¶

asyncio.run_in_executor を使用した非同期 I/O ラッパー。イベントループコンテキストではノンブロッキング。

safe_dumps_async()¶

Python オブジェクトを YAML 文字列にシリアライズ (非同期)。

async def safe_dumps_async(data: Any) -> str

safe_dump_async()¶

Python オブジェクトを stdout に YAML として出力 (非同期)。

async def safe_dump_async(data: Any) -> None

safe_loads_async()¶

YAML 文字列をネイティブ Python オブジェクトにパース (非同期)。

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

safe_load_async()¶

YAML 文字列をネイティブ Python オブジェクトにパース (非同期)。

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

例:

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 Front Matter¶

read_markdown()¶

Markdown ファイルから YAML Front Matterを抽出します。

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

戻り値: (frontmatter_dict, content_string)。Front Matterがない場合、frontmatter は None。

read_markdown_str()¶

Markdown 文字列から YAML Front Matterを抽出します。

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

i18n 関数¶

set_language()¶

エラーメッセージの言語を設定します。

set_language(lang: str) -> None

サポート: "en", "zh-CN", "ja-JP", "ko-KR"

get_language()¶

現在の言語を取得します。

get_language() -> str

list_languages()¶

すべてのサポートされる言語を一覧表示します。

list_languages() -> list[str]

detect_language()¶

環境変数からユーザーの優先言語を自動検出します。

detect_language() -> str

negotiate_language()¶

BCP 47 言語ネゴシエーション。

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

例外¶

• YamlParseError — YAML パースエラー (ValueError を継承)
• YamlSerializeError — YAML シリアライズエラー (ValueError を継承)
• YamlTypeError — 型変換エラー (TypeError を継承)
• YamlValidateError — JSON Schema 検証エラー (ValueError を継承)
• YamlEditError — インプレース編集エラー (ValueError を継承)
• YamlPathError — YAML パスエラー (ValueError を継承)
• YamlDocumentError — 陳腐化した Node アクセスエラー (Exception を継承)

詳細は 例外 ページを参照してください。

バージョン¶

__version__ = "0.14.0"