commit | 92b84ec000413fff2185aec05565203a10c16d2f | [log] [tgz] |
---|---|---|
author | pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com> | Mon Oct 11 17:00:51 2021 +0000 |
committer | Taneli Hukkinen <3275109+hukkin@users.noreply.github.com> | Mon Oct 11 19:23:07 2021 +0200 |
tree | 3c59221dbf815116410a47b93f2f091d9c4f6b71 | |
parent | 8a8337e9fa6be4539fec835329022e134cd10fce [diff] |
[pre-commit.ci] pre-commit autoupdate updates: - [github.com/executablebooks/mdformat: b9b885e183ca16670b6d4a5ef8058664395dec58 → 427df9181bd4d8e65c1108b912ad47a81628f03b](https://github.com/executablebooks/mdformat/compare/b9b885e183ca16670b6d4a5ef8058664395dec58...427df9181bd4d8e65c1108b912ad47a81628f03b) - [github.com/PyCQA/isort: 6e4281f018ff848226d8993596765b2285e1624f → fd5ba70665a37ec301a1f714ed09336048b3be63](https://github.com/PyCQA/isort/compare/6e4281f018ff848226d8993596765b2285e1624f...fd5ba70665a37ec301a1f714ed09336048b3be63) - [github.com/psf/black: e3000ace2fd1fcb1c181bb7a8285f1f976bcbdc7 → 911470a610e47d9da5ea938b0887c3df62819b85](https://github.com/psf/black/compare/e3000ace2fd1fcb1c181bb7a8285f1f976bcbdc7...911470a610e47d9da5ea938b0887c3df62819b85) - [github.com/PyCQA/flake8: dcd740bc0ebaf2b3d43e59a0060d157c97de13f3 → cbeb4c9c4137cff1568659fcc48e8b85cddd0c8d](https://github.com/PyCQA/flake8/compare/dcd740bc0ebaf2b3d43e59a0060d157c97de13f3...cbeb4c9c4137cff1568659fcc48e8b85cddd0c8d) - [github.com/pre-commit/mirrors-mypy: 44afb68a9695d04030edc5cdc5a4fc4f17e4f9e2 → 5cf22ccb774a8be8f47dfe4c1e8c4f177c608cbf](https://github.com/pre-commit/mirrors-mypy/compare/44afb68a9695d04030edc5cdc5a4fc4f17e4f9e2...5cf22ccb774a8be8f47dfe4c1e8c4f177c608cbf)
A lil' TOML parser
Table of Contents generated with mdformat-toc
Tomli is a Python library for parsing TOML. Tomli is fully compatible with TOML v1.0.0.
pip install tomli
import tomli toml_str = """ gretzky = 99 [kurri] jari = 17 """ toml_dict = tomli.loads(toml_str) assert toml_dict == {"gretzky": 99, "kurri": {"jari": 17}}
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. Support for text file objects is deprecated for removal in the next major release.
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.
decimal.Decimal
s from TOML floatsfrom 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.
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.
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.
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 |
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).