leptris (Python) — lxml-shaped bindings for libleptris

leptris wraps the libleptris C API (XML 1.0 parsing, XPath 1.0) using cffi in ABI mode, with a required C accelerator for Element allocation and the hot accessors (tag, text, attrib, get, indexing, sibling navigation and plain-path XPath evaluation). Wheels ship it compiled; sdist builds require a C compiler.

The pinned libleptris version lives in libleptris-version.txt (lockstep releases); CI builds it from the release tarball. The binding loads the shared library from LEPTRIS_LIB_PATH or the loader path.

Requirements

Python 3.9+
cffi (installed automatically)
libleptris 1.9.3+ as a shared library (1.9.1 has an options-struct ABI break — leptris/leptris#568)
libleptris as a shared library (libleptris.dylib / .so / .dll) on the loader path, or pointed to by LEPTRIS_LIB_PATH (which must name the library file — the loader dlopens it verbatim). For a development checkout:

cmake -B build -S /path/to/leptris -DLEPTRIS_BUILD_SHARED=ON
cmake --build build --target leptris_shared
export LEPTRIS_LIB_PATH=/path/to/leptris/build/src/libleptris.dylib

Quick start

from leptris import fromstring, tostring

root = fromstring("<library><book id='1' lang='en'>Ulysses</book></library>")

root.tag                                # "library"
root[0].get("id")                       # "1"
root[0].attrib                          # {"id": "1", "lang": "en"}
root[0].text                            # "Ulysses"

root.xpath("count(//book)")             # 1.0
[b.text for b in root.findall("book")]  # ["Ulysses"]

tostring(root[0], encoding="unicode")   # "<book id=\"1\" lang=\"en\">Ulysses</book>"

Documents own the tree; use the context manager or close():

from leptris import parse

with parse("catalog.xml") as doc:
    doc.xpath("//book[@lang='en']")

Namespaces, variables, canonical XML and streaming:

root.xpath("//x:item", namespaces={"x": "urn:ex"})
root.xpath("//book[@id=$id]", variables={"id": "2"})
c14n(root, exclusive=True)

from leptris import sax
sax.parse(xml, handler)                       # one-shot
with sax.StreamingParser(handler) as parser:  # push, constant memory
    parser.feed(chunk, final=last)

Migrating from lxml

lxml	leptris	Notes
`etree.fromstring` / `etree.XML`	`fromstring` / `XML`
`etree.parse`	`parse`	paths and file-likes; no URLs
`etree.tostring(elem, …)`	`tostring(elem, …)`	bytes by default, `encoding="unicode"` for str
`elem.tag` / `.text` / `.tail`	same	`tag` uses `{uri}local` Clark notation; CDATA merges into text (lxml's default parser behavior)
`elem.attrib` / `.get()` / `.keys()` / `.items()`	same	`attrib` is a read-only Mapping
`elem.getparent/getnext/getprevious`	same
`elem[i]`, `len(elem)`, iteration, slices	same	indexing is child indexing, never attribute lookup
`elem.iter()` / `.iterdescendants()` / `.itertext()`	same	elements only (ElementTree semantics); lxml's `iter()` also yields comments/PIs
`elem.find/findall/findtext`	same	accepts full XPath 1.0 — a superset of ElementPath — including `{uri}local` names
`elem.xpath(expr, namespaces=…)`	same	plus `variables={…}` (leptris extension)
`etree.c14n` / `etree.XInclude`	`c14n(…)` / `doc.process_xinclude()`
`etree.XMLSyntaxError`	`ParseError`	XPath failures raise `XPathError`; both subclass `LeptrisError`
`etree.Element`, `SubElement`, `append`, `set`, `remove`	not exposed	libleptris has partial mutation upstream (node content setters, `set_root`, `remove_children`) — not surfaced here; build trees elsewhere
document-level comments / PIs	`doc.toplevel_comments()` / `doc.toplevel_pis()`	prolog then epilog; requires libleptris 1.9.3+
`etree.iterparse`	`leptris.iterparse(source, full_document=False)`	bounded by the largest subtree; yields `("end", element)`; elements borrowed until the next yield; tags resolve namespaces (Clark notation, libleptris 1.9.4+). Truncated or malformed input raises ParseError (libleptris 1.9.4 error channel). `full_document=True` yields every element in completion order — error detection is unreliable in that mode pending leptris/leptris#592. Still ~2× slower than lxml's iterparse (leptris/leptris#563)
smart strings	plain `str`	XPath string/attribute results
`elem.nsmap`	absent	use `elem.namespace` / `elem.prefix` and `xpath(namespaces=…)`
`etree.XPath` compiled objects	`leptris.XPath(expression)`	compile once, evaluate many; contexts, namespaces, and variables supported
`etree.XSLT`	`leptris.XSLT(stylesheet)`	compile once, apply to any Document; full XSLT 1.0 + EXSLT (math/set/str/date) via libleptris
parser options (`resolve_entities`, …)	absent	libleptris 1.2.0 has no per-parse options
`elem.sourceline`	same	requires libleptris 1.3.0+
undeclared XPath prefix	raises in lxml	evaluates to an empty nodeset here
ATTLIST default attributes	applied by lxml's default parser	excluded by default (ElementTree-like; XML 1.0 §5 permits either) — `Document.parse(xml, attribute_defaults=True)` opts in
parser options (`remove_blank_text`, …)	`etree.XMLParser(remove_blank_text=True)`	`Document.parse(xml, remove_blank_text=True)` — ~35% faster on pretty-printed input; also `attribute_defaults=True`, `recover=True`

Layout

leptris/_ffi.py — cdef mirror of the public headers + loader (the only place libleptris is declared)
leptris/_leptrisaccel.c — the C accelerator (abi3): allocates Elements and runs the hot accessors, subtree iteration, the parse and serialization seams, and the per-document element registry; bound to libleptris by the positional protocol in element.py
leptris/element.py, document.py, node.py, xpath.py — the Python surface: queries, walks, documents; node.py exposes the full DOM (comments, CDATA, PIs) beneath the ElementTree shape
leptris/api.py — fromstring/parse/tostring/c14n/ iterparse
leptris/sax.py — SAX one-shot and streaming
tests/ — pytest suite (pytest with LEPTRIS_LIB_PATH set)
benchmarks/ — matrix vs lxml/ElementTree/minidom (pip install .[bench], then python -m benchmarks.matrix)

Memory model

The Document owns the whole tree and its pool. Accessor strings are copied into Python str at the boundary, so nothing depends on document lifetime after a call returns. Elements keep a reference to their Document, so the pool cannot be freed while any wrapper is alive. Prefer explicit close() / the context manager; __del__ is a refcounting safety net, not a contract. Using an element after its document is closed raises LeptrisError.

Versioning

libleptris-version.txt pins the library release the binding is built and tested against. From 1.3.0 the package follows its own semver: 1.2.0 shipped an interim bespoke API to no adopters, and 1.3.0 replaces it with the lxml-shaped API (breaking, but pre-adoption). pyproject.toml and leptris/__init__.py must agree at release time.

Publishing

Releases publish to PyPI via .github/workflows/release.yml, using PyPI trusted publishing (no stored credentials). The workflow runs on manual dispatch (ships the version in pyproject.toml) and is called by the libleptris release flow (publish: true), so every libleptris release ships the wheel.

Local development

python3 -m venv .venv
./.venv/bin/pip install --upgrade build pytest cffi
./.venv/bin/pip install -e .[test,bench]
LEPTRIS_LIB_PATH=/path/to/libleptris.dylib ./.venv/bin/python -m pytest tests/ -q

Download files

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

Source Distribution

leptris-1.22.1.tar.gz (51.2 kB view details)

Uploaded Aug 28, 2026 Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

leptris-1.22.1-cp39-abi3-win_amd64.whl (44.8 kB view details)

Uploaded Aug 28, 2026 CPython 3.9+Windows x86-64

leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (100.5 kB view details)

Uploaded Aug 28, 2026 CPython 3.9+manylinux: glibc 2.17+ ARM64

leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (96.6 kB view details)

Uploaded Aug 28, 2026 CPython 3.9+manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl (43.2 kB view details)

Uploaded Aug 28, 2026 CPython 3.9+macOS 11.0+ ARM64

leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl (42.7 kB view details)

Uploaded Aug 28, 2026 CPython 3.9+macOS 10.9+ x86-64

File details

Details for the file leptris-1.22.1.tar.gz.

File metadata

Download URL: leptris-1.22.1.tar.gz
Upload date: Aug 28, 2026
Size: 51.2 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1.tar.gz
Algorithm	Hash digest
SHA256	`4572cc14b0b092749d1078eba2a32845af53310e7cad9ca7d98156a5919dbff3`
MD5	`7502e37e56afda7441da6ddd50dc9efa`
BLAKE2b-256	`b7f40aacfe9f648ed14520e1fb80630050adff62a536d723d2060d2fd2274262`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1.tar.gz:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1.tar.gz
- Subject digest: 4572cc14b0b092749d1078eba2a32845af53310e7cad9ca7d98156a5919dbff3
- Sigstore transparency entry: 2626668218
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch

File details

Details for the file leptris-1.22.1-cp39-abi3-win_amd64.whl.

File metadata

Download URL: leptris-1.22.1-cp39-abi3-win_amd64.whl
Upload date: Aug 28, 2026
Size: 44.8 kB
Tags: CPython 3.9+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1-cp39-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`7bac83ae9c232c8b5678510953aae465f3264ebb785eb4d26dac633213a1282a`
MD5	`deb691e49864afd7f822c5b5531d5abd`
BLAKE2b-256	`b7480f529128fa4823883ac13c5c380a16369ff8c574b81c387c2770c6d6940e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1-cp39-abi3-win_amd64.whl:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1-cp39-abi3-win_amd64.whl
- Subject digest: 7bac83ae9c232c8b5678510953aae465f3264ebb785eb4d26dac633213a1282a
- Sigstore transparency entry: 2626668225
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch

File details

Details for the file leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

Download URL: leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Upload date: Aug 28, 2026
Size: 100.5 kB
Tags: CPython 3.9+, manylinux: glibc 2.17+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm	Hash digest
SHA256	`01759c850b6c90f73f511e952fb08264f783672698a9c7aa3491d6ae9774e232`
MD5	`b6b26f5e9380aea218d594460ce21e16`
BLAKE2b-256	`a1819548a60389ff9c76ea680c8adf99785654714844a4d7d917fdfb93d97685`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
- Subject digest: 01759c850b6c90f73f511e952fb08264f783672698a9c7aa3491d6ae9774e232
- Sigstore transparency entry: 2626668222
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch

File details

Details for the file leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

Download URL: leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Upload date: Aug 28, 2026
Size: 96.6 kB
Tags: CPython 3.9+, manylinux: glibc 2.17+ x86-64, manylinux: glibc 2.5+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm	Hash digest
SHA256	`edf6736526a16786326a9f6053b899580263601994c11f44385f63a8b02c7bc7`
MD5	`8b00ad05dfb89866a66c80fc05019802`
BLAKE2b-256	`dfe89c19b229b4e157af13ff2bf1d160277c3672732c6dce33b0493064ec63ec`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
- Subject digest: edf6736526a16786326a9f6053b899580263601994c11f44385f63a8b02c7bc7
- Sigstore transparency entry: 2626668231
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch

File details

Details for the file leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl
Upload date: Aug 28, 2026
Size: 43.2 kB
Tags: CPython 3.9+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`acc033e0c4e7c9fc7d516c7297541b0021bb9cff1ac96b5cecc994f8bf63b591`
MD5	`dffe1d8dfc8145b6c0c85f331bfb4223`
BLAKE2b-256	`98bf4b925342c0efaab59c12b011f3976031379a30a72ef28bf63e97b3c087de`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1-cp39-abi3-macosx_11_0_arm64.whl
- Subject digest: acc033e0c4e7c9fc7d516c7297541b0021bb9cff1ac96b5cecc994f8bf63b591
- Sigstore transparency entry: 2626668221
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch

File details

Details for the file leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl.

File metadata

Download URL: leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl
Upload date: Aug 28, 2026
Size: 42.7 kB
Tags: CPython 3.9+, macOS 10.9+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl
Algorithm	Hash digest
SHA256	`ee929e1fd5d34fc378e992d3ac77d00ea95d8c01ef467ff73f1c3428c3d7253c`
MD5	`0420612e4b779e8325fa50ff6da1a25e`
BLAKE2b-256	`d44761d98152777b24581ccf9178d1d72265501412517a051359058933b4bae3`

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl:

Publisher: release.yml on leptris/leptris-py

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: leptris-1.22.1-cp39-abi3-macosx_10_9_x86_64.whl
- Subject digest: ee929e1fd5d34fc378e992d3ac77d00ea95d8c01ef467ff73f1c3428c3d7253c
- Sigstore transparency entry: 2626668236
- Sigstore integration time: Aug 28, 2026
Source repository:
- Permalink: leptris/leptris-py@1772ad706e68351c9049a51c78fcc59a77ea7088
- Branch / Tag: refs/heads/main
- Owner: https://github.com/leptris
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@1772ad706e68351c9049a51c78fcc59a77ea7088
- Trigger Event: workflow_dispatch