YamlDocument クラス

概要¶

YamlDocument は pyrs-yaml のコアクラスで、解析済みの YAML ドキュメントを保持します。IndexMap を使用したカスタム AST により、100% ラウンドトリップ、完全なキー順序保持、ネストされたコメントの保持、詳細なメタデータを実現します。

class YamlDocument:
    """pyrs-yaml のコアクラス。"""

    # ... C 拡張で実装 ...

コンストラクター¶

`YamlDocument()`¶

内部コンストラクター。ユーザーが直接呼び出すことはありません。pyrs_yaml.parse() から返されます。

プロパティ¶

version — YAML ドキュメントバージョン
schema — スキーマ（core, failsafe, json）
tags — タグ一覧
anchors — アンカー一覧
source — YAML ソーステキスト

メソッド¶

`to_yaml()`¶

ドキュメントを YAML 文字列に変換します。

to_yaml(
    indent: int = 2,
    allow_unicode: bool = True,
    default_flow_style: bool = False,
    sort_keys: bool = False,
    width: int = 80,
    resolve_aliases: bool = True,
    strip_comments: bool = False,
    preserve_quotes: bool = True,
) -> str

パラメータ:

indent — インデントスペース数（デフォルト: 2）
allow_unicode — Unicode 文字を許可（デフォルト: True）
default_flow_style — デフォルトでフロースタイルを使用（デフォルト: False）
sort_keys — キーをソート（デフォルト: False）
width — 折り返し幅（デフォルト: 80）
resolve_aliases — エイリアスを解決（デフォルト: True）
strip_comments — コメントを除去（デフォルト: False）
preserve_quotes — クォートを保持（デフォルト: True）

戻り値: YAML 文字列

例:

doc = pyrs_yaml.parse("key: value\n# comment")
yaml_str = doc.to_yaml()

`to_yaml_with_options()`¶

カスタムオプションで YAML に変換します。

to_yaml_with_options(
    indent_size: int = 2,
    explicit_start: bool = False,
    explicit_end: bool = False,
    sort_keys: bool = False,
) -> str

パラメータ:

indent_size — インデントレベルごとのスペース数 (デフォルト: 2)
explicit_start — ドキュメント先頭に --- を追加 (デフォルト: False)
explicit_end — ドキュメント末尾に ... を追加 (デフォルト: False)
sort_keys — キーをアルファベット順にソート (デフォルト: False)

例:

yaml_str = doc.to_yaml_with_options(
    indent_size=4,
    explicit_start=True,
    sort_keys=True,
)

`to_dict()`¶

Python dict/list に変換します。エイリアス参照を解決し、ネイティブ Python タイプを返します。

to_dict() -> dict[str, Any] | list[Any]

戻り値: 辞書またはリスト

例:

doc = pyrs_yaml.parse("key: value")
data = doc.to_dict()  # {'key': 'value'}

`get()`¶

トップレベルのマッピングキーによるリテラルキー検索で値を取得します（__getitem__/__setitem__ と一貫）。キーは .、[、]、$ を含めても常に文字どおりのキーとして扱われ、パスとして解釈されません。

get(key: str, default: Any = None) -> Any

戻り値: 値、見つからない場合はデフォルト

パスアクセス

JSONPath スタイルのアクセスには find() / node() / set() を使ってください（$.a.b、$.items[-1] 等）。

`root_type()`¶

ルートノードの型を文字列で取得します。

root_type() -> str

戻り値: "scalar", "mapping", "sequence", "null", "alias" のいずれか。

例:

print(doc.root_type())  # "mapping"

`to_json()`¶

ドキュメントを JSON 文字列にシリアライズします。

to_json(indent: int = 2) -> str

戻り値: JSON 文字列

`validate()`¶

JSON Schema に基づいてドキュメントの内容を検証します。

validate(schema: dict[str, Any]) -> None

スロー: YamlValidateError — 検証エラー

`reparse()`¶

