pyuppsala

Python bindings for the Uppsala XML library -- a zero-dependency, pure-Rust implementation of XML 1.0, Namespaces, XPath 1.0, and XSD validation.

pyuppsala gives you a fast, correct, and memory-safe XML toolkit from Python with no C dependencies to compile and no transitive native libraries to audit.

This release is against 0.9 of Uppsala library.

Features

XML 1.0 parsing with full well-formedness checking
Namespace-aware DOM with tree mutation (create, append, insert, remove, detach)
XPath 1.0 evaluation (all axes, functions, predicates)
XSD validation (structures + datatypes, 40+ built-in types, facets, complex types)
XSD regex pattern matching (Unicode categories, blocks, character class subtraction)
XSLT 1.0 transforms with bounded template recursion
Imperative XML builder (XmlWriter) for constructing output without a DOM
Serialization with pretty-printing, compact output, and streaming to files
Automatic encoding detection for UTF-8 and UTF-16 (LE/BE)
lxml.etree-compatible API via pyuppsala.etree, a near drop-in for much of lxml.etree backed by Uppsala's secure parser
Native batch and fast etree paths for parsing many documents and running simple large-tree aggregates without one Python object per matched node

Read the full documentation

Security defaults

pyuppsala keeps the main XML attack classes bounded by default:

Parser resource caps are enabled by default for element depth, entity expansion size, and entity-reference nesting.
DTDs and entity declarations are accepted by default for compatibility, but entity expansion is capped. Use forbid_dtd=True or forbid_entities=True when parsing untrusted XML that should not contain DTDs or entity declarations.
XPath evaluation is capped by expression depth and by a per-evaluation node visit budget. Do not let untrusted callers choose max_depth or max_node_visits.
XSD regex matching has group-depth and backtracking-step limits. Do not let untrusted callers raise max_steps.
XSLT template recursion is capped by default. Treat stylesheets as trusted application configuration; EXSLT compatibility is enabled by default.
Document mutators reject Node handles from another document. Use Document.import_subtree() for intentional cross-document copies.
pyuppsala.etree keeps parser caps on by default. huge_tree=True lifts those caps for lxml compatibility and should only be used with trusted XML.
XInclude processing is explicit. Remote includes require network_access=True; local includes are restricted to the including document's base directory and are size-limited.
Native fetch helpers (available only in builds with the default-on net feature; gate use on pyuppsala._HAS_NET) cap response bodies at 128 MiB by default, including file:// reads, and keep TLS verification enabled by default. Apply your own URL allowlist before fetching attacker-controlled URLs.

See the resource limits and hardening guide and the API security notes for all knobs and default values.

Installation

python3 -m pip install pyuppsala

Or with uv:

uv add pyuppsala

Wheels are compiled from Rust via maturin. Python 3.10+ is required.

Quick start

Parse and query

from pyuppsala import Document, XPathEvaluator

doc = Document("<bookstore><book><title>Moby Dick</title></book></bookstore>")
doc.prepare_xpath()

xpath = XPathEvaluator()
title = xpath.evaluate(doc, "string(//title)")
print(title)  # "Moby Dick"

Build XML

from pyuppsala import XmlWriter

w = XmlWriter()
w.write_declaration()
w.start_element("catalog", [("xmlns", "urn:example")])
w.start_element("item", [("id", "1")])
w.text("Widget")
w.end_element("item")
w.end_element("catalog")
print(w.to_string())

Validate against an XSD schema

from pyuppsala import XsdValidator

schema = """\
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
  <xs:element name="greeting" type="xs:string"/>
</xs:schema>
"""

validator = XsdValidator(schema)
print(validator.is_valid_str("<greeting>Hello!</greeting>"))  # True
print(validator.is_valid_str("<greeting><bad/></greeting>"))  # False

Mutate the DOM

from pyuppsala import Document

doc = Document("<root><a/></root>")
root = doc.document_element
b = doc.create_element("b")
doc.append_child(root, b)
print(doc.to_xml())  # <root><a/><b/></root>

XSD regex

from pyuppsala import XsdRegex

regex = XsdRegex(r"[0-9]{5}")
print(regex.is_match("12345"))  # True
print(regex.is_match("abcde"))  # False

lxml-compatible etree API

Code written for lxml.etree runs after swapping the import. Elements are live views over the underlying document, with stable identity and the familiar .text/.tail/.attrib model.

from pyuppsala import etree  # instead of: from lxml import etree

root = etree.fromstring("<catalog><book id='1'>Dune</book></catalog>")
print(root.find("book").text)        # Dune
print(root[0].get("id"))             # 1

cat = etree.Element("catalog")
book = etree.SubElement(cat, "book", {"id": "2"})
book.text = "Neuromancer"
print(etree.tostring(cat, encoding="unicode"))
# <catalog><book id="2">Neuromancer</book></catalog>

