commit	60274fac33919c549d61ef386633ad898fa5310a	[log] [tgz]
author	Taneli Hukkinen <hukkinj1@users.noreply.github.com>	Sat May 29 14:11:02 2021 +0300
committer	Taneli Hukkinen <hukkinj1@users.noreply.github.com>	Sat May 29 14:11:02 2021 +0300
tree	34c9b5e86336ed1d91158a6a16c65e852dca27c8
parent	79010a248561b41ae98018f648975765c5bf1e7a [diff]

tree: 34c9b5e86336ed1d91158a6a16c65e852dca27c8

README.md

Tomli

A lil' TOML parser

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.")

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 isinstance(toml_dict["precision-matters"], Decimal)

FAQ

Why this parser?

it‘s lil’
pure Python with zero dependencies
fairly fast (but pure Python so can't do any miracles there)
100% spec compliance: passes all tests in a test set soon to be merged to the official compliance tests for TOML repository
100% test 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 (list, int, str, datetime.datetime etc.). Preserving comments requires a custom type to be returned so will not be supported, at least not by the tomli.loads function.

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

Not yet, and it's possible there never will be.

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. On May 28 2021 running the benchmark output the following on my notebook computer.

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.0,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='305387179'
benchmark-pypi run-test: commands[0] | python benchmark/run.py
Parsing data.toml 5000 times:
------------------------------------------------------
    parser |  exec time | performance (more is better)
-----------+------------+-----------------------------
  pytomlpp |     1.16 s | baseline
     rtoml |     1.17 s | 1x baseline
     tomli |     8.94 s | 0.13x baseline
      toml |     9.33 s | 0.12x baseline
     qtoml |     15.7 s | 0.074x baseline
   tomlkit |       70 s | 0.017x baseline

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).