Stream Crystal Reports XML at memory bandwidth.

crxml

High-performance Crystal Reports XML → Arrow/DataFrame engine for Python.

Parse, filter, rename, cast, and project Crystal Reports XML directly into
columnar data, with Rust execution, parallel parsing, bounded-memory
processing, and automatic query fusion.

Quick start

from crxml import CrystalXMLSource

source = CrystalXMLSource("report.xml", row_tag="Details")

# Row iteration: yields dicts lazily
for row in source:
    print(row["invoice"], row["amount"])

# DataFrame (auto-routes to parallel engine)
df = source.to_dataframe()
print(df.head())

That is it. df is a pandas DataFrame with zero-copy ArrowDtype strings, built in under a second for a 100 MB file.

With pipeline stages fused into the Rust parse loop:

from crxml.stages import RenameFields, DropFields

pipeline = source | RenameFields({"f1": "invoice"}) | DropFields(["temp_id"])
df = pipeline.to_dataframe()

Why crxml

Crystal Reports XML exports are deeply nested: <Group> wraps <GroupHeader> wraps <Section> wraps <Details> wraps <Field>/<Text>/<FormattedValue>/ <Value>/<TextValue>. Standard XML libraries (ElementTree, SAX, lxml) spend most of their CPU time descending into children you do not need.

crxml skips the nesting:

• The stream engine walks the XML once with quick-xml and yields flat dicts.
• The parallel engine memory-maps the file, splits it at row boundaries, and parses each chunk on its own thread into Arrow buffers directly (no dicts).
• Pipeline stages that rename, cast, drop, or filter fields execute in the Rust parse loop, before any Python object is created.

Comparison: stream vs parallel

The stream engine materializes one dict per row: fully consuming a large file costs roughly 10x its size in memory (~1 GB RSS for a 100 MB file). Use it for incremental processing; use table sinks for collection.

For files larger than RAM, add memory="500MB" to any engine for bounded mode: peak RSS tracks the budget, not the file.

Full benchmark details

Install

pip install crxml

The columnar and parallel engines are included by default. For performance profiling counters: pip install -e . --config-settings=--features=profile.

Features

Engine guide

Pass engine= explicitly, or let auto select the best engine per call.

Framework support

Limitations

• UTF-8 input only. UTF-16 exports (which Crystal Reports can produce) fail validation; convert first.
• No compressed input. .gz/.zst files must be decompressed before parsing.
• Crystal Reports grammar, not general XML. The flat-row model fits CR exports; arbitrary XML documents are out of scope.
• Linux-tuned performance. madvise hints and thread-count ratios were measured on Linux; other platforms work but are untested territory.
• No async API. Row iteration is synchronous.

Documentation

Full docs at crxml.emiliano-go.com covering:

• All CrystalXMLSource parameters
• Pipeline stages and fusion rules
• Sink reference
• Batch iteration and parallel distribution
• Performance with phase breakdowns
• Architecture and correctness

License

MIT