Tomli
A lil' TOML parser
Table of Contents generated with mdformat-toc
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", encoding="utf-8") as f:
toml_dict = tomli.load(f)
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.Decimals from TOML floats
from decimal import Decimal
import tomli
toml_dict = tomli.loads("precision-matters = 0.982492", parse_float=Decimal)
assert isinstance(toml_dict["precision-matters"], Decimal)
Note that you may replace decimal.Decimal with any callable that converts a TOML float from string to any Python type (except list or dict). The decimal.Decimal type is, however, the most typical replacement when float inaccuracies can not be tolerated.
FAQ
Why this parser?
- it's lil'
- pure Python with zero dependencies
- the fastest pure Python parser *: 14x 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.0.4,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='2995948371'
benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'
2021-07-05
benchmark-pypi run-test: commands[1] | python --version
Python 3.8.5
benchmark-pypi run-test: commands[2] | python benchmark/run.py
Parsing data.toml 5000 times:
------------------------------------------------------
parser | exec time | performance (more is better)
-----------+------------+-----------------------------
rtoml | 0.902 s | baseline (100%)
pytomlpp | 1.09 s | 83.00%
tomli | 3.82 s | 23.60%
toml | 9.27 s | 9.73%
qtoml | 11.5 s | 7.84%
tomlkit | 55.1 s | 1.64%
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).
![[pre-commit.ci] pre-commit autoupdate](https://avatars.githubusercontent.com/in/68672?v=4)
1 Nov 14, 2021
10 Nov 21, 2022
1.5k Jan 9, 2023
6.2k Jan 8, 2023
402 Dec 20, 2022
70 Oct 4, 2022
245 Aug 14, 2022
230 Dec 18, 2022
29 Nov 30, 2022
104 Dec 1, 2022
72 Oct 14, 2022
6.1k Jan 3, 2023
40 Sep 25, 2021
1.3k Jan 1, 2023
13 May 24, 2021
56 Dec 22, 2022
1.7k Jan 6, 2023
756 Jan 6, 2023