tomllib --- TOML ファイルの解析

ソースコード: Lib/tomllib

---

This module provides an interface for parsing TOML 1.1.0 (Tom's Obvious Minimal Language, https://toml.io). This module does not support writing TOML.

Added in version 3.11: The module was added with support for TOML 1.0.0.

バージョン 3.15 で変更: Added TOML 1.1.0 support. See the What's New for details.

警告

Be cautious when parsing data from untrusted sources. A malicious TOML string may cause the decoder to consume considerable CPU and memory resources. Limiting the size of data to be parsed is recommended.

参考

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 で変更: Added the msg, doc and pos parameters. Added the msg, doc, pos, lineno and colno attributes.

バージョン 3.14 で非推奨: Passing free-form positional arguments is deprecated.

使用例

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（tzinfo 属性は datetime.timezone のインスタンスが設定される）
ローカルの日時	datetime.datetime（tzinfo 属性は None に設定される）
ローカルの日付	datetime.date
ローカルの時刻	datetime.time
配列	リスト
テーブル	辞書
インラインテーブル	辞書
テーブルの配列	辞書のリスト

Limits and interoperability considerations

tomllib places some limits on the documents it can handle, and it preserves details that other TOML parsers are allowed to ignore. When writing portable TOML files, only use features that are guaranteed or recommended by the standard.

The implementation details listed here may change in future versions of Python.

Tables/dicts

The TOML spec does not guarantee key/value pairs in TOML documents and tables to be in any specific order.

CPython 実装の詳細: tomllib loads dictionary entries in the order they appear in the source.

整数

TOML recommends supporting integers in range(−2**63, 2**63).

CPython 実装の詳細: tomllib uses Python's limit on integer string conversion (4300 digits by default).

Floats

TOML recommends supporting at least IEEE 754 binary64 values, which means that numbers with more than 15 significant decimal digits are likely to be rounded.

CPython 実装の詳細: tomllib uses Python float by default; on many common platforms this is the recommended binary64. See sys.float_info for details.

Nesting limit

TOML 1.1.0 does not recommend a limit on how deeply arrays and tables may be nested inside one another. (A limit of 100 has been proposed for a future version of TOML.)

CPython 実装の詳細: In tomllib, the nesting level is mainly limited by Python's recursion limit. Note that code that calls tomllib may contribute to the limit.