tag	613e32421bf3d6c7a324e2ede3c4fdfdbaebfeb7
tagger	Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>	Fri Jun 18 18:59:31 2021 +0300
object	33ae2ba864a0369c5c1baecf6be90af72f9ab93d

commit	33ae2ba864a0369c5c1baecf6be90af72f9ab93d	[log] [tgz]
author	Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>	Fri Jun 18 18:59:28 2021 +0300
committer	Taneli Hukkinen <3275109+hukkin@users.noreply.github.com>	Fri Jun 18 18:59:28 2021 +0300
tree	b58442299a671feb1606701328da18e50e380ac9
parent	68d4a37872649a741020faf97e15e5dd469fc4ae [diff]

tree: b58442299a671feb1606701328da18e50e380ac9

README.md

Tomli

A lil' TOML parser

Table of Contents generated with mdformat-toc

Intro
Installation
Usage
FAQ
Performance

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

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 *: 13x as fast as tomlkit, 2x 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 function.

Is there a `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.

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.1,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='1621207351'
benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'
2021-06-15
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.903 s | baseline (100%)
  pytomlpp |      1.1 s | 82.26%
     tomli |     4.35 s | 20.78%
      toml |      8.9 s | 10.15%
     qtoml |       11 s | 8.23%
   tomlkit |     58.8 s | 1.54%

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