tomli 1.0.2

A lil' TOML parser

Tomli

A lil' TOML parser

Table of Contents generated with mdformat-toc

• Intro
• Installation
• Usage
  • Parse a TOML string
  • Parse a TOML file
  • Handle invalid TOML
  • Construct decimal.Decimals from TOML floats
• FAQ
  • Why this parser?
  • Is comment preserving round-trip parsing supported?
  • Is there a dumps, write or encode function?
  • How do TOML types map into Python types?
• 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.Decimals 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).