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:

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)

Output:

Custom serialization failed: Bad data (at users/[0]/meta/@date)
Circular References: A RecursionError is raised if an object references itself.

⚙️ API Reference

def unparse(
   input: Union[Dict, Iterable, Any],
   *,
   output: Optional[Union[str, IO]] = None,
   encoding: str = "utf-8",
   full_document: bool = True,
   attr_prefix: str = "@",
   cdata_key: str = "#text",
   pretty: bool = False,
   indent: str = "  ",
   compat: str = "native",
   streaming: bool = False,
   default: Optional[Callable[[Any], str]] = None,
   item_name: str = "item",
   sort_attributes: bool = False,
   namespaces: Optional[Dict[str, str]] = None
) -> str:

🖥️ CLI Usage

# Basic
python -m obj2xml_rs input.json -o output.xml --pretty

# Streaming from Pipe
cat huge.json | python -m obj2xml_rs --stream --item-name "record" > out.xml

Python XML Library Comparison Matrix

📄 License

This project is licensed under the Apache License 2.0.