xmlcst

Full-fidelity XML concrete syntax tree for Python -- parse, edit, and serialize with zero formatting loss.

Why xmlcst?

Existing Python XML libraries (ElementTree, lxml, minidom) parse XML into a semantic tree that discards lexical details: whitespace, comment placement, attribute quote styles, entity reference forms, and more. When you serialize back, the output differs from the input even if you changed nothing.

xmlcst takes a different approach. It treats XML as source text first and semantic structure second, producing a concrete syntax tree (CST) that retains every byte of the original document. When you edit a single attribute, only that attribute changes in the output -- surrounding formatting, comments, and whitespace remain untouched.

This makes xmlcst ideal for programmatic editing of XML configuration files (Maven POMs, .csproj files, Spring configs, Android manifests) where changes must produce minimal, reviewable diffs.

How xmlcst compares

The closest conceptual analogue is ruamel.yaml -- a round-trip-capable YAML library -- applied to XML.

Installation

pip install xmlcst

Requires Python 3.12+. Pure Python -- no compiled dependencies. Ships PEP 561 type annotations for full mypy / pyright support.

Quick Start

Parse and round-trip

import xmlcst

source = '<project xmlns="http://maven.apache.org/POM/4.0.0">\n  <version>1.0</version>\n</project>'

doc = xmlcst.parse(source)
assert doc.to_string() == source  # byte-identical round-trip

Edit an attribute (minimal diff)

doc = xmlcst.parse('<root version="1.0" author="alice"/>')
doc.root.attributes["version"] = "2.0"
print(doc.to_string())
# <root version="2.0" author="alice"/>
# Only the value changed -- quotes, whitespace, other attributes untouched

Navigate the tree

doc = xmlcst.parse("""\
<project>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
    </dependency>
  </dependencies>
</project>""")

deps = doc.root.find("dependencies")
dep = deps.find("dependency")
group = dep.find("groupId")
print(group.children[0].content)  # "junit" (a Text node)

# Or search recursively
dep2 = doc.root.find_recursive("dependency")
all_deps = doc.root.findall_recursive("dependency")

Add and remove elements

doc = xmlcst.parse("<root>\n  <a/>\n  <b/>\n</root>")
doc.root.append(xmlcst.Element("c"))
print(doc.to_string())
# <root>
#   <a/>
#   <b/>
#   <c/>
# </root>

Access formatting metadata

doc = xmlcst.parse('<root  id = "1"  name=\'foo\'/>')
attr = doc.root.attributes["id"]
print(attr.raw_value)          # "1"
print(attr.quote)              # '"'
print(attr.leading_whitespace) # "  "
print(attr.eq_whitespace)      # (" ", " ")

Work with entity references

doc = xmlcst.parse("<root>a &amp; b</root>")
text = doc.root.children[0]
print(text.content)            # "a &amp; b"  (raw, as in the source)
print(text.decoded_content())  # "a & b"      (entities resolved)

text.set_content("x < y")     # auto-escapes
print(text.content)            # "x &lt; y"

Sample Application

The samples/bump_pom_version/ directory contains a complete example: a Maven POM version bumper that reads a pom.xml, increments the patch version, and writes the file back. Only the version string changes -- all comments, whitespace, attribute quoting, and other formatting are preserved exactly.

python samples/bump_pom_version/bump_pom_version.py
# 1.2.3 -> 1.2.4

The script accepts an optional path argument to operate on any POM file:

python samples/bump_pom_version/bump_pom_version.py /path/to/your/pom.xml

API Overview

Parsing

All parse functions raise xmlcst.ParseError on malformed input. The error includes message, line, column, and offset attributes.

Node Types

Serialization

Design

xmlcst uses a dual-layer architecture:

1. Token stream (Layer 1) -- a lossless sequence of tokens covering every byte of the input. The fundamental invariant: "".join(t.text for t in tokens) == source.
2. Tree API (Layer 2) -- mutable nodes backed by the token stream. Each node tracks a token span and a dirty flag.

Unmodified nodes serialize by replaying their original tokens (byte-identical). Modified nodes rebuild from their current properties. This guarantees that edits produce the smallest possible diff.

See SPEC.md for the full specification.

Limitations (v1)

• UTF-8 encoding only
• XML 1.0 well-formed documents only (no error recovery)
• No DTD validation or schema support
• No XPath query engine
• No streaming / SAX-style parsing
• Pure Python (no compiled acceleration)

See the future roadmap in the specification for planned enhancements.

License

MIT