toml-rs 0.2.1

A High-Performance TOML Parser for Python written in Rust

toml-rs

A High-Performance TOML v1.0.0 and v1.1.0 parser for Python written in Rust

Features

• The fastest TOML parser in Python (see benchmarks)

• Drop-in compatibility with most tomllib use cases (see below)

Installation

# Using pip
pip install toml-rs

# Using uv
uv pip install toml-rs

Examples

import tomllib
from pprint import pprint

import toml_rs

toml = """\
title = "TOML Example"

[owner]
name = "Tom Preston-Werner"
dob = 1979-05-27T07:32:00-08:00

[database]
enabled = true
ports = [ 8000, 8001, 8002 ]
data = [ ["delta", "phi"], [3.14] ]
temp_targets = { cpu = 79.5, case = 72.0 }

[servers]
[servers.alpha]
ip = "10.0.0.1"
role = "frontend"
[servers.beta]
ip = "10.0.0.2"
role = "backend"
"""

tomllib_loads = tomllib.loads(toml)
toml_rs_loads = toml_rs.loads(toml)
toml_rs_dumps = toml_rs.dumps(toml_rs_loads)

assert tomllib_loads == toml_rs_loads

print("toml_rs.loads:")
pprint(toml_rs_loads)
print("toml_rs.dumps:")
print(toml_rs_dumps)

Differences with tomllib

1. More understandable errors

import tomllib

t = """\
x = 1
y = 2
v = 
"""
print(tomllib.loads(t))
# tomllib.TOMLDecodeError: Invalid value (at line 3, column 5)

import toml_rs

t = """\
x = 1
y = 2
v = 
"""
print(toml_rs.loads(t))
# toml_rs.TOMLDecodeError: TOML parse error at line 3, column 5
#   |
# 3 | v = 
#   |     ^
# string values must be quoted, expected literal string

2. Strict compliance with TOML v1.0.0

From TOML v1.0.0 spec:

Arbitrary 64-bit signed integers (from −2^63 to 2^63−1) should be accepted and handled losslessly. If an integer cannot be represented losslessly, an error must be thrown.

import tomllib

t = "x = 999_999_999_999_999_999_999_999"
print(tomllib.loads(t))
# {'x': 999999999999999999999999} <== speс violation

import toml_rs

t = "x = 999_999_999_999_999_999_999_999"
print(toml_rs.loads(t))
# toml_rs.TOMLDecodeError: TOML parse error at line 1, column 5
#   |
# 1 | x = 999_999_999_999_999_999_999_999
#   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
# invalid type: integer `999999999999999999999999` as i128, expected any valid TOML value

Note: TOML v1.1.0 allows parsers to support integers and floats beyond i64/f64 limits, so the behavior will be the same as tomllib

3. Supports serialization (toml_rs.dumps and toml_rs.dump)

from pathlib import Path

import toml_rs

data = {
    "title": "TOML Example",
    "owner": {"name": "Alice", "age": 30},
}

print(toml_rs.dumps(data))

toml_rs.dump(data, Path("example.toml"))  
# or `toml_rs.dump(data, "example.toml")`