保存されたソーステキストをその場で再パースし、スキーマやマージ動作の変更を可能にします。

reparse(resolve_merges: bool = True, schema: str = "core") -> None

パラメータ:

resolve_merges — <<: *alias マージキーを解決するかどうか (デフォルト: True)
schema — 型解決スキーマ: "core", "json", "failsafe", または "yaml1.1" (デフォルト: "core")

スロー:

TypeError — ソーステキストが保存されていない
YamlParseError — 再パースに失敗

例:

doc = pyrs_yaml.parse("x: on")
print(doc.get("x"))  # "on" (string, core schema)

doc.reparse(schema="yaml1.1")
print(doc.get("x"))  # True (bool, yaml1.1 schema)

`source()`¶

このドキュメントの作成に使用された元の YAML ソーステキストを返します。ドキュメントがその場で編集された場合、ソースは最初のアクセス時に現在のツリーから遅延して再シリアライズされます。

source() -> str

戻り値: YAML 文字列。parse() で作成されていない場合（例: from_dict()）は空文字列。

例:

doc = pyrs_yaml.parse("key: value")
print(doc.source())  # "key: value"

編集メソッド¶

アトミック編集

pyrs-yaml の編集操作はすべてアトミックです。失敗した場合、ドキュメント（リビジョンを含む）は変更されません。

ドキュメントをその場で編集し、すべてのメタデータ（コメント、アンカー、タグ、スタイル）を保持します。編集は JSONPath スタイルのパス（$.a.b、$.items[0]）でノードを特定します。

`set()`¶

パスで値を置き換えます。

set(path: str, value: Any, create_missing: bool = False) -> None

スカラー、dict、list をサポート；tuple はサポートされません（YamlEditError をスロー）
既存のスカラーを置換する場合、対象のメタデータが保持されます；パスが存在しない場合はマッピングの末尾に新しいキーを追加
空のドキュメント（"" からパース）にパスを設定すると、マッピングルートが自動的に作成されます
create_missing=True を指定すると、不足している中間マッピングキーが自動的に作成されます

例:

doc = pyrs_yaml.parse("a:\n  b: 1")
doc.set("$.a.b", 42)
doc.set("$.a.c", True)  # 新しいキーを追加
doc.set("$", {"x": 1})  # ルート全体を置換

# create_missing で不足キーを自動作成
doc.set("$.b.c.d", 2, create_missing=True)

`walk()`¶

AST の深さ優先・先行順の走査で、Node オブジェクトを生成します。

walk() -> Generator[Node, None, None]

Node.walk() とは異なり、このメソッドはRust バックエンドです — AST を Python dict に変換せずに直接走査するため、大規模ドキュメントで大幅に高速です。

生成するもの: ルートを含む、ドキュメントツリー内のすべてのノードの Node オブジェクト。

例:

doc = pyrs_yaml.parse("a:\n  b: 1\n  c: 2\n")
for node in doc.walk():
    print(node._path, node.root_type)
# ()       mapping
# ('a',)   mapping
# ('a', 'b') scalar
# ('a', 'c') scalar

`scalars()`¶

walk() と同様ですが、スカラー/null ノードのみを生成します。

scalars() -> Generator[Node, None, None]

生成するもの: ドキュメントツリー内のすべてのスカラーまたは null ノードの Node オブジェクト。

例:

doc = pyrs_yaml.parse("a: hello\nb: null\n")
for node in doc.scalars():
    print(node._path, node.value)
# ('a',) hello
# ('b',) None

`insert()`¶

シーケンスの指定インデックスに値を挿入します。

insert(path: str, index: int, value: Any) -> None

index はシーケンスの現在の長さまで指定できます（len への挿入は追加と同等）。負のインデックスは末尾から数えます（-1 は最後の要素の前に挿入）。パスはシーケンスノードに解決される必要があります。

`append()`¶

シーケンスの末尾に値を追加します。

append(path: str, value: Any) -> None

`delete()`¶

パスでノードを削除します。マッピングの順序は保持されます。

