Lian
文章目录 站点概览

Lian

make thing better and simpler.

98 文章
64 标签

Toml文件使用指南

发布于 2023-02-24 | 标签: python 、 config | 8分钟 | 1519字数

一. 前言

TOML aims to be a minimal configuration file format that's easy to read due to obvious semantics. TOML is designed to map unambiguously to a hash table. TOML should be easy to parse into data structures in a wide variety of languages.

toml-lang/toml

在了解这个文件格式前, 需要了解以下配置文件的常见格式.

  • json, json格式可以说是互联网中最重要的数据交换载体, 简洁明了, 轻量, 但是唯一遗憾的是不支持注释.
  • ini, 作为一种非常简单易用的格式, 但是不支持复杂的配置, 不支持数字(仅限于字符串), 支持注释, windows上相对流行.
  • xml, 一个逐步退出历史舞台的文件格式, 过于臃肿.
  • yaml, 支持复杂的配置(号称json的扩展版), 但是可阅读性较差?书写规条较多?.

简而言之, 作为一个好用的配置文件, 既需要数据易于存储/读取(同时需要有效数据密度高), 同时也需要有较好的阅读体验. 以json为例, 假如不进行格式化, 将难以阅读其内容.

而Toml就号称满足上述要求:

TOML 旨在成为一个语义明显且易于阅读的最小化配置文件格式.TOML 被设计成可以无歧义地映射为哈希表.TOML 应该能很容易地被解析成各种语言中的数据结构.

目前主流的语言多已支持这种文件格式, 详情见v1.0.0 compliant

二. 数据类型

支持以下数据内容

  • 键/值对
  • 数组
  • 表
  • 内联表
  • 表数组
  • 整数 & 浮点数
  • 布尔值
  • 日期 & 时刻带可选的时区偏移

三. 规格

  • TOML 是大小写敏感的.
  • TOML 文件必须是合法的 UTF-8 编码的 Unicode 文档.
  • 空白是指制表符(0x09)或空格(0x20).
  • 换行是指 LF(0x0A)或 CRLF(0x0D 0x0A).

四. 使用

在python下

pip show toml
#
pip install toml

以官方文档的示例来看一下

# This is a TOML document. # 注释

title = "TOML Example" # 字符串

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00 # 日期, 带有时区偏移

[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"
] # 字典
  • 支持注释
  • 易于阅读
  • 格式相对宽松(不像yaml?)
import toml

str_toml = '''
# 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"
]
'''

4.1 字符串

# 得到字典
toml.loads(str_toml)

{'title': 'TOML Example',
 'owner': {'name': 'Tom Preston-Werner',
  'dob': datetime.datetime(1979, 5, 27, 7, 32, tzinfo=<toml.tz.TomlTz object at 0x000001F267411BB0>)},
 'database': {'server': '192.168.1.1',
  'ports': [8000, 8001, 8002],
  'connection_max': 5000,
  'enabled': True},
 'servers': {'alpha': {'ip': '10.0.0.1', 'dc': 'eqdc10'},
  'beta': {'ip': '10.0.0.2', 'dc': 'eqdc10'}},
 'clients': {'data': [['gamma', 'delta'], [1, 2]],
  'hosts': ['alpha', 'omega']}}

p_toml = toml.loads(str_toml)

# 将字典解析为字符串
toml.dumps(p_toml)

'title = "TOML Example"\n\n[owner]\nname = "Tom Preston-Werner"\ndob = 1979-05-27T07:32:00-08:00\n\n[database]\nserver = "192.168.1.1"\nports = [ 8000, 8001, 8002,]\nconnection_max = 5000\nenabled = true\n\n[clients]\ndata = [ [ "gamma", "delta",], [ 1, 2,],]\nhosts = [ "alpha", "omega",]\n\n[servers.alpha]\nip = "10.0.0.1"\ndc = "eqdc10"\n\n[servers.beta]\nip = "10.0.0.2"\ndc = "eqdc10"\n'

