本文由大侠(AhcaoZhu)原创，转载请声明。
链接: https://blog.csdn.net/Ahcao2008

Alt
@[TOC](一图看懂 toml 模块：用于解析和创建TOML(Tom’s Obvious, Minimal Language)的Python库, 资料整理+笔记（大全）)

☘️摘要

全文介绍系统内置 toml(Tom’s Obvious, Minimal Language) 模块、函数、类及类的方法和属性。
它通过代码抓取并经AI智能翻译和人工校对。
是一部不可多得的权威字典类工具书。它是系列集的一部分。后续陆续发布、敬请关注。【原创：AhcaoZhu大侠】

☘️模块图

toml-module

toml
	toml.tz
	toml.decoder
	toml.encoder

☘️类关系图

toml-class

◆object
	◆BaseException
		◆Exception
			◆ValueError
				toml.decoder.TomlDecodeError
	◆datetime.tzinfo
		toml.tz.TomlTz
	toml.decoder.CommentValue
	toml.decoder.InlineTableDict
	toml.decoder.TomlDecoder
		toml.decoder.TomlPreserveCommentDecoder
	toml.encoder.TomlEncoder
		toml.encoder.TomlArraySeparatorEncoder
		toml.encoder.TomlNumpyEncoder
		toml.encoder.TomlPathlibEncoder
		toml.encoder.TomlPreserveCommentEncoder
		toml.encoder.TomlPreserveInlineDictEncoder

☘️什么是TOML?

TOML —— Tom’s Obvious, Minimal Language.
作者 Tom Preston-Werner, Pradyun Gedam 等人。

目标：

TOML的目标是成为一种最小的配置文件格式，由于其明显的语义，它易于阅读。
TOML被设计成明确地映射到哈希表。TOML应该很容易被解析成各种语言的数据结构。
发行规范参见：https://toml.io

举例：

# This is a TOML document.
title = "TOML Example"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # First class dates
[database]
server = "192.168.1.1"
ports = [ 8000, 8001, 8002 ]
connection_max = 5000
enabled = true
[servers]
  # Indentation (tabs and/or spaces) is allowed but not required
  [servers.alpha]
  ip = "10.0.0.1"
  dc = "eqdc10"

  [servers.beta]
  ip = "10.0.0.2"
  dc = "eqdc10"

[clients]
data = [ ["gamma", "delta"], [1, 2] ]

# Line breaks are OK when inside arrays
hosts = [
  "alpha",
  "omega"
]

与其它格式兼容

TOML与用于应用程序配置和数据序列化的其他文件格式(如YAML和JSON)共享一些特性。
TOML和JSON都很简单，使用普遍的数据类型，这使得它们很容易编写代码或用机器解析。
TOML和YAML都强调人类的可读性特性，比如注释，使人们更容易理解给定行的目的。
TOML的不同之处在于，它允许注释(与JSON不同)，但保持简单性(与YAML不同)。

由于TOML明确地打算作为一种配置文件格式，所以解析它很容易，但它不打算序列化任意数据结构。
TOML总是在文件的顶层有一个哈希表，它可以很容易地将数据嵌套在它的键中，但它不允许顶层数组或浮点数，因此它不能直接序列化一些数据。
也没有标准标识TOML文件的开始或结束，这会使通过流发送TOML文件变得复杂。这些细节必须在应用层上协商。

人们经常将INI文件与TOML进行比较，因为它们在语法和用作配置文件方面具有相似性。然而，INI没有标准化的格式，而且它们不能优雅地处理一到两层以上的嵌套。

进一步阅读:
YAML 规范：
JSON 规范:
Wikipedia关于INI文件:

参见：
TOML标准

☘️模块全展开

🔵【toml】

toml, fullname=toml, file=toml_init_.py

Python模块，用于解析和发出TOML。在MIT许可下发布。

🌿统计

序号	类别	数量
4	str	7
6	list	1
8	dict	1
9	module	3
10	class	9
11	function	4
13	residual	2
14	system	10
15	private	1
16	all	27

🌿常量

str

1 spec 0.5.0

🌿模块

2 toml.tz

tz, fullname=toml.tz, file=toml\tz.py

3 toml.decoder

decoder, fullname=toml.decoder, file=toml\decoder.py

