PythonistaのためのYAML徹底解説：PyYAMLとruamel.yamlを使いこなす

YAMLは、JSONやXMLと同様に構造化されたデータを表現するためのフォーマットですが、インデント（字下げ）によって階層構造を示す点が大きな特徴です。これにより、括弧やタグが少なく、非常にシンプルで読みやすい形式となっています。

Pythonのコードブロックもインデントで構造を示すため、YAMLの形式と非常に似ており、Pythonプログラマーにとっては直感的に理解しやすいでしょう。設定ファイルとしてYAMLを使うことで、複雑な設定もすっきりと記述でき、管理が容易になります。また、異なるプログラミング言語間でのデータ交換にも利用されます。

YAMLの主な特徴:

• 人間にとって読み書きしやすい
• インデントによる階層表現
• コメントが書ける（# で始まる行）
• リスト（シーケンス）や辞書（マッピング）を表現可能
• 豊富なデータ型（文字列、数値、真偽値、null、日付など）
• 1つのファイルに複数のドキュメントを含めることができる（--- で区切る）

PythonでYAMLを扱うことで、これらのメリットを活かし、設定管理やデータ処理を効率化できます。

PythonでYAMLを扱うためのライブラリはいくつかありますが、特に有名なのがPyYAMLとruamel.yamlです。

PyYAML (pyyaml)

古くから存在する、最も広く使われているYAMLライブラリです。YAML 1.1仕様をサポートしており、基本的なYAMLファイルの読み書き機能を提供します。シンプルで使いやすいAPIが特徴ですが、いくつかの注意点もあります（後述）。

インストール:

pip install pyyaml

ruamel.yaml

PyYAMLのフォーク（派生版）として開発されたライブラリで、YAML 1.2仕様をサポートしています。PyYAMLのいくつかの問題を改善しており、特に以下の点で優れています。

• コメントの保持: YAMLファイル内のコメントを読み書き時に保持できます。
• 順序の保持: 辞書（マッピング）のキーの順序を保持します。
• よりYAML 1.2仕様に準拠した動作

設定ファイルをプログラムで編集し、元のフォーマット（コメントや順序）を極力維持したい場合に非常に強力です。

インストール:

pip install ruamel.yaml

どちらを使うべきか？

シンプルな読み書きだけであればPyYAMLでも十分ですが、設定ファイルの編集や、元の構造を保持したい場合はruamel.yamlの利用を強く推奨します。この記事では、主にPyYAMLの基本的な使い方を解説しつつ、ruamel.yamlの利点についても触れていきます。

3.1 YAMLファイルの読み込み (load / safe_load)

YAMLファイルをPythonオブジェクト（主に辞書やリスト）に変換するには、yaml.load()またはyaml.safe_load()関数を使用します。

例：config.yaml

# 設定ファイル例
database: host: localhost port: 5432 user: admin password: "secure_password" # これは例です。実際のパスワードは安全に管理してください。
api_settings: url: "https://api.example.com/v1" timeout: 30 # seconds retry_attempts: 3
feature_flags: new_dashboard: true experimental_feature: false user_groups: - alpha - beta

Pythonコード (読み込み):

import yaml
from pathlib import Path
# YAMLファイルのパス
yaml_file_path = Path('config.yaml')
try: with open(yaml_file_path, 'r', encoding='utf-8') as f: # 安全なsafe_loadを使用 config_data = yaml.safe_load(f) # 読み込んだデータを表示・利用 print("--- 設定データ全体 ---") print(config_data) print("\n--- 個別の値へのアクセス ---") db_host = config_data['database']['host'] api_timeout = config_data['api_settings']['timeout'] user_groups = config_data['feature_flags']['user_groups'] print(f"データベースホスト: {db_host}") print(f"APIタイムアウト: {api_timeout}") print(f"ユーザーグループ: {user_groups}")
except FileNotFoundError: print(f"エラー: ファイル '{yaml_file_path}' が見つかりません。")
except yaml.YAMLError as e: print(f"エラー: YAMLファイルの解析中にエラーが発生しました。 - {e}")
except Exception as e: print(f"予期せぬエラーが発生しました: {e}")

safe_load()はYAMLの内容を解析し、対応するPythonのデータ構造（この場合はネストした辞書とリスト）を返します。キーを使って値にアクセスできます。ファイルの文字コードはencoding='utf-8'のように指定するのが一般的です。

文字列からの読み込み

safe_load()はファイルオブジェクトだけでなく、YAML形式の文字列も直接読み込めます。

