"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 で変更: *msg*、*doc*、*pos* 引数を追加しました。
   "msg"、"doc"、"pos"、"lineno"、"colno" 属性を追加しました。

   バージョン 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（"tzinfo" 属性は "datetime.timezone" のインスタンス が設定される）   |
| 時                 |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| ローカルの日時     | datetime.datetime（"tzinfo" 属性は "None" に設定される）                               |
+--------------------+----------------------------------------------------------------------------------------+
| ローカルの日付     | 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" を呼び出すコードも、この上限に達するまでの
   深さを消費することに注意してください。