4 toml.encoder

encoder, fullname=toml.encoder, file=toml\encoder.py

🌿函数

5 load(f, _dict=<class ‘dict’>, decoder=None)

load(f, _dict=<class ‘dict’>, decoder=None), module=toml.decoder, line:113 at site-packages\toml\decoder.py

解析指定的文件或文件作为toml并返回一个字典。
    参数:
        f:文件路径打开,文件读入数组单一dict或一个文件描述符
        _dict:(可选)指定的类返回toml字典
        decoder:解码器使用
    返回:解析toml文件表示为一个字典
        提出:TypeError——TomlDecodeError:而 IOError / FileNotFoundError -当一个数组没有那么有效(现有)
    Raises:
        TypeError -- 当f是无效的类型
        TomlDecodeError: toml解码错误
        IOError / FileNotFoundError -- 当一个数组没有那么有效(已存在)
        (Python 2 / Python 3)          文件路径忽略。

6 loads(s, _dict=<class ‘dict’>, decoder=None)

loads(s, _dict=<class ‘dict’>, decoder=None), module=toml.decoder, line:165 at site-packages\toml\decoder.py

将字符串解析为toml
    参数:
        s: 要解析的字符串
        _dict: (可选)指定返回的toml字典的类
    返回:
        以字典表示的解析toml文件
    Raises:
        TypeError: 当传入非字符串时
        TomlDecodeError: 解码toml时出错

示例：

>>> import toml
>>> toml_string = """
... # This is a TOML document.
...
... title = "TOML Example"
...
... [owner]
... name = "Tom Preston-Werner"
... dob = 1979-05-27T07:32:00-08:00 # First class dates
...
... [database]
... server = "192.168.1.1"
... ports = [ 8001, 8001, 8002 ]
... connection_max = 5000
... enabled = true
...
... [servers]
...
...   # Indentation (tabs and/or spaces) is allowed but not required
...   [servers.alpha]
...   ip = "10.0.0.1"
...   dc = "eqdc10"
...
...   [servers.beta]
...   ip = "10.0.0.2"
...   dc = "eqdc10"
...
... [clients]
... data = [ ["gamma", "delta"], [1, 2] ]
...
... # Line breaks are OK when inside arrays
... hosts = [
...   "alpha",
...   "omega"
... ]
... """

>>> parsed_toml = toml.loads(toml_string)

7 dump(o, f, encoder=None)

dump(o, f, encoder=None), module=toml.encoder, line:12 at site-packages\toml\encoder.py

将dict作为toml写入文件
    参数:
        o: 对象转储到toml
        f: 文件描述符，toml应该存储在其中
        encoder: 用于构造输出字符串的 ``TomlEncoder``
    返回:
        包含字典对应的toml的字符串
    Raises:
        TypeError: 当传入文件描述符以外的任何内容时

举例：

