json2xml 6.1.0__tar.gz → 6.2.0__tar.gz

{json2xml-6.1.0 → json2xml-6.2.0}/HISTORY.rst

@@ -1,4 +1,15 @@
 
+6.2.0 / 2026-06-05
+==================
+
+  * feat: reduce peak serializer memory in the pure Python rooted-output path
+  * feat: reduce Rust extension peak serializer memory by writing directly into Python bytes
+  * fix: split PyO3 extension-module linking so ``cargo test`` works on macOS
+  * chore: release ``json2xml-rs`` 0.3.0 and make ``json2xml[fast]`` require the memory-saving Rust package
+  * chore: update the Rust extension crate to Rust 2024 with rust-version 1.96
+  * docs: add reproducible Rust memory benchmark results showing about 49% lower serializer RSS delta
+
+
 6.1.0 / 2026-05-04
 ==================
 

{json2xml-6.1.0 → json2xml-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 6.1.0
+Version: 6.2.0
 Summary: Simple Python Library to convert JSON to XML
 Author-email: Vinit Kumar <mail@vinitkumar.me>
 License: Apache Software License 2.0
@@ -23,15 +23,16 @@ Description-Content-Type: text/x-rst
 License-File: LICENSE
 License-File: AUTHORS.rst
 Requires-Dist: defusedxml
-Requires-Dist: urllib3
+Requires-Dist: urllib3>=2.7.0
 Provides-Extra: dev
 Requires-Dist: pytest>=8.4.1; extra == "dev"
 Requires-Dist: pytest-cov; extra == "dev"
 Requires-Dist: coverage; extra == "dev"
 Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: pygments>=2.20.0; extra == "dev"
 Requires-Dist: xmltodict>=0.12.0; extra == "dev"
 Provides-Extra: fast
-Requires-Dist: json2xml-rs>=0.1.0; extra == "fast"
+Requires-Dist: json2xml-rs>=0.3.0; extra == "fast"
 Dynamic: license-file
 
 .. image:: ./json2xml-hero.png

json2xml-6.2.0/docs/benchmarks.rst

@@ -0,0 +1,203 @@
+Benchmarks
+==========
+
+Comprehensive performance comparison between all json2xml implementations.
+
+Test Environment
+----------------
+
+* **Machine**: Apple Silicon (arm64)
+* **OS**: macOS 26.5 (Darwin 25.5.0)
+* **Python**: 3.14.4
+* **Date**: May 27, 2026
+* **CLI tools**: ``json2xml-go`` and ``json2xml-zig`` from ``/Users/vinitkumar/.local/bin``
+
+Implementations Tested
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 55
+
+   * - Implementation
+     - Type
+     - Notes
+   * - Python
+     - Library
+     - Pure Python ``json2xml``
+   * - Rust
+     - Library
+     - Native extension via PyO3, imported as ``json2xml_rs``
+   * - Go
+     - CLI
+     - Standalone ``json2xml-go`` binary
+   * - Zig
+     - CLI
+     - Standalone ``json2xml-zig`` binary
+
+Test Data
+~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 55 25
+
+   * - Size
+     - Description
+     - Bytes
+   * - Small
+     - Simple object ``{"name": "John", "age": 30, "city": "New York"}``
+     - 47
+   * - Medium
+     - 10 generated records with nested structures
+     - 3,215
+   * - bigexample.json
+     - Real-world patent data
+     - 2,018
+   * - Large
+     - 100 generated records with nested structures
+     - 32,206
+   * - Very Large
+     - 1,000 generated records with nested structures
+     - 323,131
+
+Results
+-------
+
+Performance Summary
+~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 28 18 18 18 18
+
+   * - Test Case
+     - Python
+     - Rust
+     - Go
+     - Zig
+   * - Small (47B)
+     - 3.19µs
+     - 0.86µs
+     - 6.05ms
+     - 3.08ms
+   * - Medium (3.2KB)
+     - 214.83µs
+     - 18.41µs
+     - 5.85ms
+     - 3.12ms
+   * - bigexample (2KB)
+     - 91.20µs
+     - 7.32µs
+     - 5.76ms
+     - 3.08ms
+   * - Large (32KB)
+     - 2.07ms
+     - 175.46µs
+     - 5.89ms
+     - 3.73ms
+   * - Very Large (323KB)
+     - 21.20ms
+     - 1.48ms
+     - 6.82ms
+     - 7.82ms
+
+Speedup vs Pure Python
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 34 22 22 22
+
+   * - Test Case
+     - Rust
+     - Go
+     - Zig
+   * - Small (47B)
+     - **3.7x**
+     - 0.0x*
+     - 0.0x*
+   * - Medium (3.2KB)
+     - **11.7x**
+     - 0.0x*
+     - 0.1x*
+   * - bigexample (2KB)
+     - **12.5x**
+     - 0.0x*
+     - 0.0x*
+   * - Large (32KB)
+     - **11.8x**
+     - 0.4x*
+     - 0.6x*
+   * - Very Large (323KB)
+     - **14.4x**
+     - **3.1x**
+     - **2.7x**
+
+*CLI tools have process spawn overhead of about 3-6ms, which dominates for small inputs.*
+
+Key Observations
+----------------
+
+Rust remains the best option for Python library calls. It avoids process overhead and is about 4-14x faster than the optimized pure Python path in this run.
+
+Recent pure Python improvements substantially reduced conversion time. Medium and large inputs are roughly an order of magnitude faster than the April 2026 baseline, so relative Rust speedups are lower even though Rust is still fastest.
+
+Go and Zig remain useful for native CLI workflows. They are slower for small and medium inputs because startup dominates, but both beat Python on the 323KB workload when full CLI process time is measured.
+
+See ``docs/rust_memory_benchmark.rst`` for the June 2026 Rust peak-memory comparison between the previous extension-boundary copy and the Python bytes-writer implementation.
+
+When to Use Each Implementation
+-------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 25 35
+
+   * - Use Case
+     - Recommended
+     - Why
+   * - Python library calls
+     - **Rust**
+     - 4-14x faster, no process overhead
+   * - Small files via CLI
+     - **Zig**
+     - Fastest startup among native CLIs in this run
+   * - Large files via CLI
+     - **Go** or **Zig**
+     - Both are faster than Python at 323KB
+   * - Batch processing
+     - **Go** or **Rust**
+     - Choose based on shell vs Python integration
+   * - Pure Python required
+     - **Python**
+     - Always available
+
+Running the Benchmarks
+----------------------
+
+Run benchmarks from a clean checkout with the project installed in an isolated environment.
+
+.. code-block:: bash
+
+   uv venv
+   source .venv/bin/activate
+   uv pip install -e .
+   python benchmark_all.py
+
+For Rust benchmarks, install the extension into the same environment.
+
+.. code-block:: bash
+
+   uv pip install maturin
+   cd rust
+   maturin develop --release
+   cd ..
+
+For native CLI benchmarks, install the external tools and verify that the commands are visible.
+
+.. code-block:: bash
+
+   go install github.com/vinitkumar/json2xml-go@latest
+   which json2xml-go
+   which json2xml-zig

json2xml-6.2.0/docs/rust_memory_benchmark.rst

@@ -0,0 +1,110 @@
+Rust Memory Benchmark
+=====================
+
+This benchmark compares peak memory usage before and after the Rust serializer started writing directly into Python ``bytes``.
+
+Summary
+-------
+
+The current branch reduces serializer peak RSS by about **77.44 MiB** on a 100,000-record payload that produces **78.17 MiB** of XML. That is a **49.1% reduction** in serializer memory delta compared with the previous PR commit.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 22 22 22 22
+
+   * - Version
+     - Commit
+     - Avg peak RSS
+     - Avg serializer delta
+     - Avg time
+   * - Previous
+     - ``7dd86b0``
+     - 349.15 MiB
+     - 157.70 MiB
+     - 0.180s
+   * - Current
+     - ``07d840f``
+     - 271.65 MiB
+     - 80.26 MiB
+     - 0.265s
+
+The memory result matches the implementation change: the previous version held roughly one final XML payload in Rust plus one Python ``bytes`` payload, while the current version writes into the Python ``bytes`` object directly.
+
+Methodology
+-----------
+
+The benchmark uses ``benchmark_memory_rust.py`` with a deterministic generated payload so the Rust fast path can be measured without file parsing or pure-Python fallback behavior.
+
+* Machine: Apple Silicon arm64
+* OS: macOS 26.5
+* Python: 3.14.0
+* Build: ``python3 -m maturin develop --release --offline``
+* Payload: 100,000 nested records
+* Input JSON size: 44.31 MiB
+* Output XML size: 78.17 MiB
+* Measurement: process ``ru_maxrss`` after payload creation versus peak after ``json2xml_rs.dicttoxml(payload, attr_type=True)``
+* Sampling: three fresh Python processes per version
+
+The baseline RSS is captured after the large Python payload is already built. The reported serializer delta is ``peak_rss - baseline_rss``, which focuses the comparison on output construction rather than payload allocation.
+
+Raw Samples
+-----------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 24 18 18 18 18
+
+   * - Run
+     - Baseline RSS
+     - Peak RSS
+     - Serializer delta
+     - Time
+   * - previous-release-1
+     - 191.53 MiB
+     - 349.22 MiB
+     - 157.69 MiB
+     - 0.182s
+   * - previous-release-2
+     - 191.39 MiB
+     - 349.09 MiB
+     - 157.70 MiB
+     - 0.179s
+   * - previous-release-3
+     - 191.44 MiB
+     - 349.14 MiB
+     - 157.70 MiB
+     - 0.178s
+   * - current-release-1
+     - 191.45 MiB
+     - 271.77 MiB
+     - 80.31 MiB
+     - 0.265s
+   * - current-release-2
+     - 191.48 MiB
+     - 271.64 MiB
+     - 80.16 MiB
+     - 0.272s
+   * - current-release-3
+     - 191.25 MiB
+     - 271.55 MiB
+     - 80.30 MiB
+     - 0.258s
+
+Tradeoff
+--------
+
+The memory improvement comes with a throughput cost in this release benchmark. Average conversion time increased from 0.180s to 0.265s, about **47.5% slower** for this payload.
+
+That cost is likely from routing every XML write through ``std::io::Write`` and PyO3's bytes writer. The memory win is substantial for large outputs, but latency-sensitive callers may want more timing data before treating the bytes-writer path as a universal improvement.
+
+Reproduction
+------------
+
+Run each version in a fresh process after installing the desired Rust extension build.
+
+.. code-block:: bash
+
+   python3 -m maturin develop --release --offline
+   python3 benchmark_memory_rust.py --records 100000 --label current-release-1
+
+For the previous comparison, install commit ``7dd86b0`` in a temporary worktree, then run the same command from the main checkout so the benchmark script stays identical.

{json2xml-6.1.0 → json2xml-6.2.0}/json2xml/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Vinit Kumar"""
 __email__ = "mail@vinitkumar.me"
-__version__ = "6.1.0"
+__version__ = "6.2.0"