json2xml 6.0.6__tar.gz → 6.1.0__tar.gz

{json2xml-6.0.6 → json2xml-6.1.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.6 → json2xml-6.1.0}/HISTORY.rst

@@ -1,4 +1,18 @@
 
+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
+==================
+
+  * fix: handle JSON conversion edge cases and improve URL reader robustness (#284)
+  * chore(deps-dev): bump pytest from 9.0.1 to 9.0.3 (#282)
+
+
 6.0.6 / 2026-04-08
 ==================
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 6.0.6
+Version: 6.1.0
 Summary: Simple Python Library to convert JSON to XML
 Author-email: Vinit Kumar <mail@vinitkumar.me>
 License: Apache Software License 2.0
@@ -54,7 +54,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 +62,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
@@ -79,7 +210,7 @@ Installation
 
     pip install json2xml
 
-**With Native Rust Acceleration (up to 149x faster)**
+**With Native Rust Acceleration (up to 129x faster)**
 
 For maximum performance, install the optional Rust extension:
 
@@ -91,7 +222,7 @@ For maximum performance, install the optional Rust extension:
     # Or install the Rust extension separately
     pip install json2xml-rs
 
-The Rust extension provides **75-149x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
+The Rust extension provides **57-129x faster** conversion compared to pure Python in the latest benchmark. It's automatically used when available, with seamless fallback to pure Python.
 
 **As a CLI Tool**
 
@@ -337,7 +468,7 @@ Using tools directly:
 
 **Rust Extension Development**
 
-The optional Rust extension (``json2xml-rs``) provides up to 149x faster performance. To develop or build the Rust extension:
+The optional Rust extension (``json2xml-rs``) provides up to 129x faster performance in the latest benchmark. To develop or build the Rust extension:
 
 Prerequisites:
 
@@ -464,21 +595,21 @@ For users who need maximum performance within Python, json2xml includes an optio
      - Rust Extension
      - Speedup
    * - **Small JSON** (47 bytes)
-     - 78µs
-     - 1.05µs
-     - **75x**
+     - 31.49µs
+     - 0.55µs
+     - **56.8x**
    * - **Medium JSON** (3.2 KB)
-     - 2.15ms
-     - 15µs
-     - **139x**
+     - 1.69ms
+     - 16.15µs
+     - **105.0x**
    * - **Large JSON** (32 KB)
-     - 22ms
-     - 151µs
-     - **146x**
+     - 17.97ms
+     - 168.21µs
+     - **106.8x**
    * - **Very Large JSON** (323 KB)
-     - 219ms
-     - 1.47ms
-     - **149x**
+     - 183.33ms
+     - 1.42ms
+     - **129.0x**
 
 **Usage with Rust Extension:**
 
@@ -508,7 +639,7 @@ For other platforms, the pure Python version is used automatically.
 Performance Benchmarks
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Comprehensive benchmarks comparing all implementations (Apple Silicon, January 2026):
+Comprehensive benchmarks comparing all implementations (Apple Silicon, macOS 26.4.1, Python 3.14.4, April 2026):
 
 .. list-table::
    :header-rows: 1
@@ -521,40 +652,40 @@ Comprehensive benchmarks comparing all implementations (Apple Silicon, January 2
      - Zig
      - Best
    * - **Small** (47B)
-     - 40µs
-     - 1.5µs
-     - 4.6ms
-     - 3.7ms
-     - Rust (28x)
+     - 31.49µs
+     - 0.55µs
+     - 4.09ms
+     - 2.02ms
+     - Rust (56.8x)
    * - **Medium** (3.2KB)
-     - 2.1ms
-     - 71µs
-     - 4.1ms
-     - 3.3ms
-     - Rust (30x)
+     - 1.69ms
+     - 16.15µs
+     - 4.07ms
+     - 2.09ms
+     - Rust (105.0x)
    * - **Large** (32KB)
-     - 21ms
-     - 740µs
-     - 4ms
-     - 6.1ms
-     - Rust (28x)
+     - 17.97ms
+     - 168.21µs
+     - 4.10ms
+     - 2.42ms
+     - Rust (106.8x)
    * - **Very Large** (323KB)
-     - 213ms
-     - 7.5ms
-     - 4.4ms
-     - 33ms
-     - Go (48x)
+     - 183.33ms
+     - 1.42ms
+     - 4.20ms
+     - 5.12ms
+     - Rust (129.0x)
 
 **Key Findings:**
 
-- **Rust extension**: ~28x faster than Python, zero overhead (best for Python users)
-- **Go CLI**: 48x faster for large files (300KB+), but has ~4ms startup overhead
-- **Zig CLI**: 3-6x faster for medium-large files
+- **Rust extension**: 57-129x faster than Python, zero process overhead (best for Python users)
+- **Go CLI**: 43.6x faster for very large files (300KB+), but has ~4ms startup overhead
+- **Zig CLI**: 7.4x faster for large files and 35.8x faster for very large files, with ~2ms startup overhead
 
 **Recommendation by Use Case:**
 
-- **Python library calls**: Use ``pip install json2xml[fast]`` (Rust, 28x faster)
-- **Large file CLI processing**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ (Go, 48x for 300KB+)
+- **Python library calls**: Use ``pip install json2xml[fast]`` (Rust, up to 129x faster)
+- **Large file CLI processing**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ or `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ depending on your workload
 - **Pure Python required**: Use ``pip install json2xml``
 
 For detailed benchmarks, see `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_.
@@ -565,13 +696,12 @@ Other Implementations
 
 This library is also available in other languages:
 
-- **Rust**: `json2xml-rs <https://pypi.org/project/json2xml-rs/>`_ - 28x faster, Python extension via PyO3
-- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 48x faster for large files, native CLI
-- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 6x faster, native CLI
+- **Rust**: `json2xml-rs <https://pypi.org/project/json2xml-rs/>`_ - up to 129x faster, Python extension via PyO3
+- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 43.6x faster for very large files, native CLI
+- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 35.8x faster for very large files, native CLI
 
 
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - You can sponsor my work for this plugin here: https://github.com/sponsors/vinitkumar/
-

{json2xml-6.0.6 → json2xml-6.1.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
@@ -43,7 +174,7 @@ Installation
 
     pip install json2xml
 
-**With Native Rust Acceleration (up to 149x faster)**
+**With Native Rust Acceleration (up to 129x faster)**
 
 For maximum performance, install the optional Rust extension:
 
@@ -55,7 +186,7 @@ For maximum performance, install the optional Rust extension:
     # Or install the Rust extension separately
     pip install json2xml-rs
 
-The Rust extension provides **75-149x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
+The Rust extension provides **57-129x faster** conversion compared to pure Python in the latest benchmark. It's automatically used when available, with seamless fallback to pure Python.
 
 **As a CLI Tool**
 
@@ -301,7 +432,7 @@ Using tools directly:
 
 **Rust Extension Development**
 
-The optional Rust extension (``json2xml-rs``) provides up to 149x faster performance. To develop or build the Rust extension:
+The optional Rust extension (``json2xml-rs``) provides up to 129x faster performance in the latest benchmark. To develop or build the Rust extension:
 
 Prerequisites:
 
@@ -428,21 +559,21 @@ For users who need maximum performance within Python, json2xml includes an optio
      - Rust Extension
      - Speedup
    * - **Small JSON** (47 bytes)
-     - 78µs
-     - 1.05µs
-     - **75x**
+     - 31.49µs
+     - 0.55µs
+     - **56.8x**
    * - **Medium JSON** (3.2 KB)
-     - 2.15ms
-     - 15µs
-     - **139x**
+     - 1.69ms
+     - 16.15µs
+     - **105.0x**
    * - **Large JSON** (32 KB)
-     - 22ms
-     - 151µs
-     - **146x**
+     - 17.97ms
+     - 168.21µs
+     - **106.8x**
    * - **Very Large JSON** (323 KB)
-     - 219ms
-     - 1.47ms
-     - **149x**
+     - 183.33ms
+     - 1.42ms
+     - **129.0x**
 
 **Usage with Rust Extension:**
 
@@ -472,7 +603,7 @@ For other platforms, the pure Python version is used automatically.
 Performance Benchmarks
 ^^^^^^^^^^^^^^^^^^^^^^
 
-Comprehensive benchmarks comparing all implementations (Apple Silicon, January 2026):
+Comprehensive benchmarks comparing all implementations (Apple Silicon, macOS 26.4.1, Python 3.14.4, April 2026):
 
 .. list-table::
    :header-rows: 1
@@ -485,40 +616,40 @@ Comprehensive benchmarks comparing all implementations (Apple Silicon, January 2
      - Zig
      - Best
    * - **Small** (47B)
-     - 40µs
-     - 1.5µs
-     - 4.6ms
-     - 3.7ms
-     - Rust (28x)
+     - 31.49µs
+     - 0.55µs
+     - 4.09ms
+     - 2.02ms
+     - Rust (56.8x)
    * - **Medium** (3.2KB)
-     - 2.1ms
-     - 71µs
-     - 4.1ms
-     - 3.3ms
-     - Rust (30x)
+     - 1.69ms
+     - 16.15µs
+     - 4.07ms
+     - 2.09ms
+     - Rust (105.0x)
    * - **Large** (32KB)
-     - 21ms
-     - 740µs
-     - 4ms
-     - 6.1ms
-     - Rust (28x)
+     - 17.97ms
+     - 168.21µs
+     - 4.10ms
+     - 2.42ms
+     - Rust (106.8x)
    * - **Very Large** (323KB)
-     - 213ms
-     - 7.5ms
-     - 4.4ms
-     - 33ms
-     - Go (48x)
+     - 183.33ms
+     - 1.42ms
+     - 4.20ms
+     - 5.12ms
+     - Rust (129.0x)
 
 **Key Findings:**
 
-- **Rust extension**: ~28x faster than Python, zero overhead (best for Python users)
-- **Go CLI**: 48x faster for large files (300KB+), but has ~4ms startup overhead
-- **Zig CLI**: 3-6x faster for medium-large files
+- **Rust extension**: 57-129x faster than Python, zero process overhead (best for Python users)
+- **Go CLI**: 43.6x faster for very large files (300KB+), but has ~4ms startup overhead
+- **Zig CLI**: 7.4x faster for large files and 35.8x faster for very large files, with ~2ms startup overhead
 
 **Recommendation by Use Case:**
 
-- **Python library calls**: Use ``pip install json2xml[fast]`` (Rust, 28x faster)
-- **Large file CLI processing**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ (Go, 48x for 300KB+)
+- **Python library calls**: Use ``pip install json2xml[fast]`` (Rust, up to 129x faster)
+- **Large file CLI processing**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ or `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ depending on your workload
 - **Pure Python required**: Use ``pip install json2xml``
 
 For detailed benchmarks, see `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_.
@@ -529,13 +660,12 @@ Other Implementations
 
 This library is also available in other languages:
 
-- **Rust**: `json2xml-rs <https://pypi.org/project/json2xml-rs/>`_ - 28x faster, Python extension via PyO3
-- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 48x faster for large files, native CLI
-- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 6x faster, native CLI
+- **Rust**: `json2xml-rs <https://pypi.org/project/json2xml-rs/>`_ - up to 129x faster, Python extension via PyO3
+- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 43.6x faster for very large files, native CLI
+- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 35.8x faster for very large files, native CLI
 
 
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 - You can sponsor my work for this plugin here: https://github.com/sponsors/vinitkumar/
-