import yaml
yaml_string = """
- item1
- item2
- sublist: - subitem A - subitem B
"""
data_from_string = yaml.safe_load(yaml_string)
print(data_from_string)

3.2 PythonオブジェクトのYAMLファイルへの書き込み (dump)

Pythonの辞書やリストなどのオブジェクトをYAML形式でファイルに書き込むには、yaml.dump()関数を使用します。

Pythonコード (書き込み):

import yaml
from pathlib import Path
# 書き込むデータ (Pythonの辞書)
output_data = { 'server': { 'ip_address': '192.168.1.100', 'port': 8080, 'enabled': True, 'services': ['web', 'database', 'cache'] }, 'metadata': { 'version': '1.2.3', 'description': 'サーバー設定データ' # 日本語を含む例 }
}
# 出力ファイルパス
output_yaml_path = Path('output.yaml')
try: with open(output_yaml_path, 'w', encoding='utf-8') as f: # dump関数で書き込み yaml.dump( output_data, f, allow_unicode=True, # 日本語などの非ASCII文字をそのまま出力 default_flow_style=False, # ブロックスタイル (インデント形式) を強制 sort_keys=False # キーの順序を保持しようと試みる (PyYAMLでは保証されない) ) print(f"データを '{output_yaml_path}' に書き込みました。")
except Exception as e: print(f"ファイルの書き込み中にエラーが発生しました: {e}")

dump()の主なオプション:

• stream: 書き込み先のファイルオブジェクト。省略すると文字列として結果を返す。
• allow_unicode=True: Unicode文字（日本語など）を\uXXXXのようなエスケープシーケンスではなく、そのまま出力します。通常はTrueを指定するのが良いでしょう。
• default_flow_style=False: リストや辞書をフロースタイル（例: [item1, item2], {key: value}）ではなく、ブロックスタイル（インデントを使った形式）で出力します。可読性のためにFalseが推奨されることが多いです。PyYAMLはデフォルトで、ネストされたコレクションがない場合はフロースタイルを選択することがあります。
• sort_keys=False: 辞書のキーをソートせずに出力しようと試みます。ただし、PyYAMLはPython 3.6以前の辞書のように順序を保証しないため、意図した順序にならない場合があります。順序保持が必要な場合はruamel.yamlを使用します。
• indent=N: インデントのスペース数を指定します（デフォルトは2）。

3.3 データ型：スカラー、シーケンス、マッピング

PyYAMLはYAMLの基本的なデータ構造をPythonの型にマッピングします。

• スカラー (Scalar): 文字列、数値 (整数、浮動小数点数)、真偽値 (True, False)、None (YAMLのnullや~に対応)
  • 注意: YES/NO, ON/OFFなども真偽値として解釈されることがあります（”The Norway Problem”として知られる）。文字列として扱いたい場合はクォーテーションで囲む必要があります（例: 'NO'）。
• シーケンス (Sequence): 順序付けられた要素のリスト。Pythonのlistに対応します。
  • ブロックスタイル: - item
  • フロースタイル: [item1, item2]
• マッピング (Mapping): キーと値のペアのコレクション。Pythonのdictに対応します。
  • ブロックスタイル: key: value
  • フロースタイル: {key1: value1, key2: value2}

import yaml
yaml_data_types = """
string_example: Hello, YAML!
quoted_string: "Special characters: & * #" # クォートで囲むと特殊文字も扱いやすい
integer_example: 123
float_example: 3.14159
boolean_true: true
boolean_false: No # これは False になるので注意！文字列なら 'No' と書く
null_example: null # または ~
list_example: - apple - banana - orange
dictionary_example: name: Alice age: 30 city: Tokyo
nested_structure: - key: item1 value: 100 - key: item2 value: [a, b, c]
"""
parsed_data = yaml.safe_load(yaml_data_types)
print(parsed_data)
# データ型の確認
print(f"boolean_falseの型: {type(parsed_data['boolean_false'])}") # print(f"list_exampleの型: {type(parsed_data['list_example'])}") # print(f"dictionary_exampleの型: {type(parsed_data['dictionary_example'])}") # print(f"null_exampleの型: {type(parsed_data['null_example'])}") # 

3.4 複数ドキュメントの扱い

YAMLファイルは---区切りで複数のドキュメントを含むことができます。PyYAMLでこれらを読み込むにはyaml.safe_load_all()を使用します。これはジェネレータを返すため、ループで各ドキュメントを処理します。

例：multi_doc.yaml

# ドキュメント1
document: 1
type: config
---
# ドキュメント2
document: 2
type: data
payload: - id: 1 value: foo - id: 2 value: bar
---
# ドキュメント3: シンプルなリスト
- item_a
- item_b

Pythonコード:

import yaml
from pathlib import Path
multi_doc_path = Path('multi_doc.yaml')
try: with open(multi_doc_path, 'r', encoding='utf-8') as f: documents = yaml.safe_load_all(f) print("--- 複数ドキュメントの読み込み ---") for i, doc in enumerate(documents): print(f"\nドキュメント {i+1}:") print(doc)
except FileNotFoundError: print(f"エラー: ファイル '{multi_doc_path}' が見つかりません。")
except yaml.YAMLError as e: print(f"エラー: YAMLファイルの解析中にエラーが発生しました。 - {e}")
except Exception as e: print(f"予期せぬエラーが発生しました: {e}")

同様に、複数のPythonオブジェクトをyaml.dump_all()で1つのファイルに書き込めます。

ruamel.yamlは、PyYAMLの基本的な機能に加え、より高度な操作やYAML 1.2準拠の機能を提供します。特に「Round Trip」モード (typ='rt') が強力です。

4.1 コメントと順序の保持 (Round Trip)

設定ファイルを読み込み、一部を変更して書き戻す際に、元のコメントやキーの順序が失われると非常に不便です。ruamel.yamlのRound Tripモードはこれを解決します。

from ruamel.yaml import YAML
from pathlib import Path
import sys
yaml_file_with_comments = Path('config_with_comments.yaml')
# コメント付きのYAMLファイルを作成 (例)
yaml_content = """
# データベース設定
database: host: old_host.example.com # ホスト名 (変更予定) port: 5432
# APIエンドポイント
api: url: https://api.example.com
"""
yaml_file_with_comments.write_text(yaml_content, encoding='utf-8')
# ruamel.yamlのYAMLインスタンスを作成 (Round Tripモード)
yaml = YAML() # typ='rt'がデフォルト
yaml.preserve_quotes = True # クォートを保持
yaml.indent(mapping=2, sequence=4, offset=2) # インデント設定 (例)
try: # ファイルを読み込む (コメントや順序が保持される) with open(yaml_file_with_comments, 'r', encoding='utf-8') as f: data = yaml.load(f) # データを変更 data['database']['host'] = 'new_host.internal.local' data['api']['timeout'] = 60 # 新しいキーを追加 # 変更後のデータを書き戻す (コメントや順序は維持される) print("--- 変更後のYAML (標準出力へ) ---") yaml.dump(data, sys.stdout) # ファイルに書き戻す場合 output_path = Path('config_updated.yaml') with open(output_path, 'w', encoding='utf-8') as f: yaml.dump(data, f) print(f"\n\n変更を '{output_path}' に書き込みました。")
except Exception as e: print(f"エラーが発生しました: {e}")

このコードを実行すると、config_updated.yamlには元のコメントが残り、databaseセクションのhostが更新され、apiセクションにtimeoutが追加されたYAMLが出力されます。キーの順序も維持されます。これはPyYAMLでは実現困難な機能です。

4.2 YAML 1.2 対応と細かい挙動の違い

ruamel.yamlはYAML 1.2をサポートしているため、PyYAML (YAML 1.1) とは一部の解釈が異なる場合があります。

• 8進数: YAML 1.1では012は8進数の10と解釈されますが、YAML 1.2では単なる数値の12です。ruamel.yaml (pure Pythonモード) は1.2の挙動に従います (0o12のように明示的に書くのが1.2流)。
• 真偽値: YAML 1.2ではtrue/falseのみが標準の真偽値です (Yes/No, On/Offは非標準)。
• Unicode: より厳密なUnicodeサポート。

基本的な使い方では大きな違いはありませんが、細かい仕様に依存するケースではruamel.yamlの方がより標準に準拠していると言えます。

5.1 セキュリティ: safe_load を常に使う

繰り返しになりますが、最も重要な注意点です。外部から受け取る可能性のあるYAMLデータ（設定ファイル、APIレスポンスなど）を読み込む際は、必ず yaml.safe_load() (PyYAML) または YAML(typ='safe') (ruamel.yaml) を使用してください。

load() (特に古いPyYAMLやLoader指定なし) は、悪意のあるコード実行 (例: CVE-2020-14343) に繋がる深刻なセキュリティリスクがあります。2017年頃からこの問題は広く認識されるようになり、多くのプロジェクトでsafe_loadへの移行が進みました。

5.2 エンコーディング

YAMLファイルはテキストファイルであり、文字エンコーディングの問題が発生することがあります。特に日本語を含む場合、UTF-8で保存・読み書きするのが一般的です。

# 読み込み時
with open('config.yaml', 'r', encoding='utf-8') as f: data = yaml.safe_load(f)
# 書き込み時
with open('output.yaml', 'w', encoding='utf-8') as f: yaml.dump(data, f, allow_unicode=True)

ファイルを扱う際は、常にencoding='utf-8'を指定することを推奨します。もし他のエンコーディング（Shift_JISなど）のファイルを読む必要がある場合は、適切に指定してください。不明な場合は、複数のエンコーディングを試すエラーハンドリングが必要になることもあります。

5.3 YAMLのバージョン

前述の通り、PyYAMLは主にYAML 1.1、ruamel.yamlはYAML 1.2をサポートします。両バージョン間には細かい非互換性があります。使用するツールやライブラリがどのバージョンを期待しているかを確認することが重要です。例えば、AWS CloudFormationはYAML 1.1をサポートしています。

5.4 エラーハンドリング

ファイルの読み書きやYAMLの解析中には様々なエラーが発生する可能性があります。

• FileNotFoundError: 指定されたファイルが存在しない。
• yaml.YAMLError: YAMLの構文エラー（インデントミス、不正な形式など）。
  • yaml.parser.ParserError, yaml.scanner.ScannerError など、より具体的なエラークラスもあります。
• UnicodeDecodeError: 指定されたエンコーディングでファイルを読み取れない。
• PermissionError: ファイルへのアクセス権がない。

適切なtry...exceptブロックを使って、これらのエラーを捕捉し、ユーザーに分かりやすいメッセージを表示したり、代替処理を行ったりするようにしましょう。

import yaml
from pathlib import Path
file_path = Path('potentially_invalid.yaml')
try: with open(file_path, 'r', encoding='utf-8') as f: data = yaml.safe_load(f) # 成功した場合の処理 print("YAMLの読み込みに成功しました。") # print(data)
except FileNotFoundError: print(f"エラー: ファイル '{file_path}' が見つかりません。")
except yaml.YAMLError as e: # YAMLErrorは構文エラーなどを含む基底クラス print(f"エラー: YAMLファイルの形式が正しくありません。") # エラーの詳細情報をログに出力するなど print(f"詳細: {e}") # 必要であれば、エラーが発生した行番号などを取得することも可能 if hasattr(e, 'problem_mark'): mark = e.problem_mark print(f"エラー箇所 (おおよそ): 行 {mark.line + 1}, 列 {mark.column + 1}")
except UnicodeDecodeError: print(f"エラー: ファイル '{file_path}' の文字コードがUTF-8ではない可能性があります。")
except PermissionError: print(f"エラー: ファイル '{file_path}' へのアクセス権がありません。")
except Exception as e: print(f"予期せぬエラーが発生しました: {e}")

5.5 クォートの扱い

YAMLでは多くの場合、文字列をクォート(' or ")で囲む必要はありません。しかし、以下のような場合はクォートが必要です。

• 値が特殊文字 (:, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `) で始まる場合。
• 値が数値や真偽値 (true, false, 123, 1.23, Yes, No など) と解釈される可能性があり、それを文字列として扱いたい場合 (例: '123', 'No')。
• 値の前後に空白を含めたい場合。

シングルクォート(')内では、シングルクォート自体は '' とエスケープします。ダブルクォート(")内では、バックスラッシュ(\)によるエスケープシーケンス（\n, \", \\ など）が利用可能です。どちらを使うかは状況に応じて選択します。

PythonでYAMLを扱うことは、設定管理やデータ交換において非常に便利です。主要なライブラリであるPyYAMLとruamel.yamlは、それぞれ特徴があります。

• PyYAML: シンプルな読み書きには十分。ただし、safe_loadの使用を徹底すること。
• ruamel.yaml: コメントや順序の保持が必要な場合、YAML 1.2準拠の動作が必要な場合に強力。Round Tripモードが特に便利。

どちらのライブラリを使うにしても、以下の点を意識することが重要です。

1. セキュリティ: 常にsafe_load相当の安全な関数を使う。
2. エンコーディング: UTF-8を基本とし、適切に指定する。
3. エラーハンドリング: ファイルI/Oやパースエラーに備える。
4. YAMLバージョン: ツールや環境に合わせたバージョンを意識する。

これらの知識を活用して、PythonプロジェクトでYAMLを効果的に使いこなし、よりクリーンで管理しやすいコードを目指しましょう！