delete(path: str) -> None

`rename()`¶

マッピングキーをその場でリネームします（位置とメタデータを保持）。

rename(path: str, new_key: str) -> None

ルートまたは複合（非スカラー）キーのリネームは YamlEditError をスローします。

`node()`¶

ドキュメントルートの Node を返します。

node() -> Node

`find()`¶

パスでノードを検索します。ワイルドカード（[*]）とディープスキャン（..）をサポート — その場合、ノードのリストを返します。

find(path: str) -> Node | list[Node]

スロー:

YamlPathError — パスが不正、または編集パスでワイルドカード/.. を使用
YamlEditError — 編集を適用できない（tuple、エイリアス経由の編集、ルート/複合キーのリネーム、スカラーへのナビゲーション、インデックス範囲外）
YamlDocumentError — ドキュメント編集後に陳腐化した Node を使用

参照: インプレース編集ガイド

例:

doc = pyrs_yaml.parse("items: [1, 2, 3]")
doc.set("$.items[1]", "two")
doc.insert("$.items", 1, "x")  # items: [1, x, 2, 3]
doc.append("$.items", 4)
doc.rename("$.items", "list")  # マッピングキーをリネーム
del doc["list"]  # doc.delete("$.list") と同等

ダンダーメソッド¶

`getitem()`¶

キー（マッピング）またはインデックス（シーケンス）でアクセスします。

doc = pyrs_yaml.parse("key: value")
value = doc["key"]  # 'value'

`setitem()`¶

ルートマッピングキーを設定します（doc.set() のルート用糖衣構文）。

doc["key"] = value

`delitem()`¶

ルートマッピングキーを削除します（doc.delete() のルート用糖衣構文）。

del doc["key"]

`contains()`¶

キーが存在するか確認します。

"key" in doc  # True

`len()`¶

アイテム数を取得します。

len(doc)

`iter()`¶

キー（マッピング）または値（シーケンス）を反復します。

for key in doc:
    print(key)

`repr()`¶

デバッグ表現。

repr(doc)  # "YamlDocument({key: value})"

`str()`¶

文字列表現。

str(doc)  # "YamlDocument({key: value})"

`eq()`¶

等値比較。2つの YamlDocument が同じ内容を持つ場合、true を返します。

doc1 == doc2  # True or False

使用例¶

import pyrs_yaml

doc = pyrs_yaml.parse("""
name: Alice
age: 30
""")

print(doc.get("name"))  # Alice
print(doc.root_type())  # mapping
print(len(doc))  # 2
print("name" in doc)  # True
for key in doc:
    print(key, doc[key])  # name Alice, age 30

YamlDocument クラス

概要¶

コンストラクター¶

YamlDocument()¶

プロパティ¶

メソッド¶

to_yaml()¶

to_yaml_with_options()¶

to_dict()¶

get()¶

root_type()¶

to_json()¶

validate()¶

reparse()¶

source()¶

編集メソッド¶

set()¶

walk()¶

scalars()¶

insert()¶

append()¶

delete()¶

rename()¶

node()¶

find()¶

ダンダー メソッド¶

__getitem__()¶

__setitem__()¶

__delitem__()¶

__contains__()¶

__len__()¶

__iter__()¶

__repr__()¶

__str__()¶

__eq__()¶

使用例¶

`YamlDocument()`¶

`to_yaml()`¶

`to_yaml_with_options()`¶

`to_dict()`¶

`get()`¶

`root_type()`¶

`to_json()`¶

`validate()`¶

`reparse()`¶

`source()`¶

`set()`¶

`walk()`¶

`scalars()`¶

`insert()`¶

`append()`¶

`delete()`¶

`rename()`¶

`node()`¶

`find()`¶

ダンダーメソッド¶

`getitem()`¶

`setitem()`¶

`delitem()`¶

`contains()`¶

`len()`¶

`iter()`¶

`repr()`¶

`str()`¶

`eq()`¶