"tomllib" --- 剖析 TOML 檔案
****************************

在 3.11 版新加入.

**原始碼：**Lib/tomllib

======================================================================

此模組提供了剖析 TOML (Tom’s Obvious Minimal Language,
https://toml.io) 的一個介面，此模組並不支援寫入 TOML。

也參考:

  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

   "ValueError" 的子類別。


範例
====

剖析一個 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                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 内联表             | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 表数组             | 字典列表                                                                               |
+--------------------+----------------------------------------------------------------------------------------+
