json2xml 6.0.7__tar.gz → 6.2.0__tar.gz

{json2xml-6.0.7 → json2xml-6.2.0}/CONTRIBUTING.rst

@@ -9,6 +9,17 @@ helps, and credit will always be given.
 
 You can contribute in many ways:
 
+Good First Contributions
+------------------------
+
+If you are new to the project, these are useful places to start:
+
+* Improve examples for real-world API responses, files, and command-line usage.
+* Add small tests around conversion options such as wrappers, list handling, CDATA, and XPath output.
+* Improve benchmark documentation or add a reproducible benchmark case.
+* Polish CLI behavior, error messages, and help text.
+* Review the roadmap in ``ROADMAP.md`` and open a focused issue before starting larger changes.
+
 Types of Contributions
 ----------------------
 
@@ -99,7 +110,7 @@ Ready to contribute? Here's how to set up `json2xml` for local development.
 Rust Extension Development
 --------------------------
 
-The ``json2xml-rs`` Rust extension provides ~29x faster performance. If you want to contribute to the Rust extension:
+The ``json2xml-rs`` Rust extension provides ~57-129x faster performance in the current benchmark. If you want to contribute to the Rust extension:
 
 **Prerequisites**
 

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

@@ -1,4 +1,22 @@
 
+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
+==================
+
+  * fix: address open contribution issues (#292)
+  * docs: improve README and add public roadmap (#287)
+
+
 6.0.7 / 2026-04-26
 ==================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 6.0.7
+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
@@ -54,7 +55,7 @@ json2xml
 .. image:: https://codecov.io/gh/vinitkumar/json2xml/branch/master/graph/badge.svg?token=Yt2h55eTL2
       :target: https://codecov.io/gh/vinitkumar/json2xml
 
-json2xml is a Python library that allows you to convert JSON data into XML format. It's simple, efficient, and easy to use.
+json2xml is a Python library and CLI for converting JSON data into XML. It is designed for teams that need predictable XML output, Python-first ergonomics, and a faster native path when conversion speed matters.
 
 Documentation: https://json2xml.readthedocs.io.
 
@@ -62,6 +63,137 @@ The library was initially dependent on the `dict2xml` project, but it has now be
 
 **Looking for a Go version?** Check out `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_, a Go port of this library with identical features and a native CLI tool.
 
+Why json2xml?
+^^^^^^^^^^^^^
+
+Use json2xml when you need:
+
+* A Python library for turning dictionaries, strings, files, or API responses into XML
+* A command-line tool for quick JSON-to-XML conversion from scripts and terminals
+* Optional Rust acceleration with automatic fallback to the pure Python implementation
+* XPath 3.1 compatible output when standards-friendly XML is required
+* A small, focused project with tests, docs, benchmarks, and multiple native implementation experiments
+
+Quick Start
+^^^^^^^^^^^
+
+Install the Python package:
+
+.. code-block:: console
+
+    pip install json2xml
+
+Use it from Python:
+
+.. code-block:: python
+
+    from json2xml import json2xml
+    from json2xml.utils import readfromstring
+
+    data = readfromstring('{"name": "Ada", "language": "Python"}')
+    print(json2xml.Json2xml(data).to_xml())
+
+Use it from the terminal:
+
+.. code-block:: console
+
+    json2xml-py -s '{"name": "Ada", "language": "Python"}'
+
+Install the accelerated path:
+
+.. code-block:: console
+
+    pip install json2xml[fast]
+
+Real-world Examples
+^^^^^^^^^^^^^^^^^^^
+
+Convert a JSON API response in Python when another system expects XML:
+
+.. code-block:: python
+
+    from json2xml import json2xml
+
+    api_response = {"user": {"id": 7, "name": "Ada"}, "active": True}
+    print(json2xml.Json2xml(api_response, pretty=False).to_xml().decode("utf-8"))
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><user type="dict"><id type="int">7</id><name type="str">Ada</name></user><active type="bool">true</active></all>
+
+Convert a local JSON export from the shell:
+
+.. code-block:: console
+
+    cat > orders.json <<'JSON'
+    {"orders":[{"id":"A100","total":19.99},{"id":"A101","total":5.5}]}
+    JSON
+    json2xml-py --no-pretty --no-type orders.json
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><orders><item><id>A100</id><total>19.99</total></item><item><id>A101</id><total>5.5</total></item></orders></all>
+
+Convert stdin in a shell pipeline:
+
+.. code-block:: console
+
+    printf '%s\n' '{"event":"deploy","status":"ok"}' | json2xml-py --no-pretty --no-type -
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><event>deploy</event><status>ok</status></all>
+
+Performance Snapshot
+^^^^^^^^^^^^^^^^^^^^
+
+The optional Rust extension is the fastest path for Python callers because it avoids process startup overhead and falls back to pure Python when a feature is not supported natively.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 15
+
+   * - Test Case
+     - Pure Python
+     - Rust Extension
+     - Speedup
+   * - **Small JSON** (47 bytes)
+     - 31.49µs
+     - 0.55µs
+     - **56.8x**
+   * - **Medium JSON** (3.2 KB)
+     - 1.69ms
+     - 16.15µs
+     - **105.0x**
+   * - **Large JSON** (32 KB)
+     - 17.97ms
+     - 168.21µs
+     - **106.8x**
+   * - **Very Large JSON** (323 KB)
+     - 183.33ms
+     - 1.42ms
+     - **129.0x**
+
+See `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_ for the full Python, Rust, Go, and Zig comparison.
+
+Project Roadmap
+^^^^^^^^^^^^^^^
+
+The next phase of json2xml is focused on making the project easier to adopt, benchmark, and contribute to:
+
+* Improve examples for common API, file, and CLI workflows
+* Add clearer contribution paths for docs, CLI polish, and benchmark coverage
+* Keep comparing Python, Rust, Go, and Zig implementations with reproducible benchmarks
+* Continue hardening the Rust extension fallback behavior across platforms
+
+See `ROADMAP.md <https://github.com/vinitkumar/json2xml/blob/master/ROADMAP.md>`_ for more detail.
+
 
 
 Architecture Diagram
@@ -574,4 +706,3 @@ Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - You can sponsor my work for this plugin here: https://github.com/sponsors/vinitkumar/
-

{json2xml-6.0.7 → json2xml-6.2.0}/README.rst

@@ -18,7 +18,7 @@ json2xml
 .. image:: https://codecov.io/gh/vinitkumar/json2xml/branch/master/graph/badge.svg?token=Yt2h55eTL2
       :target: https://codecov.io/gh/vinitkumar/json2xml
 
-json2xml is a Python library that allows you to convert JSON data into XML format. It's simple, efficient, and easy to use.
+json2xml is a Python library and CLI for converting JSON data into XML. It is designed for teams that need predictable XML output, Python-first ergonomics, and a faster native path when conversion speed matters.
 
 Documentation: https://json2xml.readthedocs.io.
 
@@ -26,6 +26,137 @@ The library was initially dependent on the `dict2xml` project, but it has now be
 
 **Looking for a Go version?** Check out `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_, a Go port of this library with identical features and a native CLI tool.
 
+Why json2xml?
+^^^^^^^^^^^^^
+
+Use json2xml when you need:
+
+* A Python library for turning dictionaries, strings, files, or API responses into XML
+* A command-line tool for quick JSON-to-XML conversion from scripts and terminals
+* Optional Rust acceleration with automatic fallback to the pure Python implementation
+* XPath 3.1 compatible output when standards-friendly XML is required
+* A small, focused project with tests, docs, benchmarks, and multiple native implementation experiments
+
+Quick Start
+^^^^^^^^^^^
+
+Install the Python package:
+
+.. code-block:: console
+
+    pip install json2xml
+
+Use it from Python:
+
+.. code-block:: python
+
+    from json2xml import json2xml
+    from json2xml.utils import readfromstring
+
+    data = readfromstring('{"name": "Ada", "language": "Python"}')
+    print(json2xml.Json2xml(data).to_xml())
+
+Use it from the terminal:
+
+.. code-block:: console
+
+    json2xml-py -s '{"name": "Ada", "language": "Python"}'
+
+Install the accelerated path:
+
+.. code-block:: console
+
+    pip install json2xml[fast]
+
+Real-world Examples
+^^^^^^^^^^^^^^^^^^^
+
+Convert a JSON API response in Python when another system expects XML:
+
+.. code-block:: python
+
+    from json2xml import json2xml
+
+    api_response = {"user": {"id": 7, "name": "Ada"}, "active": True}
+    print(json2xml.Json2xml(api_response, pretty=False).to_xml().decode("utf-8"))
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><user type="dict"><id type="int">7</id><name type="str">Ada</name></user><active type="bool">true</active></all>
+
+Convert a local JSON export from the shell:
+
+.. code-block:: console
+
+    cat > orders.json <<'JSON'
+    {"orders":[{"id":"A100","total":19.99},{"id":"A101","total":5.5}]}
+    JSON
+    json2xml-py --no-pretty --no-type orders.json
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><orders><item><id>A100</id><total>19.99</total></item><item><id>A101</id><total>5.5</total></item></orders></all>
+
+Convert stdin in a shell pipeline:
+
+.. code-block:: console
+
+    printf '%s\n' '{"event":"deploy","status":"ok"}' | json2xml-py --no-pretty --no-type -
+
+Output:
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?><all><event>deploy</event><status>ok</status></all>
+
+Performance Snapshot
+^^^^^^^^^^^^^^^^^^^^
+
+The optional Rust extension is the fastest path for Python callers because it avoids process startup overhead and falls back to pure Python when a feature is not supported natively.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 15
+
+   * - Test Case
+     - Pure Python
+     - Rust Extension
+     - Speedup
+   * - **Small JSON** (47 bytes)
+     - 31.49µs
+     - 0.55µs
+     - **56.8x**
+   * - **Medium JSON** (3.2 KB)
+     - 1.69ms
+     - 16.15µs
+     - **105.0x**
+   * - **Large JSON** (32 KB)
+     - 17.97ms
+     - 168.21µs
+     - **106.8x**
+   * - **Very Large JSON** (323 KB)
+     - 183.33ms
+     - 1.42ms
+     - **129.0x**
+
+See `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_ for the full Python, Rust, Go, and Zig comparison.
+
+Project Roadmap
+^^^^^^^^^^^^^^^
+
+The next phase of json2xml is focused on making the project easier to adopt, benchmark, and contribute to:
+
+* Improve examples for common API, file, and CLI workflows
+* Add clearer contribution paths for docs, CLI polish, and benchmark coverage
+* Keep comparing Python, Rust, Go, and Zig implementations with reproducible benchmarks
+* Continue hardening the Rust extension fallback behavior across platforms
+
+See `ROADMAP.md <https://github.com/vinitkumar/json2xml/blob/master/ROADMAP.md>`_ for more detail.
+
 
 
 Architecture Diagram
@@ -538,4 +669,3 @@ Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - You can sponsor my work for this plugin here: https://github.com/sponsors/vinitkumar/
-

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.