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

在 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 工具套件是一個保留風格且具有讀寫能力的 TOML 函式庫。若要編輯已
     存在的 TOML 文件，建議用它來替換此模組。

此模組定義了以下函式：

tomllib.load(fp, /, *, parse_float=float)

   讀取一個 TOML 檔案。第一個引數應為一個可讀取的二進位檔案物件。回傳
   一個 "dict"。用這個轉換表將 TOML 型別轉換成 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 型別成 Python 的。*parse_float* 引數和 "load()" 中的相同。

   不合格的 TOML 文件會使得 "TOMLDecodeError" 被引發。

以下為可用的例外：

exception tomllib.TOMLDecodeError(msg, doc, pos)

   Subclass of "ValueError" with the following additional attributes:

   msg

      The unformatted error message.

   doc

      The TOML document being parsed.

   pos

      The index of *doc* where parsing failed.

   lineno

      The line corresponding to *pos*.

   colno

      The column corresponding to *pos*.

   在 3.14 版的變更: Added the *msg*, *doc* and *pos* parameters.
   Added the "msg", "doc", "pos", "lineno" and "colno" attributes.

   在 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 文件          | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| string             | str                                                                                    |
+--------------------+----------------------------------------------------------------------------------------+
| integer            | int                                                                                    |
+--------------------+----------------------------------------------------------------------------------------+
| float              | float（可透過 *parse_float* 調整）                                                     |
+--------------------+----------------------------------------------------------------------------------------+
| boolean            | bool                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 偏移日期時間       | datetime.datetime（設定 "tzinfo" 屬性為 "datetime.timezone" 的實例）                   |
| (offset date-time) |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| 本地日期時間       | datetime.datetime（設定 "tzinfo" 為 "None"）                                           |
| (local date-time)  |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| 本地日期 (local    | datetime.date                                                                          |
| date)              |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| 本地時間 (local    | datetime.time                                                                          |
| time)              |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| array              | list                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| table              | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 行內表格 (inline   | dict                                                                                   |
| table)             |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+
| 表格陣列 (array of | dict 串列 (list of dicts)                                                              |
| tables)            |                                                                                        |
+--------------------+----------------------------------------------------------------------------------------+


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.

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