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.11.0 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

For an existing DOM, validator.validate(doc) avoids reparsing XML. The experimental validator.experimental_validate_node(node) validates a selected element independently: it reads document roots directly when no namespace adjustment is needed and otherwise copies the selected subtree in Rust. Copies preserve inherited namespace bindings and apply effective default namespaces to bare element names, matching etree serialization without mutating the source. Empty etree trees raise the same missing-root assertion as validate(). It returns validation errors and releases the GIL.

The etree equivalents are schema.experimental_validate(tree) and schema.experimental_assertValid(tree). These APIs are opt-in and may change. The established validate(), assertValid() and callable schema APIs retain their serialization-based validation path.

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

Exceptions

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

Builds use Uppsala 0.11.0 from crates.io, including the XSLT parameter and reserved xml namespace fixes. A sibling Uppsala checkout is not required.

# 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