"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.