4.2 文件

# 读取文件
toml.load('test.toml')

{'title': 'TOML Example',
 'owner': {'name': 'Tom Preston-Werner',
  'dob': datetime.datetime(1979, 5, 27, 7, 32, tzinfo=<toml.tz.TomlTz object at 0x000001F267411C70>)},
 'database': {'server': '192.168.1.1',
  'ports': [8000, 8001, 8002],
  'connection_max': 5000,
  'enabled': True},
 'servers': {'alpha': {'ip': '10.0.0.1', 'dc': 'eqdc10'},
  'beta': {'ip': '10.0.0.2', 'dc': 'eqdc10'}},
 'clients': {'data': [['gamma', 'delta'], [1, 2]],
  'hosts': ['alpha', 'omega']}}

# 写入
with open('a.toml', mode='w', encoding='utf-8') as f:
    res = toml.dump(p_toml, f)

 res

'title = "TOML Example"\n\n[owner]\nname = "Tom Preston-Werner"\ndob = 1979-05-27T07:32:00-08:00\n\n[database]\nserver = "192.168.1.1"\nports = [ 8000, 8001, 8002,]\nconnection_max = 5000\nenabled = true\n\n[clients]\ndata = [ [ "gamma", "delta",], [ 1, 2,],]\nhosts = [ "alpha", "omega",]\n\n[servers.alpha]\nip = "10.0.0.1"\ndc = "eqdc10"\n\n[servers.beta]\nip = "10.0.0.2"\ndc = "eqdc10"\n'

五. 问题

  • 局部数据如何修改?
  • 修改后写入, 注释如何保持?

就目前使用看来, 暂时还没有看出什么绝对优势的地方, 其操作基本还是延续json的操作.

六. API Reference

  • toml.load(f, _dict=dict)
    Parse a file or a list of files as TOML and return a dictionary.

    将一个文件或者文件列表转为字典

    • Args:
      f: A path to a file, list of filepaths (to be read into single object) or a file descriptor

    • _dict: The class of the dictionary object to be returned

    • Returns:
      A dictionary (or object _dict) containing parsed TOML data

    • Raises:
      TypeError: When f is an invalid type or is a list containing invalid types

      TomlDecodeError: When an error occurs while decoding the file(s)

  • toml.loads(s, _dict=dict)
    Parse a TOML-formatted string to a dictionary.

    解析toml格式的字符串到字典

    • Args:
      s: The TOML-formatted string to be parsed

    • _dict: Specifies the class of the returned toml dictionary

    • Returns:
      A dictionary (or object _dict) containing parsed TOML data

    • Raises:
      TypeError: When a non-string object is passed

      TomlDecodeError: When an error occurs while decoding the TOML-formatted string

  • toml.dump(o, f, encoder=None)
    Write a dictionary to a file containing TOML-formatted data

    将字典写到toml格式的文件

    • Args:
      o: An object to be converted into TOML
    • f: A File descriptor where the TOML-formatted output should be stored
    • encoder: An instance of TomlEncoder (or subclass) for encoding the object. If None, will default to TomlEncoder
    • Returns:
      A string containing the TOML-formatted data corresponding to object o
    • Raises:
      TypeError: When anything other than file descriptor is passed

  • toml.dumps(o, encoder=None)
    Create a TOML-formatted string from an input object

    创建一个toml格式的字符串从一个输入对象

    • Args:
      o: An object to be converted into TOML
    • encoder: An instance of TomlEncoder (or subclass) for encoding the object. If None, will default to TomlEncoder
    • Returns:
      A string containing the TOML-formatted data corresponding to object o

七. 完整规范

# python # config
<女士品茶>与TF-IDF算法 上一篇
MySQL Shell for VS Code简单使用 下一篇
已运行:
浏览数: 次 | 访客数: 人
Powered by Kyouichirou