tomllib --- TOML ファイルの解析¶
ソースコード: Lib/tomllib
このモジュールは TOML 1.1.0 (Tom's Obvious Minimal Language、https://toml.io) を解析するインターフェースを提供します。 TOML の書き込みには対応していません。
Added in version 3.11: TOML 1.0.0 に対応したモジュールとして追加されました。
バージョン 3.15 で変更: TOML 1.1.0 に対応しました。 詳しくは 新機能の説明 を参照してください。
警告
信頼できない情報源のデータを解析するときは注意してください。 悪意のある TOML 文字列によって、デコーダーが大量の CPU やメモリを消費する可能性があります。 解析するデータのサイズを制限することを推奨します。
参考
Tomli-W パッケージ はTOMLの書き込み用にこのモジュールと組み合わせて使用でき、標準ライブラリの marshal や pickle モジュールなどでユーザーによく知られている書き込みAPIを提供します。
参考
TOML Kit パッケージ は、スタイルを保持した読み書きに対応したTOMLライブラリです。存在するTOMLファイルを編集するときにこのモジュールの代わりに使用することを推奨します。
このモジュールは以下の関数を定義しています:
- tomllib.load(fp, /, *, parse_float=float)¶
TOMLファイルを読み込みます。第1引数には読み込み可能なバイナリのファイルオブジェクトを指定します。戻り値は
dictです。TOMLの型は conversion table を使用してPythonのデータ型に変換されます。parse_float は、全てのデコードされる TOML の浮動小数点数文字列に対して呼ばれます。デフォルトでは、
float(num_str)と等価です。これは TOML 浮動小数点数に対して他のデータ型やパーサ (たとえばdecimal.Decimal) を使うのに使えます。呼び出し可能オブジェクトはdictやlist以外を返す必要があり、そうでない場合はValueErrorが送出されます。無効なTOMLドキュメントの場合は
TOMLDecodeErrorが送出されます。
- tomllib.loads(s, /, *, parse_float=float)¶
strからTOMLを読み込みます。戻り値はdictです。TOMLの型は conversion table を使用してPythonのデータ型に変換されます。parse_float 引数はload()と同じ意味を持ちます。無効なTOMLドキュメントの場合は
TOMLDecodeErrorが送出されます。
次の例外がサポートされています:
- exception tomllib.TOMLDecodeError(msg, doc, pos)¶
ValueErrorのサブクラスで、以下の追加の属性を持ちます:- msg¶
フォーマットされていないエラーメッセージです。
- doc¶
パース対象の TOML ドキュメントです。
- pos¶
doc の解析に失敗したインデクスです。
- lineno¶
pos に対応する行です。
- colno¶
pos に対応する列です。
バージョン 3.14 で非推奨: 自由な形式の位置引数を渡すことは非推奨になりました。
使用例¶
TOMLファイルを解析します:
import tomllib
with open("pyproject.toml", "rb") as f:
data = tomllib.load(f)
TOMLの文字列を解析します:
import tomllib
toml_str = """
python-version = "3.11.0"
python-implementation = "CPython"
"""
data = tomllib.loads(toml_str)
変換表¶
TOML |
Python |
|---|---|
TOMLドキュメント |
辞書 |
文字列 |
文字列 |
整数 |
整数 |
浮動小数点数 |
浮動小数点数（parse_float で設定可能） |
ブール値 |
真偽値型(bool) |
オフセット付きの日時 |
datetime.datetime（ |
ローカルの日時 |
datetime.datetime（ |
ローカルの日付 |
datetime.date |
ローカルの時刻 |
datetime.time |
配列 |
リスト |
テーブル |
辞書 |
インラインテーブル |
辞書 |
テーブルの配列 |
辞書のリスト |
制限と相互運用性についての考慮事項¶
tomllib は、処理できる文書にいくつかの制限を設けています。
また、ほかの TOML パーサーでは無視してよい細部も保持します。
移植性の高い TOML ファイルを書くときは、規格が保証または推奨する機能だけを使ってください。
ここに挙げる実装の詳細は、将来の Python バージョンで変わる可能性があります。
- テーブルと辞書
TOML 仕様は、文書やテーブル内のキーと値の組について、特定の順序を保証していません。
tomllibは、ソースに現れる順に辞書の項目を読み込みます。- 整数
TOML recommends supporting integers in
range(−2**63, 2**63).tomllibは、Python の整数文字列変換の制限 (デフォルトは 4300 桁) を使います。- 浮動小数点数
TOML は少なくとも IEEE 754 binary64 の値をサポートすることを推奨しています。 そのため、10 進の有効桁数が 15 桁を超える数値は丸められる可能性が高くなります。
tomllibはデフォルトで Python のfloatを使います。 多くの一般的なプラットフォームでは、これは推奨されている binary64 です。 詳しくはsys.float_infoを参照してください。- 入れ子の深さの制限
TOML 1.1.0 は、配列やテーブルを互いに入れ子にする深さの上限を推奨していません。 将来の TOML バージョン向けに 100 という上限が提案されています。
tomllibでは、入れ子の深さは主に Python の再帰の上限によって制限されます。tomllibを呼び出すコードも、この上限に達するまでの深さを消費することに注意してください。