| commit | ea9dc4446900ee6cd2f402291dfb21c9e83fb31a | [log] [tgz] |
|---|---|---|
| author | Taneli Hukkinen <hukkinj1@users.noreply.github.com> | Tue Jun 01 08:53:41 2021 +0300 |
| committer | Taneli Hukkinen <hukkinj1@users.noreply.github.com> | Tue Jun 01 08:53:41 2021 +0300 |
| tree | cf51e7a5e477ebf67b9ee6a8ecb075d2a80f96db | |
| parent | bf6e5b939bfd8fc98013d989a125f0a235ea984e [diff] |
Improve README
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", encoding="utf-8") as f: toml_dict = tomli.load(f)
import tomli try: toml_dict = tomli.loads("]] this is invalid TOML [[") except tomli.TOMLDecodeError: print("Yep, definitely not valid.")
decimal.Decimals from TOML floatsfrom 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.
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 function.
dumps, write or encode function?Not yet, and it's possible there never will be.
This library is deliberately minimal, and most TOML use cases are read-only. Also, most use cases where writes are relevant could also benefit from comment and whitespace preserving reads, which this library does not currently support.
| TOML type | Python type |
|---|---|
| Document Root | dict |
| String | str |
| Integer | int |
| Float | float |
| Boolean | bool |
| Offset Date-Time | datetime.datetime |
| Local Date-Time | datetime.datetime |
| Local Date | datetime.date |
| Local Time | datetime.time |
| Array | list |
| 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. On June 1 2021 running the benchmark output the following on my notebook computer.
foo@bar:~/dev/tomli$ python --version Python 3.8.0 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.6.1,toml==0.10.2,tomli==0.2.6,tomlkit==0.7.2 benchmark-pypi run-test-pre: PYTHONHASHSEED='3747534643' benchmark-pypi run-test: commands[0] | python benchmark/run.py Parsing data.toml 5000 times: ------------------------------------------------------ parser | exec time | performance (more is better) -----------+------------+----------------------------- pytomlpp | 1.14 s | baseline (100%) rtoml | 1.16 s | 98.05% tomli | 6.72 s | 16.93% toml | 9.32 s | 12.19% qtoml | 15.3 s | 7.41% tomlkit | 67.2 s | 1.69%
The parsers are ordered from fastest to slowest, using the fastest parser (pytomlpp) as baseline. Tomli performed the best out of all pure Python TOML parsers, losing only to pytomlpp (wraps C++) and rtoml (wraps Rust).