Package: tomli
TomliA lil' TOML parserTable of Contentsgenerated withmdformat-tocIntroInstallationUsageParse a TOML stringParse a TOML fileHandle invalid TOMLConstructdecimal.Decimals from TOML floatsFAQWhy this parser?Is comment preserving round-trip parsing supported?Is there adumps,writeorencodefunction?How do TOML types map into Python types?PerformanceIntroTomli is a Python library for parsingTOML.
Tomli is fully compatible withTOML v1.0.0.InstallationpipinstalltomliUsageParse a TOML stringimporttomlitoml_str="""gretzky = 99[kurri]jari = 17"""toml_dict=tomli.loads(toml_str)asserttoml_dict=={"gretzky":99,"kurri":{"jari":17}}Parse a TOML fileimporttomliwithopen("path_to_file/conf.toml","rb")asf: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 TOMLimporttomlitry:toml_dict=tomli.loads("]] this is invalid TOML [[")excepttomli.TOMLDecodeError:print("Yep, definitely not valid.")Note that error messages are considered informational only.
They should not be assumed to stay constant across Tomli versions.Constructdecimal.Decimals from TOML floatsfromdecimalimportDecimalimporttomlitoml_dict=tomli.loads("precision-matters = 0.982492",parse_float=Decimal)asserttoml_dict["precision-matters"]==Decimal("0.982492")Note thatdecimal.Decimalcan be replaced with another callable that converts a TOML float from string to a Python type.
Thedecimal.Decimalis, however, a practical choice for use cases where float inaccuracies can not be tolerated.Illegal types aredictandlist, and their subtypes.
AValueErrorwill be raised ifparse_floatproduces illegal types.FAQWhy this parser?it's lil'pure Python with zero dependenciesthe fastest pure Python parser*:
15x as fast astomlkit,
2.4x as fast astomloutputsbasic data typesonly100% spec compliant: passes all tests ina test setsoon to be merged to the officialcompliance tests for TOMLrepositorythoroughly tested: 100% branch coverageIs comment preserving round-trip parsing supported?No.Thetomli.loadsfunction returns a plaindictthat 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 thetomli.loadsandtomli.loadfunctions.Look intoTOML Kitif preservation of style is what you need.Is there adumps,writeorencodefunction?Tomli-Wis the write-only counterpart of Tomli, providingdumpanddumpsfunctions.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 typePython typeDetailsDocument RootdictKeystrStringstrIntegerintFloatfloatBooleanboolOffset Date-Timedatetime.datetimetzinfoattribute set to an instance ofdatetime.timezoneLocal Date-Timedatetime.datetimetzinfoattribute set toNoneLocal Datedatetime.dateLocal Timedatetime.timeArraylistTabledictInline TabledictPerformanceThebenchmark/folder in this repository contains a performance benchmark for comparing the various Python TOML parsers.
The benchmark can be run withtox -e benchmark-pypi.
Running the benchmark on my personal computer output the following:foo@bar:~/dev/tomli$tox-ebenchmark-pypibenchmark-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.2benchmark-pypi run-test-pre: PYTHONHASHSEED='2658546909'benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'2021-07-23benchmark-pypi run-test: commands[1] | python --versionPython 3.8.10benchmark-pypi run-test: commands[2] | python benchmark/run.pyParsing 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).