Skip to main content

A lil' TOML parser

Project description

Build Status codecov.io PyPI version

Tomli

A lil' TOML parser

Table of Contents generated with mdformat-toc

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", "rb") as f:
    toml_dict = tomli.load(f)

Opening the file in binary mode (with the "rb" flag) is highly encouraged. Binary mode will enforce decoding the file as UTF-8 with universal newlines disabled, both of which are required to correctly parse TOML. Support for text file objects may be deprecated for removal in a future release.

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

Note that decimal.Decimal can be replaced with another callable that converts a TOML float from string to a Python type. The decimal.Decimal is, however, a practical choice for use cases where float inaccuracies can not be tolerated.

Illegal types include dict, list, and anything that has the append attribute. Parsing floats into an illegal type results in undefined behavior.

FAQ

Why this parser?

  • it's lil'
  • pure Python with zero dependencies
  • the fastest pure Python parser *: 14x as fast as tomlkit, 2.4x 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 and tomli.load functions.

Look into TOML Kit if preservation of style is what you need.

Is there a dumps, write or encode function?

Tomli-W is the write-only counterpart of Tomli, providing dump and dumps functions.

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 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.4,tomlkit==0.7.2
benchmark-pypi run-test-pre: PYTHONHASHSEED='2995948371'
benchmark-pypi run-test: commands[0] | python -c 'import datetime; print(datetime.date.today())'
2021-07-05
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.902 s | baseline (100%)
  pytomlpp |     1.09 s | 83.00%
     tomli |     3.82 s | 23.60%
      toml |     9.27 s | 9.73%
     qtoml |     11.5 s | 7.84%
   tomlkit |     55.1 s | 1.64%

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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

tomli-1.1.0.tar.gz (12.1 kB view details)

Uploaded Source

Built Distribution

tomli-1.1.0-py3-none-any.whl (11.7 kB view details)

Uploaded Python 3

File details

Details for the file tomli-1.1.0.tar.gz.

File metadata

  • Download URL: tomli-1.1.0.tar.gz
  • Upload date:
  • Size: 12.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.26.0

File hashes

Hashes for tomli-1.1.0.tar.gz
Algorithm Hash digest
SHA256 33d7984738f8bb699c9b0a816eb646a8178a69eaa792d258486776a5d21b8ca5
MD5 dfe77dbc5dcefa23e036d421d65bdc57
BLAKE2b-256 6c16f48ab3289015f8f90e2c68fb76531728b3d8e4ce5052ee80ad10e7707eda

See more details on using hashes here.

File details

Details for the file tomli-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: tomli-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 11.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: python-requests/2.26.0

File hashes

Hashes for tomli-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f4a182048010e89cbec0ae4686b21f550a7f2903f665e34a6de58ec15424f919
MD5 99a682b50cf83d59af6504a7153ec152
BLAKE2b-256 2eac75c79a6880ba6b306df9f61fedf802dd7db0c54d42e4a879f1428625c138

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page