See the etree documentation for the supported and unsupported feature matrix.

API overview

Class / function	Purpose
`Document(xml)`	Parse XML string into a DOM
`Document.from_bytes(data)`	Parse XML bytes (auto-detects UTF-8/UTF-16)
`Document.empty()`	Create an empty document for building from scratch
`Node`	A handle to a node in the document tree
`QName`	A qualified XML name (local name + optional namespace + prefix)
`Attribute`	An XML attribute (name + value)
`XPathEvaluator`	Evaluate XPath 1.0 expressions
`XsdValidator(schema)`	Validate documents against an XSD schema
`XmlWriter`	Imperative XML builder (no DOM needed)
`XsdRegex(pattern)`	XSD regular expression pattern matcher
`Xslt(stylesheet_xml)`	Compile and apply XSLT 1.0 stylesheets
`parse(xml)`	Module-level shorthand for `Document(xml)`
`parse_bytes(data)`	Module-level shorthand for `Document.from_bytes(data)`
`parse_many(items)`	Parse many XML strings or byte strings in native worker threads
`fetch_many(urls)`	Fetch many HTTP(S) or file URLs with body limits and per-item results (requires `pyuppsala._HAS_NET`)
`fetch_and_parse_many(urls)`	Fetch many URLs and parse each response as XML (requires `pyuppsala._HAS_NET`)
`pyuppsala.etree`	lxml.etree-compatible API (`Element`, `SubElement`, `fromstring`, `tostring`, `find`/`findall`, `XPath`, `XMLSchema`, ...)
`etree.fromstring_many(items)`	Parse many documents into etree roots with per-item errors
`_Element.fast_*()`	Native count/existence/attribute/text-group scans for large etree subtrees

Exceptions

Exception	Raised when
`XmlParseError`	XML is syntactically malformed
`XmlWellFormednessError`	XML violates well-formedness constraints
`XmlNamespaceError`	Namespace prefix is undeclared or misused
`XPathError`	XPath expression is invalid
`XsdValidationError`	XSD schema itself is invalid

All exceptions inherit from Exception.

Type stubs

Type stubs (pyuppsala/__init__.pyi and pyuppsala/etree.pyi, marked with py.typed) ship with the package for full IDE auto-completion and type-checking with mypy/pyright.

Development

# Clone the repository
git clone https://github.com/kushaldas/pyuppsala.git
cd pyuppsala

# Set up the environment with uv
uv sync

# Build the native extension in development mode
uv run maturin develop

# Run the test suite
uv run pytest

# Build a release wheel
uv run maturin build --release

License

BSD-2-Clause

Download files

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

Source Distribution

pyuppsala-0.10.0.tar.gz (248.5 kB view details)

Uploaded Aug 1, 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.

pyuppsala-0.10.0-cp310-abi3-win_arm64.whl (1.8 MB view details)

Uploaded Aug 1, 2026 CPython 3.10+Windows ARM64

pyuppsala-0.10.0-cp310-abi3-win_amd64.whl (1.9 MB view details)

Uploaded Aug 1, 2026 CPython 3.10+Windows x86-64

pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl (1.9 MB view details)

Uploaded Aug 1, 2026 CPython 3.10+manylinux: glibc 2.28+ x86-64

pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Aug 1, 2026 CPython 3.10+macOS 11.0+ ARM64

File details

Details for the file pyuppsala-0.10.0.tar.gz.

File metadata

Download URL: pyuppsala-0.10.0.tar.gz
Upload date: Aug 1, 2026
Size: 248.5 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyuppsala-0.10.0.tar.gz
Algorithm	Hash digest
SHA256	`bcc0f4f1a78e200399c909bdc87ff13fbbec2899ecc57e83ad8950aa311b0e9c`
MD5	`7c9b93cbb8f81bcff65c4ba3ce164289`
BLAKE2b-256	`b991345516ca44b3dade136dd569ab2d540423508f7a0164d339e1e01fcfba32`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyuppsala-0.10.0.tar.gz:

Publisher: release.yml on kushaldas/pyuppsala

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: pyuppsala-0.10.0.tar.gz
- Subject digest: bcc0f4f1a78e200399c909bdc87ff13fbbec2899ecc57e83ad8950aa311b0e9c
- Sigstore transparency entry: 2313048323
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: kushaldas/pyuppsala@5ccebd279582450c4b9b7100ebf578bbb4117438
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/kushaldas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5ccebd279582450c4b9b7100ebf578bbb4117438
- Trigger Event: push

File details

Details for the file pyuppsala-0.10.0-cp310-abi3-win_arm64.whl.

File metadata

