Skip to main content

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)

XSLT and XPath version support

leptris.XSLT(stylesheet) compiles once, applies to any Document, and returns a Document; leptris.XPath(expression) compiles an XPath for repeated evaluation. Which language constructs work is decided by the engine — the matrix below is measured against libleptris 1.9.32 (audited through this binding; the upstream gap ledger is leptris/leptris#685).

language status notes
XSLT 1.0 full libxslt conformance suite 205/205 upstream; EXSLT math/set/str/date included
XSLT 2.0 partial for-each-group, analyze-string + regex-group(), xsl:number formats, xsl:assert, xsl:sequence (multi-item), xsl:perform-sort · ✗ xsl:function, tunnel parameters, shadow attributes, xsl:result-document, @separator
XSLT 3.0 increments try/catch (with $err:description), accumulator (gated by xsl:mode use-accumulators), iterate + break, on-empty, evaluate, grouping, modes, where-populated, on-non-empty, next-match, fork, @start-at, composite keys, tunnel params (call-template) · ✗ merge, result-document, package, on-completion, xsl:map
XPath 1.0 full complete core function library
XPath 2.0 partial ✓ composition grammar: for, if/then/else, to ranges · ✓ function slices 1.9.35+: date constructors/accessors (xs:date, year-from-dateTime), sequences (exists/empty/avg/min/max/distinct-values/head/remove/…), regex trio (matches/replace/tokenize — string args; node args pending), math:*, abs, format-integer, codepoints, URI escapes, node-name · ✗ quantified (some/every), except/intersect, instance of, cast/castable, value comparisons (eq…), node order (is, <<); dates/times, JSON, map:/array:, higher-order functions
XPath 3.1 lane 0 let, simple map !, arrow =>, string concat || — through both XPath() and XSLT · ✗ function items, inline functions, maps, arrays, string constructors
XQuery not available not implemented by the engine in any version — capability request: leptris/leptris#684

XPath 3.1 composition and XSLT 3.0 instructions flow through the existing API with zero binding change:

from leptris import Document, XPath, XSLT, tostring

with Document.parse("<r><item v='1'>alpha</item><item v='5'>beta</item></r>") as doc:
    doc.getroot().xpath("let $n := //item[2] return $n/@v")      # ['5']
    doc.getroot().xpath("(//item ! string(.)) => count()")        # 2.0

    style = XSLT("""<xsl:stylesheet version="3.0"
        xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
      <xsl:mode use-accumulators="depth"/>
      <xsl:accumulator name="depth" initial-value="0">
        <xsl:accumulator-rule match="*" phase="start" select="$value + 1"/>
        <xsl:accumulator-rule match="*" phase="end" select="$value - 1"/>
      </xsl:accumulator>
      <xsl:template match="/"><o>
        <xsl:iterate select="//item">
          <i d="{accumulator-before('depth')}"/>
        </xsl:iterate>
      </o></xsl:template>
    </xsl:stylesheet>""")
    print(tostring(style(doc), encoding="unicode"))
    # <o><i d="2"/><i d="2"/></o>   # items sit at depth 2 (r → item)

Unsupported constructs fail at XSLT() compile time or at evaluation with LeptrisError — except a known family of instructions that still produce empty output instead of an error (merge, result-document, on-completion, xsl:map, xsl:namespace, xsl:document, xsl:copy/@select, @separator/@default attributes); tracked in the #685/#690 ledgers above.

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 (both modes, libleptris 1.9.15+). full_document=True yields every element in completion order
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 — see the version support matrix above
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
declared non-UTF-8 bytes (UTF-16, latin-1, …) auto-detected auto-detected — declared encodings route through the converter, others retry on failure (libleptris 1.9.15+)
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.pyfromstring/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.25.1.tar.gz (62.1 kB view details)

Uploaded Source

Built Distributions

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

leptris-1.25.1-cp39-abi3-win_amd64.whl (46.9 kB view details)

Uploaded CPython 3.9+Windows x86-64

leptris-1.25.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (103.2 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ ARM64

leptris-1.25.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (99.1 kB view details)

Uploaded CPython 3.9+manylinux: glibc 2.17+ x86-64manylinux: glibc 2.5+ x86-64

leptris-1.25.1-cp39-abi3-macosx_11_0_arm64.whl (45.3 kB view details)

Uploaded CPython 3.9+macOS 11.0+ ARM64

leptris-1.25.1-cp39-abi3-macosx_10_9_x86_64.whl (44.7 kB view details)

Uploaded CPython 3.9+macOS 10.9+ x86-64

File details

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

File metadata

  • Download URL: leptris-1.25.1.tar.gz
  • Upload date:
  • Size: 62.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for leptris-1.25.1.tar.gz
Algorithm Hash digest
SHA256 946ea9d876a870d0bbe474563454d9ca8223cc33ccb667a7b35500eccd8253dc
MD5 bcce4e554119fa587eb126a97687cf0b
BLAKE2b-256 8b3cc436c44db52cb53d3bc8ba763c34fd870e8ddc572194b051cfcd0e1b5d31

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

File details

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

File metadata

  • Download URL: leptris-1.25.1-cp39-abi3-win_amd64.whl
  • Upload date:
  • Size: 46.9 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.25.1-cp39-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 4dc0e7bb8a31357092af43041448dcb8ae57650baf8ed98c84bf054b9a7abdc9
MD5 c60c22023e5d5871efd46ec969d7f10a
BLAKE2b-256 fe8faa4cb885655d743130717f1ba5debb34759d3bed10bb5b14fd90d6a7d082

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

File details

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

File metadata

File hashes

Hashes for leptris-1.25.1-cp39-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 25dfedaadff970d8045081b995b1bcd191b1db87ed65938f56f0c0058df20d6a
MD5 76b66bcec68f6bfe1065db5a5c040af3
BLAKE2b-256 d9808ca3380f614bb9b0abbaf64a82db849e59364cb245eae81b1a9318cb56ba

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

File details

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

File metadata

File hashes

Hashes for leptris-1.25.1-cp39-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 11860596cac88c783b663d2a99bd8b361143c409ded517f661751c4d0c195ee4
MD5 cf5cecc4b37506b09e6b30c2e763c08d
BLAKE2b-256 c52fc3b7a7a3bb41a02282a4812f3b236588bbcea526a5fea5fcbdadc197ea84

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

File details

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

File metadata

File hashes

Hashes for leptris-1.25.1-cp39-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 561eb946f4bd425de1d614ab3ae4c2bba32be295532949eef3fc8f391e3de6ea
MD5 86f13a6da3a125d79815eb10c35a296c
BLAKE2b-256 cb4ed2d57d252749497a27a04f67115aa03dea9df2b43a04f0b1483513b0f429

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

File details

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

File metadata

File hashes

Hashes for leptris-1.25.1-cp39-abi3-macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 c9012f7e79151aaef0596eeee343e3e2db8150e4f7c50c4383444157325f1b9d
MD5 30504d72da1ca4537e1dff253a24ef61
BLAKE2b-256 5a3390a74da05592d0eb38151d1179ac2abc038b7303f0b72eb50bede8b516e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for leptris-1.25.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.

Release history Release notifications | RSS feed

1.27.1

6 files

1.27.0

6 files

1.26.1

6 files

1.26.0

6 files

1.25.4

6 files

1.25.3

6 files

1.25.2

6 files

This release

1.25.1 This release

6 files

1.25.0

6 files

1.24.3

6 files

1.24.2

6 files

1.24.1

6 files

1.24.0

6 files

1.23.3

6 files

1.23.2

6 files

1.23.1

6 files

1.23.0

6 files

1.22.2

6 files

1.22.1

6 files

1.22.0

6 files

1.21.0

6 files

1.20.0

6 files

1.19.0

6 files

1.18.0

6 files

1.17.1

6 files

1.17.0

6 files

1.16.1

6 files

1.16.0

6 files

1.15.1

6 files

1.15.0

6 files

1.14.3

6 files

1.14.2

6 files

1.14.1

6 files

1.14.0

6 files

1.13.3

6 files

1.13.2

6 files

1.13.1

6 files

1.13.0

6 files

1.12.0

6 files

1.11.1

6 files

1.11.0

6 files

1.10.0

6 files

1.9.93.2

6 files

1.9.93.0

6 files

1.9.90.0

6 files

1.9.87.0

6 files

1.9.86.0

6 files

1.9.84.0

6 files

1.9.83.0

6 files

1.9.80.0

6 files

1.9.79.0

6 files

1.9.76.0

6 files

1.9.0

6 files

1.8.0

6 files

1.7.0

6 files

1.6.1

6 files

1.6.0

5 files

1.5.0

2 files

1.4.1

2 files

1.4.0

2 files

1.3.1

2 files

1.3.0

2 files

1.2.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page