Obj2XML-rs

High-performance, memory-efficient XML generator for Python, written in Rust.

A fast, deterministic, streaming-capable JSON→XML DSL with Python ergonomics. obj2xml-rs is a drop-in replacement for libraries like xmltodict.unparse but designed for speed, scalability, and correctness. It leverages Rust's zero-copy optimizations and streaming capabilities to handle massive datasets without exhausting system memory.

🚀 Features

⚡ Blazing Fast: Built on quick-xml with Zero-Copy (Cow<str>) optimizations. 5-15x faster than pure Python.

🌊 True Streaming: Supports Python Generators and Iterators. Writes huge XML files item-by-item directly to disk.

🛡️ Robust Error Context: Exceptions include the full XML path (e.g., Error at root/users/[3]/@id).

🔒 Safe: Includes cycle detection to prevent infinite recursion crashes.

🔧 Professional Spec: Supports Namespaces, CDATA, Comments, Processing Instructions, and deterministic attribute sorting.

🐍 Pythonic: Supports default handlers for custom types (like datetime), similar to json.dump.

📦 Installation

pip install obj2xml-rs

📖 Quick Start

import obj2xml_rs

data = {
    "root": {
    "@id": "123",
    "name": "Rust",
    "features": ["Fast", "Safe"]
    }
}
print(obj2xml_rs.unparse(data, pretty=True))

Output:

<?xml version="1.0" encoding="utf-8"?>
<root id="123">
  <name>Rust</name>
  <features>Fast</features>
  <features>Safe</features>
</root>

Streaming (Low Memory)

Generate XML from a generator. Writes to file incrementally.

def huge_data():
    for i in range(1_000_000):
        yield {"row": {"id": i, "val": f"data_{i}"}}

obj2xml_rs.unparse(
    huge_data(),
    output="large.xml",
    streaming=True,
    item_name="row"
)

📋 Specification & Behavior

This section defines how Python structures map to XML.

1. Reserved Keys

The following keys have special meaning in a dictionary:

Key	Description	Example
@key	XML Attribute (prefix configurable)	{"@id": 1} →
#text	Element text content	{"tag": {"#text": "Hello"}} → Hello
#comment	XML Comment	{"#comment": "Note"} →
?key	Processing Instruction	{"?xml-stylesheet": "href..."} →
#tail	Text content appearing immediately after the element's closing tag.	{"b": {"#text": "Bold", "#tail": " text"}} → < b>Bold</ b> text
cdata	CDATA Wrapper	{"#text": {"cdata": "x<y"}} →

2. Element Mapping & Lists

Dict Keys: Map directly to XML Element names. Lists: Keys containing a list generate repeated elements with the same name.

{"items": {"item": [1, 2]}}

<items><item>1</item><item>2</item></items>

Root Primitives: If the input is a list of primitives, they are wrapped in item_name.

unparse([1, 2], item_name="n", full_document=False)

<n>1</n><n>2</n>

3. Attributes & Sorting

Keys starting with attr_prefix (default "@") become attributes. Values: Any serializable value is accepted. Dicts/Lists in attributes are stringified. Sorting: Attributes follow Python insertion order by default. Use sort_attributes=True for deterministic output (attributes sorted lexicographically).

4. Namespaces

Namespaces can be declared in three ways: Static (Root Scope): Best practice for clean XML.

unparse(data, namespaces={"soap": "http://example.com/soap"})

<root xmlns:soap="http://example.com/soap"> ...

Inline Declarations:

{"root": {"@xmlns:x": "urn:x", "x:child": 1}}

Dynamic Assignment:

{"tag": {"@ns": "urn:auto"}}

Automatically generates prefixes (ns0, ns1...)

5. Advanced Nodes

CDATA: Use the cdata key inside a text node. Comments: Use #comment. Processing Instructions: Keys starting with ?.

{"root": {"?xml-stylesheet": 'type="text/xsl" href="style.xsl"'}}

6. Constraints & Validation policies

XML Names: No validation of XML name syntax is performed. If you pass {"": 1}, invalid XML will be generated. Mixed Content: Mixed #text and child elements are allowed.

{"p": {"#text": "Hello", "b": "World"}}

**Valid:** <p>Hello<b>World</b></p>

Root Rules:

 full_document=True (default): Requires exactly one root element.
 full_document=False: Allows multiple roots (XML Fragment).

⚠️ Error Handling

Errors are actionable and include the full path to the problematic node.

def fail_serializer(obj):
    raise ValueError("Bad data")

data = {"users": [{"name": "Alice", "meta": {"@date": object()}}]}

try:
    unparse(data, default=fail_serializer)
except ValueError as e:
    print(e)