turboxml

A fast, lightweight Python library for reading and writing XML files, powered by Rust.

In a recorded manual benchmark on CPython 3.12.14 / Linux x86-64, turboxml achieved 1.52× the throughput of xml.etree.ElementTree for structured XML with attributes, 1.11× for deeply nested XML, and 12.05× for text-heavy XML. These are three synthetic workloads on one machine, not a typical-speedup guarantee; results depend on the document, Python version, hardware, and build. The benchmark measures full-tree parsing and destruction through each library's public API.

---

Features

• Rust-powered parsing - See the reproducible benchmark for measured results, input definitions, and limitations.
• Shared input storage - Parsed plain strings refer to the input buffer; surviving nodes retain the document. Python field access and decoded/joined strings still allocate.
• Simple API - Read, traverse, and write XML with minimal boilerplate.
• Thread-friendly - Parsing and writing release the GIL, so multiple documents can be processed in parallel from Python threads.
• Clear errors - Malformed XML raises ValueError with position information; a missing file raises FileNotFoundError.
• Type-safe - Ships with a .pyi stub file for full editor autocompletion and type checking.
• Cross-platform - Wheels for CPython 3.10+ and PyPy 3.11 / 3.12 on Windows, macOS, and Linux.

Installation

pip install turboxml

Quick Start

Reading XML

Given an XML file note.xml:

<?xml version="1.0" encoding="UTF-8"?>
<note example_attr="example value">
    <to>
        <name>Example Name</name>
    </to>
    <from>
        <name>Example Name</name>
    </from>
    <heading>An Example Heading</heading>
    <body>An Example Body!</body>
</note>

Parse it with turboxml:

from turboxml import read_file

root = read_file("note.xml", "note")

for child in root.children:
    print(child.name, child.text)

Writing XML

from turboxml import Node, write_file

node = Node(
    name="greeting",
    attrs={"lang": "en"},
    text="Hello, World!",
)
write_file(node, "greeting.xml")

The Node Object

Every parsed element is represented as a Node:

class Node:
    name: str  # Tag name
    attrs: dict[str, str]  # Element attributes
    children: list[Node]  # Child nodes
    text: str | None  # Text content, if any

children and search results are shared references to the same node objects, not copies — repeated access and traversal are cheap.

Refer to the turboxml.pyi stub file for the complete API surface, including read_string, write_string, and additional utilities.

Development

turboxml is built with PyO3 and Maturin.

Prerequisites

• Python 3.10+
• Rust toolchain (stable)
• Maturin (pip install maturin)

Building from Source

git clone https://github.com/RustedBytes/turboxml.git
cd turboxml
python -m venv .venv && source .venv/bin/activate
pip install maturin
maturin develop

Running Tests

cargo test

Contributing

Contributions are welcome! Please open an issue or submit a pull request on GitHub.

License

This project is licensed under the MIT License.