CPython tomllib 模块深度解析TOML 文件解析的标准库 API、类型映射与源码实现【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpythontomllib是 CPython 标准库中用于解析 TOMLToms Obvious Minimal Language文件的官方模块自 Python 3.11 引入并在 3.15 中将支持升级到 TOML 1.1.0。本文基于仓库中的 模块文档 与 实现源码完整讲解load/loads的 API 语义、parse_float自定义浮点解析、TOMLDecodeError错误定位机制、TOML 到 Python 的完整类型转换表并深入源码剖析解析主循环、键值写入规则与安全防护措施最后结合 3.15 Whats New 说明 TOML 1.1.0 新增语法的实际变化。一、模块定位只读解析器与版本演进模块文档开篇即明确了tomllib的边界功能提供解析 TOML 1.1.0 文档的接口限制该模块不支持写入 TOMLdoes not support writing TOML版本模块随 Python 3.11 加入初始支持 TOML 1.0.0Python 3.15 起支持 TOML 1.1.0见下文 第五节。对于需要写出 TOML 的场景官方文档推荐搭配两个第三方包使用第三方包定位适用场景Tomli-WPyPI: tomli-w纯写端API 风格与标准库marshal、pickle一致只需生成 TOML读端可用tomllibTOML KitPyPI: tomlkit保留格式的读写库编辑已有 TOML 文件、保持注释与排版安全提示文档原文以 warning 框强调解析来自不可信来源的数据时要格外谨慎——恶意的 TOML 字符串可能让解码器消耗大量 CPU 和内存资源建议限制待解析数据的大小。这一点在源码中也有对应的防御设计见 第四节 的MAX_KEY_PARTS。二、核心 API 详解2.1tomllib.load(fp, /, *, parse_floatfloat)读取并解析一个 TOML 文件返回dict。要点如下第一个参数fp必须是可读取的二进制文件对象binary file object即用open(foo.toml, rb)方式打开TOML 各类型按 第三节转换表 转为 Python 对象parse_float参数仅关键字每个 TOML 浮点数的字符串形式都会传给该可调用对象默认等价于float(num_str)可换成decimal.Decimal等该可调用对象不得返回dict或list否则抛出ValueError遇到非法 TOML 文档时抛出TOMLDecodeError。从 源码实现 可以看到其具体行为def load(fp: IO[bytes], /, *, parse_float: ParseFloat float) - dict[str, Any]: Parse TOML from a binary file object. b fp.read() try: s b.decode() except AttributeError: raise TypeError( File must be opened in binary mode, e.g. use open(foo.toml, rb) ) from None return loads(s, parse_floatparse_float)两个细节值得注意b.decode()使用默认的 UTF-8 解码TOML 规范要求 UTF-8 编码如果你传入了文本模式文件对象fp.read()返回strstr.decode()不存在于是被转换为一条信息明确的TypeError直接提示「应以二进制模式打开文件」——这比静默出错更利于排查。2.2tomllib.loads(s, /, *, parse_floatfloat)从str对象解析 TOML返回dictparse_float语义与load相同。实现 中有两处规范层面的预处理# 规范允许甚至在字符串字面量内把 \r\n 转换为 \n这里统一做掉以简化解析 src s.replace(\r\n, \n)先把 CRLF 换行归一化为 LF符合 TOML 规范的换行处理要求若传入的不是str例如bytes会抛出TypeError: Expected str object, not bytes这类带类型名的错误——因此「读文件用load、读字符串用loads」是硬性约定二者不互相兜底。parse_float在进入解析前先经过make_safe_parse_float包装见 2.4 节。2.3 文档示例可直接复制运行以下两段示例完整继承自 模块文档解析 TOML 文件注意rb二进制模式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)再补一个使用parse_float的高精度场景decimal.Decimal避免二进制浮点误差import tomllib from decimal import Decimal toml_str price 19.99\nqty 3.5 data tomllib.loads(toml_str, parse_floatDecimal) # data {price: Decimal(19.99), qty: Decimal(3.5)}2.4parse_float的安全包装文档要求parse_float不得返回dict或list。源码 用装饰器方式强制了这一点def make_safe_parse_float(parse_float: ParseFloat) - ParseFloat: # 默认的 float 永远不返回非法类型直接透传以省开销 if parse_float is float: return float def safe_parse_float(float_str: str) - Any: float_value parse_float(float_str) if isinstance(float_value, (dict, list)): raise ValueError(parse_float must not return dicts or lists) return float_value return safe_parse_float禁止返回容器类型的动机写在注释里dict/list会与解析出的 TOML table / array 混淆干扰解析器内部对「嵌套是否可继续写入」的判断。另外从 值解析函数 可以看到inf、-inf、nan等特殊浮点字面量同样走parse_float通道——如果你传入了自定义解析器这些字面量也会被它处理。三、TOML → Python 类型转换表这是原文档的核心参考表锚点toml-to-py-tableload/loads的返回值严格遵循此表TOMLPythonTOML documentdictstringstrintegerintfloatfloat可用parse_float自定义booleanbooloffset date-timedatetime.datetimetzinfo为datetime.timezone实例local date-timedatetime.datetimetzinfo为Nonelocal datedatetime.datelocal timedatetime.timearraylisttabledictinline tabledictarray of tableslistofdict结合 日期时间源码 可以进一步确认表中语义的实现细节offset date-time带Z/z时区用timezone.utc带±HH:MM偏移时通过cached_tz构造timezone实例且该函数带lru_cache(maxsizeNone)——源码注释解释了为何无需限制缓存大小能匹配上正则的偏移组合最多只有 24 × 60 × 2 2880 种缓存天然有界local date-time正则匹配到时间但没有时区信息时tzinfo置为Nonelocal date只有日期部分无时间部分时返回datetime.date而非datetime整数数字正则见下匹配后若不含floatpart分组则调用int(match.group(), 0)转换——base0表示自动识别0x十六进制、0o八进制、0b二进制前缀与 Python 字面量规则一致。数字与时间的识别依赖 Lib/tomllib/_re.py 中编译好的正则RE_NUMBER: Final re.compile( r 0 |(?: x0-9A-Fa-f* # hex | b01* # bin | o0-7* # oct ) | [-]?(?:0|1-9*) # dec, integer part (?Pfloatpart (?:\.0-9*)? # optional fractional part (?:[eE][-]?0-9*)? # optional exponent part ) , flagsre.VERBOSE, )即整数部分禁止前导零、下划线分隔符只允许出现在数字之间只要出现小数部分或指数部分整串就会交给parse_float处理。四、解析主循环与写入规则源码剖析loads的核心是一个「逐条语句」的主循环源码结构 非常清晰每个循环迭代处理一行语句跳过行首空白skip_chars(src, pos, TOML_WS)分派语句类型文件结尾 / 空行 / 注释 /key value键值对 /[table]建表 /[[array of tables]]追加数组表跳过行尾注释skip_comment期望行尾或文件结尾否则抛出TOMLDecodeError(Expected newline or end of document after a statement, ...)。其中[开头的语句通过再看第二个字符区分单表与数组表源码[[走create_list_rule单个[走create_dict_rule。4.1Flags防止重复声明与覆盖的位标记系统TOML 有几条关键不变量实现上由 Flags 类 用两个标志位维护FROZEN标记不可变命名空间inline array / inline tableEXPLICIT_NEST标记已显式创建的嵌套表之后不能再被[table]语法打开。典型检查逻辑见 create_dict_rule同一张表声明两次Cannot declare [a, b] twice、往已有非表值上继续建表Cannot overwrite a value都会在这里被拦截而 key_value_rule 则保证点键dotted key不会重定义已有表、不会写入 FROZEN 命名空间且解析出的 dict/list 值会递归地把整棵子树标记为 FROZEN。4.2NestedDict结果树的构建结果结构由 NestedDict 维护get_or_create_nest(key)沿键路径下钻缺失的中间层自动创建为{}若路径中途遇到list数组表的值则自动下钻到最后一个元素cont[-1]——这正是「[a.b]出现在[[a]]之后时后续键值写入最新一个数组表元素」这一 TOML 行为的实现append_nest_to_list(key)处理[[a.b]]键已存在则向列表追加新{}不存在则初始化为[{}]。4.3 值解析的分派顺序parse_value 按「检查速度与出现概率」排序做分派值得注意的顺序是/开头 → 单行或多行 basic / literal 字符串true/false前缀匹配布尔[→ 数组{→ 内联表先匹配日期时间正则再匹配本地时间最后才匹配数字——源码注释明确说明数字正则是贪婪的任何以十进制数字开头的类型它都能吃掉所以必须放在日期/时间之后特殊浮点±inf/±nan走parse_float都不匹配则TOMLDecodeError(Invalid value, ...)。字符串方面basic 字符串支持\b \t \n \f \r \e \ \\以及\xHH/\uHHHH/\UHHHHHHHH十六进制转义is_unicode_scalar_value会校验其确为合法 Unicode 标量值多行字符串支持「反斜杠换行」的空白折叠转义。4.4 针对恶意输入的两道防线与文档中的安全警告相呼应源码里有两处显式防护键段数上限源码# 路径性过长的键段数会引发二次方复杂度例如 Flags.is_。 # 虽然当前解析键并不用递归但键命名了一个递归结构 # 因此用 getrecursionlimit() 与 RecursionError 来限制它是合理的。 MAX_KEY_PARTS: Final sys.getrecursionlimit()点键段数超过sys.getrecursionlimit()时抛出RecursionError阻断二次方复杂度退化parse_float包装见 2.4 节防止自定义解析器污染解析器的容器判断。五、TOML 1.1.0 新特性Python 3.15 起Whats New in Python 3.15 的tomllib小节锚点whatsnew315-tomllib-1-1-0说明了这次升级是向后兼容的所有合法的 TOML 1.0.0 文档解析结果不变。按官方 TOML 变更记录具体新增语法有三类内联表允许换行与尾随逗号。此前内联表必须写在单行且不能以逗号结尾现在以下写法合法tbl { key a string, moar-tbl { key 1, }, }basic 字符串新增\xHH与\e转义\xHH针对码点小于 255 的字符null null byte: \x00; letter a: \x61 csi \e[日期与时间中的秒变为可选dt 2010-02-03 14:15 t 14:15这三项能力分别对应源码中的 parse_inline_table通过skip_comments_and_array_ws跳过换行与逗号天然容忍尾随逗号、parse_basic_str_escape\\x分支调用parse_hex_char长度 2以及 RE_DATETIME / _TIME_RE_STR秒与小数秒均为可选分组。六、TOMLDecodeError错误信息的定位机制文档定义的异常签名与属性TOMLDecodeError(msg, doc, pos)它是ValueError的子类附带以下属性属性含义msg未格式化的错误消息doc正在解析的 TOML 文档pos解析失败处在doc中的索引linenopos对应的行号colnopos对应的列号版本说明3.14新增msg、doc、pos三个参数及上述五个属性3.14 起弃用以自由位置参数方式传参已弃用会触发DeprecationWarning见 源码 中的DEPRECATED_DEFAULT哨兵逻辑。从 实现 可见行列号是如何从pos推导的lineno doc.count(\n, 0, pos) 1 if lineno 1: colno pos 1 else: colno pos - doc.rindex(\n, 0, pos) if pos len(doc): coord_repr end of document else: coord_repr fline {lineno}, column {colno} errmsg f{msg} (at {coord_repr})即str(exc)会得到形如Expected after a key in a key/value pair (at line 2, column 5)的消息失败位置在文档末尾时显示为(at end of document)。这意味着捕获异常后可以直接用exc.lineno/exc.colno做 IDE 式报错或日志定位而exc.doc让你无需重新持有原文即可输出完整上下文。模块包结构一览纯 Python 实现无 C 扩展文件职责Lib/tomllib/init.py公开loads、load、TOMLDecodeError并把异常的__module__伪装为本包使TOMLDecodeError看起来定义于tomllibLib/tomllib/_parser.py解析主循环、键/表/值规则、Flags、TOMLDecodeError通过__lazy_modules__延迟导入_reLib/tomllib/_re.py数字/日期/时间正则及匹配结果到int/float/datetime的转换Lib/tomllib/_types.pyParseFloat、Key、Pos等类型别名行为与错误路径的回归覆盖在 Lib/test/test_tomllib/ 测试包中如test_data.py、test_error.py、test_misc.py可作实现细节的进一步验证入口。七、实践要点小结二进制模式打开文件open(path, rb)配tomllib.load字符串走tomllib.loads传错类型会收到明确的TypeError提示高精度金额/坐标用parse_floatDecimal且记住±inf、±nan也走该回调错误处理捕获TOMLDecodeError而非笼统的ValueError直接读lineno/colno属性定位问题行以 3.14 的msg/doc/pos三参数构造异常避免使用已弃用的自由位置参数不可信来源限制输入体积后再解析源码中的MAX_KEY_PARTS只能防键深度攻击不能替你挡下所有恶意负载需要写出或保格式编辑 TOMLtomllib只管读写端按文档建议选用Tomli-W或TOML Kit版本前提本文涉及 TOML 1.1.0 语法示例需 Python 3.15TOMLDecodeError的属性化签名需 3.14模块本身需 3.11。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
CPython tomllib 模块深度解析：TOML 文件解析的标准库 API、类型映射与源码实现
CPython tomllib 模块深度解析TOML 文件解析的标准库 API、类型映射与源码实现【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpythontomllib是 CPython 标准库中用于解析 TOMLToms Obvious Minimal Language文件的官方模块自 Python 3.11 引入并在 3.15 中将支持升级到 TOML 1.1.0。本文基于仓库中的 模块文档 与 实现源码完整讲解load/loads的 API 语义、parse_float自定义浮点解析、TOMLDecodeError错误定位机制、TOML 到 Python 的完整类型转换表并深入源码剖析解析主循环、键值写入规则与安全防护措施最后结合 3.15 Whats New 说明 TOML 1.1.0 新增语法的实际变化。一、模块定位只读解析器与版本演进模块文档开篇即明确了tomllib的边界功能提供解析 TOML 1.1.0 文档的接口限制该模块不支持写入 TOMLdoes not support writing TOML版本模块随 Python 3.11 加入初始支持 TOML 1.0.0Python 3.15 起支持 TOML 1.1.0见下文 第五节。对于需要写出 TOML 的场景官方文档推荐搭配两个第三方包使用第三方包定位适用场景Tomli-WPyPI: tomli-w纯写端API 风格与标准库marshal、pickle一致只需生成 TOML读端可用tomllibTOML KitPyPI: tomlkit保留格式的读写库编辑已有 TOML 文件、保持注释与排版安全提示文档原文以 warning 框强调解析来自不可信来源的数据时要格外谨慎——恶意的 TOML 字符串可能让解码器消耗大量 CPU 和内存资源建议限制待解析数据的大小。这一点在源码中也有对应的防御设计见 第四节 的MAX_KEY_PARTS。二、核心 API 详解2.1tomllib.load(fp, /, *, parse_floatfloat)读取并解析一个 TOML 文件返回dict。要点如下第一个参数fp必须是可读取的二进制文件对象binary file object即用open(foo.toml, rb)方式打开TOML 各类型按 第三节转换表 转为 Python 对象parse_float参数仅关键字每个 TOML 浮点数的字符串形式都会传给该可调用对象默认等价于float(num_str)可换成decimal.Decimal等该可调用对象不得返回dict或list否则抛出ValueError遇到非法 TOML 文档时抛出TOMLDecodeError。从 源码实现 可以看到其具体行为def load(fp: IO[bytes], /, *, parse_float: ParseFloat float) - dict[str, Any]: Parse TOML from a binary file object. b fp.read() try: s b.decode() except AttributeError: raise TypeError( File must be opened in binary mode, e.g. use open(foo.toml, rb) ) from None return loads(s, parse_floatparse_float)两个细节值得注意b.decode()使用默认的 UTF-8 解码TOML 规范要求 UTF-8 编码如果你传入了文本模式文件对象fp.read()返回strstr.decode()不存在于是被转换为一条信息明确的TypeError直接提示「应以二进制模式打开文件」——这比静默出错更利于排查。2.2tomllib.loads(s, /, *, parse_floatfloat)从str对象解析 TOML返回dictparse_float语义与load相同。实现 中有两处规范层面的预处理# 规范允许甚至在字符串字面量内把 \r\n 转换为 \n这里统一做掉以简化解析 src s.replace(\r\n, \n)先把 CRLF 换行归一化为 LF符合 TOML 规范的换行处理要求若传入的不是str例如bytes会抛出TypeError: Expected str object, not bytes这类带类型名的错误——因此「读文件用load、读字符串用loads」是硬性约定二者不互相兜底。parse_float在进入解析前先经过make_safe_parse_float包装见 2.4 节。2.3 文档示例可直接复制运行以下两段示例完整继承自 模块文档解析 TOML 文件注意rb二进制模式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)再补一个使用parse_float的高精度场景decimal.Decimal避免二进制浮点误差import tomllib from decimal import Decimal toml_str price 19.99\nqty 3.5 data tomllib.loads(toml_str, parse_floatDecimal) # data {price: Decimal(19.99), qty: Decimal(3.5)}2.4parse_float的安全包装文档要求parse_float不得返回dict或list。源码 用装饰器方式强制了这一点def make_safe_parse_float(parse_float: ParseFloat) - ParseFloat: # 默认的 float 永远不返回非法类型直接透传以省开销 if parse_float is float: return float def safe_parse_float(float_str: str) - Any: float_value parse_float(float_str) if isinstance(float_value, (dict, list)): raise ValueError(parse_float must not return dicts or lists) return float_value return safe_parse_float禁止返回容器类型的动机写在注释里dict/list会与解析出的 TOML table / array 混淆干扰解析器内部对「嵌套是否可继续写入」的判断。另外从 值解析函数 可以看到inf、-inf、nan等特殊浮点字面量同样走parse_float通道——如果你传入了自定义解析器这些字面量也会被它处理。三、TOML → Python 类型转换表这是原文档的核心参考表锚点toml-to-py-tableload/loads的返回值严格遵循此表TOMLPythonTOML documentdictstringstrintegerintfloatfloat可用parse_float自定义booleanbooloffset date-timedatetime.datetimetzinfo为datetime.timezone实例local date-timedatetime.datetimetzinfo为Nonelocal datedatetime.datelocal timedatetime.timearraylisttabledictinline tabledictarray of tableslistofdict结合 日期时间源码 可以进一步确认表中语义的实现细节offset date-time带Z/z时区用timezone.utc带±HH:MM偏移时通过cached_tz构造timezone实例且该函数带lru_cache(maxsizeNone)——源码注释解释了为何无需限制缓存大小能匹配上正则的偏移组合最多只有 24 × 60 × 2 2880 种缓存天然有界local date-time正则匹配到时间但没有时区信息时tzinfo置为Nonelocal date只有日期部分无时间部分时返回datetime.date而非datetime整数数字正则见下匹配后若不含floatpart分组则调用int(match.group(), 0)转换——base0表示自动识别0x十六进制、0o八进制、0b二进制前缀与 Python 字面量规则一致。数字与时间的识别依赖 Lib/tomllib/_re.py 中编译好的正则RE_NUMBER: Final re.compile( r 0 |(?: x0-9A-Fa-f* # hex | b01* # bin | o0-7* # oct ) | [-]?(?:0|1-9*) # dec, integer part (?Pfloatpart (?:\.0-9*)? # optional fractional part (?:[eE][-]?0-9*)? # optional exponent part ) , flagsre.VERBOSE, )即整数部分禁止前导零、下划线分隔符只允许出现在数字之间只要出现小数部分或指数部分整串就会交给parse_float处理。四、解析主循环与写入规则源码剖析loads的核心是一个「逐条语句」的主循环源码结构 非常清晰每个循环迭代处理一行语句跳过行首空白skip_chars(src, pos, TOML_WS)分派语句类型文件结尾 / 空行 / 注释 /key value键值对 /[table]建表 /[[array of tables]]追加数组表跳过行尾注释skip_comment期望行尾或文件结尾否则抛出TOMLDecodeError(Expected newline or end of document after a statement, ...)。其中[开头的语句通过再看第二个字符区分单表与数组表源码[[走create_list_rule单个[走create_dict_rule。4.1Flags防止重复声明与覆盖的位标记系统TOML 有几条关键不变量实现上由 Flags 类 用两个标志位维护FROZEN标记不可变命名空间inline array / inline tableEXPLICIT_NEST标记已显式创建的嵌套表之后不能再被[table]语法打开。典型检查逻辑见 create_dict_rule同一张表声明两次Cannot declare [a, b] twice、往已有非表值上继续建表Cannot overwrite a value都会在这里被拦截而 key_value_rule 则保证点键dotted key不会重定义已有表、不会写入 FROZEN 命名空间且解析出的 dict/list 值会递归地把整棵子树标记为 FROZEN。4.2NestedDict结果树的构建结果结构由 NestedDict 维护get_or_create_nest(key)沿键路径下钻缺失的中间层自动创建为{}若路径中途遇到list数组表的值则自动下钻到最后一个元素cont[-1]——这正是「[a.b]出现在[[a]]之后时后续键值写入最新一个数组表元素」这一 TOML 行为的实现append_nest_to_list(key)处理[[a.b]]键已存在则向列表追加新{}不存在则初始化为[{}]。4.3 值解析的分派顺序parse_value 按「检查速度与出现概率」排序做分派值得注意的顺序是/开头 → 单行或多行 basic / literal 字符串true/false前缀匹配布尔[→ 数组{→ 内联表先匹配日期时间正则再匹配本地时间最后才匹配数字——源码注释明确说明数字正则是贪婪的任何以十进制数字开头的类型它都能吃掉所以必须放在日期/时间之后特殊浮点±inf/±nan走parse_float都不匹配则TOMLDecodeError(Invalid value, ...)。字符串方面basic 字符串支持\b \t \n \f \r \e \ \\以及\xHH/\uHHHH/\UHHHHHHHH十六进制转义is_unicode_scalar_value会校验其确为合法 Unicode 标量值多行字符串支持「反斜杠换行」的空白折叠转义。4.4 针对恶意输入的两道防线与文档中的安全警告相呼应源码里有两处显式防护键段数上限源码# 路径性过长的键段数会引发二次方复杂度例如 Flags.is_。 # 虽然当前解析键并不用递归但键命名了一个递归结构 # 因此用 getrecursionlimit() 与 RecursionError 来限制它是合理的。 MAX_KEY_PARTS: Final sys.getrecursionlimit()点键段数超过sys.getrecursionlimit()时抛出RecursionError阻断二次方复杂度退化parse_float包装见 2.4 节防止自定义解析器污染解析器的容器判断。五、TOML 1.1.0 新特性Python 3.15 起Whats New in Python 3.15 的tomllib小节锚点whatsnew315-tomllib-1-1-0说明了这次升级是向后兼容的所有合法的 TOML 1.0.0 文档解析结果不变。按官方 TOML 变更记录具体新增语法有三类内联表允许换行与尾随逗号。此前内联表必须写在单行且不能以逗号结尾现在以下写法合法tbl { key a string, moar-tbl { key 1, }, }basic 字符串新增\xHH与\e转义\xHH针对码点小于 255 的字符null null byte: \x00; letter a: \x61 csi \e[日期与时间中的秒变为可选dt 2010-02-03 14:15 t 14:15这三项能力分别对应源码中的 parse_inline_table通过skip_comments_and_array_ws跳过换行与逗号天然容忍尾随逗号、parse_basic_str_escape\\x分支调用parse_hex_char长度 2以及 RE_DATETIME / _TIME_RE_STR秒与小数秒均为可选分组。六、TOMLDecodeError错误信息的定位机制文档定义的异常签名与属性TOMLDecodeError(msg, doc, pos)它是ValueError的子类附带以下属性属性含义msg未格式化的错误消息doc正在解析的 TOML 文档pos解析失败处在doc中的索引linenopos对应的行号colnopos对应的列号版本说明3.14新增msg、doc、pos三个参数及上述五个属性3.14 起弃用以自由位置参数方式传参已弃用会触发DeprecationWarning见 源码 中的DEPRECATED_DEFAULT哨兵逻辑。从 实现 可见行列号是如何从pos推导的lineno doc.count(\n, 0, pos) 1 if lineno 1: colno pos 1 else: colno pos - doc.rindex(\n, 0, pos) if pos len(doc): coord_repr end of document else: coord_repr fline {lineno}, column {colno} errmsg f{msg} (at {coord_repr})即str(exc)会得到形如Expected after a key in a key/value pair (at line 2, column 5)的消息失败位置在文档末尾时显示为(at end of document)。这意味着捕获异常后可以直接用exc.lineno/exc.colno做 IDE 式报错或日志定位而exc.doc让你无需重新持有原文即可输出完整上下文。模块包结构一览纯 Python 实现无 C 扩展文件职责Lib/tomllib/init.py公开loads、load、TOMLDecodeError并把异常的__module__伪装为本包使TOMLDecodeError看起来定义于tomllibLib/tomllib/_parser.py解析主循环、键/表/值规则、Flags、TOMLDecodeError通过__lazy_modules__延迟导入_reLib/tomllib/_re.py数字/日期/时间正则及匹配结果到int/float/datetime的转换Lib/tomllib/_types.pyParseFloat、Key、Pos等类型别名行为与错误路径的回归覆盖在 Lib/test/test_tomllib/ 测试包中如test_data.py、test_error.py、test_misc.py可作实现细节的进一步验证入口。七、实践要点小结二进制模式打开文件open(path, rb)配tomllib.load字符串走tomllib.loads传错类型会收到明确的TypeError提示高精度金额/坐标用parse_floatDecimal且记住±inf、±nan也走该回调错误处理捕获TOMLDecodeError而非笼统的ValueError直接读lineno/colno属性定位问题行以 3.14 的msg/doc/pos三参数构造异常避免使用已弃用的自由位置参数不可信来源限制输入体积后再解析源码中的MAX_KEY_PARTS只能防键深度攻击不能替你挡下所有恶意负载需要写出或保格式编辑 TOMLtomllib只管读写端按文档建议选用Tomli-W或TOML Kit版本前提本文涉及 TOML 1.1.0 语法示例需 Python 3.15TOMLDecodeError的属性化签名需 3.14模块本身需 3.11。【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