Download URL: pyuppsala-0.10.0-cp310-abi3-win_arm64.whl
Upload date: Aug 1, 2026
Size: 1.8 MB
Tags: CPython 3.10+, Windows ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyuppsala-0.10.0-cp310-abi3-win_arm64.whl
Algorithm	Hash digest
SHA256	`08a62e362a2bd59b80e83b2af9eb0d4533d8713b07603e3bea64683e72d84bb4`
MD5	`095bc77bc05a861cefff2b9bb06b93d4`
BLAKE2b-256	`11c26acd3400332929d4343a0a3d0d8d68d9a76256e4c51b699f31ad2ca027ff`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyuppsala-0.10.0-cp310-abi3-win_arm64.whl:

Publisher: release.yml on kushaldas/pyuppsala

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: pyuppsala-0.10.0-cp310-abi3-win_arm64.whl
- Subject digest: 08a62e362a2bd59b80e83b2af9eb0d4533d8713b07603e3bea64683e72d84bb4
- Sigstore transparency entry: 2313048779
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: kushaldas/pyuppsala@5ccebd279582450c4b9b7100ebf578bbb4117438
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/kushaldas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5ccebd279582450c4b9b7100ebf578bbb4117438
- Trigger Event: push

File details

Details for the file pyuppsala-0.10.0-cp310-abi3-win_amd64.whl.

File metadata

Download URL: pyuppsala-0.10.0-cp310-abi3-win_amd64.whl
Upload date: Aug 1, 2026
Size: 1.9 MB
Tags: CPython 3.10+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyuppsala-0.10.0-cp310-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`a296a2dca083f16db21e2b054841b40fd53d8703ac0a2961d786368f66de25a2`
MD5	`15ca3481b61beaa2770c9c9089d9ee78`
BLAKE2b-256	`6b633e8918ceef0c9c40cf534a4dca8962ee72aecd0daa583b96577c74524eb5`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyuppsala-0.10.0-cp310-abi3-win_amd64.whl:

Publisher: release.yml on kushaldas/pyuppsala

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: pyuppsala-0.10.0-cp310-abi3-win_amd64.whl
- Subject digest: a296a2dca083f16db21e2b054841b40fd53d8703ac0a2961d786368f66de25a2
- Sigstore transparency entry: 2313048450
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: kushaldas/pyuppsala@5ccebd279582450c4b9b7100ebf578bbb4117438
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/kushaldas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5ccebd279582450c4b9b7100ebf578bbb4117438
- Trigger Event: push

File details

Details for the file pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 1, 2026
Size: 1.9 MB
Tags: CPython 3.10+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`4c0f5b426a14f1d08f3729e562170e3f2c5c6551d7cbf145156094e05bfb7fbc`
MD5	`beadd859518ce19c462a994c0e481d6c`
BLAKE2b-256	`1a08eee11d6147123d0ecd1338cfd8350e1305c6a3c96f072af734cebebcfa9d`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl:

Publisher: release.yml on kushaldas/pyuppsala

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: pyuppsala-0.10.0-cp310-abi3-manylinux_2_28_x86_64.whl
- Subject digest: 4c0f5b426a14f1d08f3729e562170e3f2c5c6551d7cbf145156094e05bfb7fbc
- Sigstore transparency entry: 2313048688
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: kushaldas/pyuppsala@5ccebd279582450c4b9b7100ebf578bbb4117438
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/kushaldas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5ccebd279582450c4b9b7100ebf578bbb4117438
- Trigger Event: push

File details

Details for the file pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
Upload date: Aug 1, 2026
Size: 1.7 MB
Tags: CPython 3.10+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`ec3a4de49fd0fbe22ed99f4d6882a360963b8c104c6e7d7e6461b027dcfd444e`
MD5	`98f2205f7c3bb7ea01e995d79699853b`
BLAKE2b-256	`cdc9bb852fae47ce1cbcad9b7e95448f7d9e082a0c5c205148cea9788d08d5ba`

See more details on using hashes here.

Provenance

The following attestation bundles were made for pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl:

Publisher: release.yml on kushaldas/pyuppsala

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: pyuppsala-0.10.0-cp310-abi3-macosx_11_0_arm64.whl
- Subject digest: ec3a4de49fd0fbe22ed99f4d6882a360963b8c104c6e7d7e6461b027dcfd444e
- Sigstore transparency entry: 2313048552
- Sigstore integration time: Aug 1, 2026
Source repository:
- Permalink: kushaldas/pyuppsala@5ccebd279582450c4b9b7100ebf578bbb4117438
- Branch / Tag: refs/tags/v0.10.0
- Owner: https://github.com/kushaldas
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: release.yml@5ccebd279582450c4b9b7100ebf578bbb4117438
- Trigger Event: push