elementpath

elementpath adds full XPath 1.0, 2.0, 3.0, and 3.1 selector support to Python’s standard xml.etree.ElementTree as well as to lxml.etree. Where the standard library only ships a limited XPath subset and lxml only implements XPath 1.0, elementpath fills the gap with a complete, spec-oriented implementation of the modern XPath language versions, exposed through a simple select() / iter_select() API and a reusable Selector class.

Internally it is a pure-Python engine built on a Top-Down Operator Precedence (Pratt) parser, with data-type support, collations, sequence types, and an optional schema proxy for XSD-aware evaluation. The package is fully type-hinted, dependency-free at runtime, and underpins the widely used xmlschema library.

What You Get

• A complete XPath 1.0/2.0/3.0/3.1 engine usable from both ElementTree and lxml
• Simple select() and iter_select() functions plus a reusable Selector class
• XPath data types, collations, sequence types, and function library support
• An optional schema proxy for XSD-aware, typed XPath evaluation
• Full type hints (py.typed) and zero runtime dependencies

Common Use Cases

• Querying XML documents with XPath 2.0+ features that the standard library lacks
• Adding XPath 2.0/3.0/3.1 selectors to lxml, which natively supports only XPath 1.0
• Powering XSD schema validation tooling that needs typed XPath evaluation
• Extracting or transforming nodes from complex XML with expressive path queries

Under The Hood

Architecture - The engine is built around a Top-Down Operator Precedence (Pratt) parser defined in tdop.py, with version-specific token sets layered in xpath1/, xpath2/, xpath3.py, xpath30/, and xpath31/. Evaluation flows through an XPathContext (xpath_context.py) over an abstracted node model (xpath_nodes.py, tree_builders.py) that normalizes both ElementTree and lxml trees. Public entry points live in xpath_selectors.py (select, iter_select, Selector), and a schema_proxy.py bridges XSD type information for typed evaluation.

Tech Stack - Pure Python targeting 3.10+, packaged via pyproject.toml with no required runtime dependencies; lxml, mypy, sphinx, and xmlschema appear only as optional dev/test extras. It supports XPath datatypes, collations, and regex handling through dedicated datatypes/, collations.py, and regex/ modules.

Code Quality - The project is production-grade: a large tests/ suite includes W3C conformance runners, memory profiling, and dedicated mypy typing tests, and the package ships py.typed for full static-typing support. Development-status classifiers mark it Production/Stable, and it is depended on by the mature xmlschema library.

API Design - The public API is deliberately minimal and ergonomic: a one-line elementpath.select(root, expression) mirrors ElementTree’s own findall mental model while unlocking far richer expressions. The Selector class allows compiling an expression once for repeated evaluation, and behavior stays consistent across ElementTree and lxml backends.