commit	7a170e5dffa2f3f1c06278e70216dbc27103e2c7	[log] [tgz]
author	Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>	Fri Dec 10 21:56:15 2021 +0200
committer	GitHub <noreply@github.com>	Fri Dec 10 21:56:15 2021 +0200
tree	7f0186a49c1c72dd1b93e294e9698ac06a0b3249
parent	2d9b2dcabe501afce95feba236e108f5166c9fe9 [diff]
parent	e4f44e30bda20fc776532b3df8abf9f4f03257f0 [diff]

tree: 7f0186a49c1c72dd1b93e294e9698ac06a0b3249

README.md

Tomli

A lil' TOML parser

Table of Contents generated with mdformat-toc

Intro
Installation
Usage
FAQ
Performance

Intro

Tomli is a Python library for parsing TOML. Tomli is fully compatible with TOML v1.0.0.

Installation

pip install tomli

Usage

Parse a TOML string

import tomli

toml_str = """
           gretzky = 99

           [kurri]
           jari = 17
           """

toml_dict = tomli.loads(toml_str)
assert toml_dict == {"gretzky": 99, "kurri": {"jari": 17}}

Parse a TOML file

import tomli

with open("path_to_file/conf.toml", "rb") as f:
    toml_dict = tomli.load(f)

The file must be opened in binary mode (with the "rb" flag). Binary mode will enforce decoding the file as UTF-8 with universal newlines disabled, both of which are required to correctly parse TOML.

Handle invalid TOML

import tomli

try:
    toml_dict = tomli.loads("]] this is invalid TOML [[")
except tomli.TOMLDecodeError:
    print("Yep, definitely not valid.")

Note that while the TOMLDecodeError type is public API, error messages of raised instances of it are not. Error messages should not be assumed to stay constant across Tomli versions.

Construct `decimal.Decimal`s from TOML floats

from decimal import Decimal
import tomli

toml_dict = tomli.loads("precision-matters = 0.982492", parse_float=Decimal)
assert toml_dict["precision-matters"] == Decimal("0.982492")

Note that decimal.Decimal can be replaced with another callable that converts a TOML float from string to a Python type. The decimal.Decimal is, however, a practical choice for use cases where float inaccuracies can not be tolerated.

Illegal types include dict, list, and anything that has the append attribute. Parsing floats into an illegal type results in undefined behavior.

FAQ

Why this parser?

it‘s lil’
pure Python with zero dependencies
the fastest pure Python parser *: 15x as fast as tomlkit, 2.4x as fast as toml
outputs basic data types only
100% spec compliant: passes all tests in a test set soon to be merged to the official compliance tests for TOML repository
thoroughly tested: 100% branch coverage

Is comment preserving round-trip parsing supported?

No.

The tomli.loads function returns a plain dict that is populated with builtin types and types from the standard library only. Preserving comments requires a custom type to be returned so will not be supported, at least not by the tomli.loads and tomli.load functions.

Look into TOML Kit if preservation of style is what you need.

Is there a `dumps`, `write` or `encode` function?

Tomli-W is the write-only counterpart of Tomli, providing dump and dumps functions.

The core library does not include write capability, as most TOML use cases are read-only, and Tomli intends to be minimal.

How do TOML types map into Python types?

TOML type	Python type	Details
Document Root	`dict`
Key	`str`
String	`str`
Integer	`int`
Float	`float`
Boolean	`bool`
Offset Date-Time	`datetime.datetime`	`tzinfo` attribute set to an instance of `datetime.timezone`
Local Date-Time	`datetime.datetime`	`tzinfo` attribute set to `None`
Local Date	`datetime.date`
Local Time	`datetime.time`
Array	`list`
Table	`dict`
Inline Table	`dict`

Performance

The benchmark/ folder in this repository contains a performance benchmark for comparing the various Python TOML parsers. The benchmark can be run with tox -e benchmark-pypi. Running the benchmark on my personal computer output the following:

foo@bar:~/dev/tomli$ tox -e benchmark-pypi
benchmark-pypi installed: attrs==19.3.0,click==7.1.2,pytomlpp==1.0.2,qtoml==0.3.0,rtoml==0.7.0,toml==0.10.2,tomli==1.1.0,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='2658546909'
benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'
2021-07-23
benchmark-pypi run-test: commands[1] | python --version
Python 3.8.10
benchmark-pypi run-test: commands[2] | python benchmark/run.py
Parsing data.toml 5000 times:
------------------------------------------------------
    parser |  exec time | performance (more is better)
-----------+------------+-----------------------------
     rtoml |    0.901 s | baseline (100%)
  pytomlpp |     1.08 s | 83.15%
     tomli |     3.89 s | 23.15%
      toml |     9.36 s | 9.63%
     qtoml |     11.5 s | 7.82%
   tomlkit |     56.8 s | 1.59%

The parsers are ordered from fastest to slowest, using the fastest parser as baseline. Tomli performed the best out of all pure Python TOML parsers, losing only to pytomlpp (wraps C++) and rtoml (wraps Rust).