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 document	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	list of dicts