>>> with open('new_toml_file.toml', 'w') as f:
...     new_toml_string = toml.dump(parsed_toml, f)
>>> print(new_toml_string)
title = "TOML Example"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00Z
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002,]
connection_max = 5000
enabled = true
[clients]
data = [ [ "gamma", "delta",], [ 1, 2,],]
hosts = [ "alpha", "omega",]
[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"
[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"

注意：

对于Numpy用户，默认数据类型为 np.floatX 不会被toml转换为浮点数，而是被编码为字符串。
为了解决这个问题，在保存数据时指定 TomlNumpyEncoder。

>>> import toml
>>> import numpy as np
>>> a = np.arange(0, 10, dtype=np.double)
>>> output = {'a': a}
>>> toml.dumps(output)
'a = [ "0.0", "1.0", "2.0", "3.0", "4.0", "5.0", "6.0", "7.0", "8.0", "9.0",]\n'
>>> toml.dumps(output, encoder=toml.TomlNumpyEncoder())
'a = [ 0.0, 1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0, 9.0,]\n'

8 dumps(o, encoder=None)

dumps(o, encoder=None), module=toml.encoder, line:34 at site-packages\toml\encoder.py

    字符串化的输入字典，以 toml 格式。
    参数:
        o: 转储到toml的对象
        encoder: 用于构造输出字符串的 ``TomlEncoder``
    返回:
        字符串包含与dict对应的toml
    举例:
        >>> import toml
        >>> output = {
        ... 'a': "I'm a string",
        ... 'b': ["I'm", "a", "list"],
        ... 'c': 2400
        ... }
        >>> toml.dumps(output)
        a = "I'm a string"
        b = [ "I'm", "a", "list",]
        c = 2400

举例：

>>> new_toml_string = toml.dumps(parsed_toml)
>>> print(new_toml_string)
title = "TOML Example"
[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00Z
[database]
server = "192.168.1.1"
ports = [ 8001, 8001, 8002,]
connection_max = 5000
enabled = true
[clients]
data = [ [ "gamma", "delta",], [ 1, 2,],]
hosts = [ "alpha", "omega",]
[servers.alpha]
ip = "10.0.0.1"
dc = "eqdc10"
[servers.beta]
ip = "10.0.0.2"
dc = "eqdc10"

🌿类

9 toml.decoder.TomlDecoder

TomlDecoder, toml.decoder.TomlDecoder, module=toml.decoder, line:635 at site-packages\toml\decoder.py

method

1 bounded_string(self, s)

kind=method class=TomlDecoder objtype=function line:923 at …\lib\site-packages\toml\decoder.py

2 embed_comments(self, idx, currentlevel)

kind=method class=TomlDecoder objtype=function line:1038 at …\lib\site-packages\toml\decoder.py

3 get_empty_inline_table(self)

kind=method class=TomlDecoder objtype=function line:643 at …\lib\site-packages\toml\decoder.py

4 get_empty_table(self)

kind=method class=TomlDecoder objtype=function line:640 at …\lib\site-packages\toml\decoder.py

5 load_array(self, a)

kind=method class=TomlDecoder objtype=function line:944 at …\lib\site-packages\toml\decoder.py

6 load_inline_object(self, line, currentlevel, multikey=False,

kind=method class=TomlDecoder objtype=function line:654 at …\lib\site-packages\toml\decoder.py

7 load_line(self, line, currentlevel, multikey, multibackslash)

kind=method class=TomlDecoder objtype=function line:706 at …\lib\site-packages\toml\decoder.py

8 load_value(self, v, strictly_valid=True)

kind=method class=TomlDecoder objtype=function line:810 at …\lib\site-packages\toml\decoder.py

9 preserve_comment(self, line_no, key, comment, beginline)

kind=method class=TomlDecoder objtype=function line:1035 at …\lib\site-packages\toml\decoder.py

10 toml.decoder.TomlDecodeError

TomlDecodeError, toml.decoder.TomlDecodeError, module=toml.decoder, line:50 at site-packages\toml\decoder.py

    基本的 toml异常/错误。

11 toml.decoder.TomlPreserveCommentDecoder

TomlPreserveCommentDecoder, toml.decoder.TomlPreserveCommentDecoder, module=toml.decoder, line:1042 at site-packages\toml\decoder.py

method

1 embed_comments(self, idx, currentlevel)

kind=method class=TomlPreserveCommentDecoder objtype=function line:1051 at …\lib\site-packages\toml\decoder.py

2 preserve_comment(self, line_no, key, comment, beginline)

kind=method class=TomlPreserveCommentDecoder objtype=function line:1048 at …\lib\site-packages\toml\decoder.py

12 toml.encoder.TomlEncoder

TomlEncoder, toml.encoder.TomlEncoder, module=toml.encoder, line:129 at site-packages\toml\encoder.py

method

1 dump_inline_table(self, section)

kind=method class=TomlEncoder objtype=function line:157 at …\lib\site-packages\toml\encoder.py

保持内联表的紧凑语法，而不是扩展到子表。
    [参见：](https://github.com/toml-lang/toml#user-content-inline-table)

2 dump_list(self, v)

kind=method class=TomlEncoder objtype=function line:150 at …\lib\site-packages\toml\encoder.py

3 dump_sections(self, o, sup)

kind=method class=TomlEncoder objtype=function line:182 at …\lib\site-packages\toml\encoder.py

4 dump_value(self, v)

kind=method class=TomlEncoder objtype=function line:174 at …\lib\site-packages\toml\encoder.py

5 get_empty_table(self)

kind=method class=TomlEncoder objtype=function line:147 at …\lib\site-packages\toml\encoder.py