"tomllib" --- 解析 TOML 文件
****************************

Added in version 3.11.

**源代码：** Lib/tomllib

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

此模块提供了一个解析 TOML 1.0.0 (Tom's Obvious Minimal Language,
https://toml.io) 的接口。 该模块不支持写入 TOML。

参见:

  Tomli-W 包 是一个 TOML 写入器，它可以与此模块一起使用，提供了与标准
  库用户熟悉的 "marshal" 和 "pickle" 模块类似的写入 API。

参见: TOML Kit 包 是一个兼具读取和写入功能的保留样式的 TOML 库。 它是用于
    编辑现有 TOML 文件的本模块的推荐替代品。

这个模块定义了以下函数：

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

   读取一个 TOML 文件。第一个参数应该是一个可读的二进制文件对象。返回
   "dict"。使用 转换表 将 TOML 类型转换为 Python。

   对每个要解析的 TOML 浮点数字符串调用 *parse_float*。默认情况下，这
   相当于 "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)

   拥有以下附加属性的 "ValueError" 的子类：

   msg

      未格式化的错误消息。

   doc

      正在解析的 TOML 文档。

   pos

      *doc* 解析失败的索引位置。

   lineno

      The line corresponding to *pos*.

   colno

      The column corresponding to *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 文档          | 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                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 内联表             | dict                                                                                   |
+--------------------+----------------------------------------------------------------------------------------+
| 表数组             | 字典列表                                                                               |
+--------------------+----------------------------------------------------------------------------------------+
