# `tomllib` --- 剖析 TOML 檔案

在 3.11 版被加入.

原始碼：Lib/tomllib

此模組提供了剖析 TOML 1.0.0 (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
偏移日期時間 (offset date-time) | datetime.datetime（設定 `tzinfo` 屬性為 `datetime.timezone` 的實例）
本地日期時間 (local date-time) | datetime.datetime（設定 `tzinfo` 為 `None`）
本地日期 (local date) | datetime.date
本地時間 (local time) | datetime.time
array | list
table | dict
行內表格 (inline table) | dict
表格陣列 (array of tables) | dict 串列 (list of dicts)