teptris-py — TOML for Python at libleptris speed
A native C-extension binding (no ctypes, no fallback) over
libteptris — the TOML counterpart
of leptris-py (XML) and yeptris-py (YAML). API shape mirrors
tomllib/tomli (loads/load raising TOMLDecodeError) plus a
dumps writer in the tomli_w spirit. Datetime mapping mirrors
tomllib: aware/naive datetime, date, time.
Both directions are native: dumps walks the object tree in C
through the builder API and emits via the shared engine emitter —
3.5×–14.2× faster than tomli_w on every benchmark shape. The engine
implements the TOML 1.1 draft grammar (a strict superset of 1.0)
with 100% toml-test conformance, and parses at ≥3× the best C/C++
competitor on every shape.
Performance (end-to-end, Python tier)
Best-of-12 runs on a GitHub ubuntu-latest runner (python 3.12),
2026-09-21, over the generated bench corpus (~700 KB per shape). The
full per-shape table regenerates on every main push via the
lang-tier lane.
| Shape | teptris | tomllib (stdlib) | tomlkit (pure) | rtoml (rust) |
|---|---|---|---|---|
| array_heavy | 6.8 ms / 107 MB/s | 236 ms / 3.1 MB/s | 1,740 ms / 0.4 MB/s | 34 ms / 21 MB/s |
| cargo_like | 3.8 ms / 94 MB/s | 100 ms / 3.5 MB/s | 1,074 ms / 0.3 MB/s | 18 ms / 20 MB/s |
| datetime_heavy | 26.1 ms / 41 MB/s | 227 ms / 4.8 MB/s | 1,680 ms / 0.6 MB/s | 40 ms / 27 MB/s |
| deep_tables | 2.2 ms / 109 MB/s | 82 ms / 3.0 MB/s | 14,713 ms / 0.0 MB/s | 13 ms / 18 MB/s |
| mixed | 5.5 ms / 80 MB/s | 150 ms / 2.9 MB/s | 1,385 ms / 0.3 MB/s | 27 ms / 16 MB/s |
| scalar_float | 12.7 ms / 115 MB/s | 310 ms / 4.7 MB/s | 2,243 ms / 0.7 MB/s | 61 ms / 24 MB/s |
| scalar_int | 11.8 ms / 108 MB/s | 300 ms / 4.3 MB/s | 2,038 ms / 0.6 MB/s | 54 ms / 24 MB/s |
End to end (parse + materialize into Python objects): 4.8-6x rtoml (the rust-backed incumbent), 19-42x the stdlib's tomllib, and hundreds of times tomlkit per shape. rtoml numbers include its own object construction; both libraries materialize fully.
Packaging
pip install teptris resolves one of 10 cp39-abi3 wheels —
manylinux/musllinux x86_64, aarch64 and armv7l (32-bit ARM, built
under qemu), macOS arm64 and x86_64, Windows AMD64 and ARM64 —
covering every CPython >= 3.9 including future minors. The extension statically links libteptris, so each
wheel is a single self-contained module (no shared-library chain).
Linux wheels build the engine inside each container via cibuildwheel
so musllinux links musl; the manylinux wheels carry the maximal tag
set (glibc >= 2.17).
Every wheel also carries the engine C SOURCE at teptris/_engine
(beside the compiled extension) — the recompile path for rebuilding
against your own environment. The sdist vendors the same tree and
compiles automatically at install.
Every other platform (FreeBSD, Solaris/illumos, any CPython on an exotic arch) installs the sdist, which vendors the engine and compiles it with the installing interpreter's compiler — a C compiler is required, and the build fails loudly without one.
Many-small batch (loads_batch)
Parse a list of TOML documents in ONE C call (teptris_parse_batch):
docs = teptris.loads_batch([toml_str_a, toml_str_b, toml_str_c])
# => [dict, dict, dict] — same datetime contract as loads()
The first failing document raises TOMLDecodeError carrying its
line/column. Honest perf shape (benchmark/batch_tier.py): per-doc
loads in a tight loop is faster on every measured shape (6.3x on
2000 tiny docs, 3.2x medium, 1.3x large — CPython's per-call overhead
amortizes better than the batch's scratch + object pressure). Use
loads_batch for the single API surface, one C crossing, and the
per-doc error report — not for speed.
Lazy load (loads_lazy)
When most of the parsed tree is going to be ignored, loads_lazy
returns a LazyNode wrapper that materializes host objects only along
the paths actually accessed:
doc = teptris.loads_lazy(big_toml)
# one parse, no dicts/lists materialized yet
sku = doc["items"][0]["sku"].value() # walks the path; scalars
# materialize at .value()
rest = doc["items"] # returns a LazyNode for the array
for it in rest:
print(it["sku"].value())
# flatten eagerly if you want the same dict-tree shape as loads()
flat = doc.to_dict()
LazyNode exposes kind() ('table' | 'array' | 'scalar'), value()
(scalars only — errors on containers), len() (containers), iteration
(tables yield (key, LazyNode) pairs; arrays yield LazyNodes),
[] (table key or array index — None for absent), and to_dict() /
to_list() for eager flattening. Datetime values materialize via the
same datetime.datetime / date / time contract as loads(). The
document and the borrowed-bytes input are kept alive by the wrapper
until GC.
Same datetime contract as loads(). The eager path is the floor for
"flatten everything" workloads; the lazy path is the win for "parse
once, touch a small subset."
Development
setup.py links the engine statically when it finds
libteptris.a/teptris.lib under TEPTRIS_LIBDIR (what the wheels
ship); otherwise it falls back to the shared library with an rpath to
its build tree. Point TEPTRIS_INCLUDE/TEPTRIS_LIBDIR at a C
checkout's build and run the suite:
cmake -B ../teptris/build -S ../teptris \
-DCMAKE_BUILD_TYPE=Release -DTEPTRIS_BUILD_SHARED=OFF -DTEPTRIS_BUILD_STATIC=ON
cmake --build ../teptris/build
TEPTRIS_INCLUDE=../teptris/src/include TEPTRIS_LIBDIR=../teptris/build/src \
python3 setup.py build_ext --inplace
PYTHONPATH=src python3 -m unittest discover -s tests -v
Publishing and version numbers are USER release decisions.
1 maintainer
Metadata
1 maintainer
Release files for teptris 0.2.22
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| teptris-0.2.22.tar.gz | 85.8 kB | Without provenance | Details |
Built distributions (wheels)
Total release size: 2.1 MB
Release files / teptris-0.2.22.tar.gz
| Download URL | teptris-0.2.22.tar.gz |
|---|---|
| Size | 85.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c822ff6253dcea0916488da6bfec07353bdc4005fcbcb2597a124a74d236b2df
|
|
BLAKE2b-256 checksum How to use checksums |
27912c469c4002193de16b163e76e2394324ed47ce6e8c220145ce2d702b822a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-win_arm64.whl
| Download URL | teptris-0.2.22-cp39-abi3-win_arm64.whl |
|---|---|
| Size | 136.2 kB |
| Tags | CPython 3.9 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
7588971f9db9a47ca62f0c30a700175c9ce465cd8189a03ef31c6120d3611f7a
|
|
BLAKE2b-256 checksum How to use checksums |
e1a39091c886485f79c4f6030e88647602438c7b7018f2b634a8b62dda9b97a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-win_amd64.whl
| Download URL | teptris-0.2.22-cp39-abi3-win_amd64.whl |
|---|---|
| Size | 138.1 kB |
| Tags | CPython 3.9 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
fd2d0bf9b0133f39826bc4b6c856f6a51e086701f94ce85e305530715e6c65f2
|
|
BLAKE2b-256 checksum How to use checksums |
fc610fa5fd25ba6ac19587cba89d0c5f86cfa502d620990b6af8e2ba0374ca40
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-musllinux_1_2_x86_64.whl
| Download URL | teptris-0.2.22-cp39-abi3-musllinux_1_2_x86_64.whl |
|---|---|
| Size | 180.0 kB |
| Tags | CPython 3.9 Linux musl 1.2+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
edfac3b772c1618102267d3f2be68ca98d15cf9f15366db07e16e70fc76f6140
|
|
BLAKE2b-256 checksum How to use checksums |
aa539bd6b1d3186d9d589cf35113456f56af80107ef2d584a9af4640edc3c8ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-musllinux_1_2_armv7l.whl
| Download URL | teptris-0.2.22-cp39-abi3-musllinux_1_2_armv7l.whl |
|---|---|
| Size | 182.1 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
cdef8456aae5e55c6f816573f5f2fbb5e1a9c05052289d5799c995b427935bbc
|
|
BLAKE2b-256 checksum How to use checksums |
59c57c1c3d47deda910446b8f52851d69b4d61745bf7cf1efea6ff371af4ca78
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-musllinux_1_2_aarch64.whl
| Download URL | teptris-0.2.22-cp39-abi3-musllinux_1_2_aarch64.whl |
|---|---|
| Size | 185.8 kB |
| Tags | CPython 3.9 Linux musl 1.2+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
3f25229d59ff3e622db42c86878a879278ad206b839102a2ddab4509f182d48c
|
|
BLAKE2b-256 checksum How to use checksums |
6d18f66a4c5fd4bfa2c77d78e97bb12cfe89d34b7de238a329ada96103bf0a73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl
| Download URL | teptris-0.2.22-cp39-abi3-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl |
|---|---|
| Size | 178.0 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ x86-64 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
8d7b6106d300faea8d2d6ea4ce41c0eff0356bf89beb6f278610edc21d38038e
|
|
BLAKE2b-256 checksum How to use checksums |
12127daf3e2ca6f8a9a298decd8a9671cefdd7171a69267b5c205adbe48b7cfb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl
| Download URL | teptris-0.2.22-cp39-abi3-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl |
|---|---|
| Size | 183.4 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ IBM System/390x Linux glibc 2.28+ IBM System/390x abi3 |
|
SHA-256 checksum How to use checksums |
2278d4f2f38ddd303ba385a73c711da1627ae54e91773b3fea5f5420759bbe84
|
|
BLAKE2b-256 checksum How to use checksums |
38c6e7cb309cceab69eb5dcebc49005cd78a765bdacabf1cb256c54df3f129c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl
| Download URL | teptris-0.2.22-cp39-abi3-manylinux2014_ppc64le.manylinux_2_17_ppc64le.manylinux_2_28_ppc64le.whl |
|---|---|
| Size | 190.4 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ PowerPC 64-le Linux glibc 2.28+ PowerPC 64-le abi3 |
|
SHA-256 checksum How to use checksums |
4044afad434c7060a580aa91ff95b5dd518cfa54b7e74d1ba1e74a9ceda5ba83
|
|
BLAKE2b-256 checksum How to use checksums |
7c7a19b797db15d5cff6b2298285877ae038d4ed102585ab2e3cc73bf27fe453
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl
| Download URL | teptris-0.2.22-cp39-abi3-manylinux2014_armv7l.manylinux_2_17_armv7l.manylinux_2_31_armv7l.whl |
|---|---|
| Size | 185.4 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARMv7l Linux glibc 2.31+ ARMv7l abi3 |
|
SHA-256 checksum How to use checksums |
5f8ae3d6ad5418bd91e671a97cd241893770e0a4e22940f978eda4c0f75896f0
|
|
BLAKE2b-256 checksum How to use checksums |
f17c6bc227380d6c850425fde22f9a670bd733d3f4f130197652b6da9e0b0c07
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl
| Download URL | teptris-0.2.22-cp39-abi3-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl |
|---|---|
| Size | 184.9 kB |
| Tags | CPython 3.9 Linux glibc 2.17+ ARM64 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
92394b327cfac9d408e108bdd2b3bfc2aebd7285c9f6524cf5395cc6bdcb9074
|
|
BLAKE2b-256 checksum How to use checksums |
47c574f6ba6732757fea7a3102d5190a73ab31d183e529da3d0973b82ca577c4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-macosx_11_0_arm64.whl
| Download URL | teptris-0.2.22-cp39-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 154.2 kB |
| Tags | CPython 3.9 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
91451a4d1a2bec45f58ebde267b5cd656a4ddac9486a6b8ab1a5970ed24a712c
|
|
BLAKE2b-256 checksum How to use checksums |
b658efff7f0c649a70627450d21676abd91f461713c3e8596cd83347905393cb
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Release files / teptris-0.2.22-cp39-abi3-macosx_10_9_x86_64.whl
| Download URL | teptris-0.2.22-cp39-abi3-macosx_10_9_x86_64.whl |
|---|---|
| Size | 153.8 kB |
| Tags | CPython 3.9 abi3 macOS 10.9+ x86-64 |
|
SHA-256 checksum How to use checksums |
332698cc202a93aee3b63d4ca5ebf87accac2ddff766d996b7c67002a421b5c0
|
|
BLAKE2b-256 checksum How to use checksums |
30ce3cf6b007de387034eea09c91eba2ec2ec7e39fb02ed735311f586c9140a3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.5
|
Security for teptris 0.2.22
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
