json2xml 5.4.0__tar.gz → 6.0.0__tar.gz

{json2xml-5.4.0 → json2xml-6.0.0}/CONTRIBUTING.rst

@@ -64,11 +64,13 @@ Ready to contribute? Here's how to set up `json2xml` for local development.
 
     $ git clone git@github.com:your_name_here/json2xml.git
 
-3. Install your local copy into a virtualenv. Assuming you have virtualenvwrapper installed, this is how you set up your fork for local development::
+3. Install your local copy using uv (recommended) or pip::
 
-    $ mkvirtualenv json2xml
     $ cd json2xml/
-    $ python setup.py develop
+    $ uv venv
+    $ source .venv/bin/activate
+    $ uv pip install -r requirements-dev.txt
+    $ uv pip install -e .
 
 4. Create a branch for local development::
 
@@ -76,14 +78,15 @@ Ready to contribute? Here's how to set up `json2xml` for local development.
 
    Now you can make your changes locally.
 
-5. When you're done making changes, check that your changes pass flake8 and the
-   tests, including testing other Python versions with tox::
+5. When you're done making changes, check that your changes pass linting and the
+   tests::
 
-    $ flake8 json2xml tests
-    $ python setup.py test or py.test
-    $ tox
-
-   To get flake8 and tox, just pip install them into your virtualenv.
+    $ make check-all  # Runs lint, typecheck, and tests
+    
+    # Or individually:
+    $ ruff check json2xml tests
+    $ mypy json2xml tests
+    $ pytest tests/
 
 6. Commit your changes and push your branch to GitHub::
 
@@ -93,6 +96,59 @@ Ready to contribute? Here's how to set up `json2xml` for local development.
 
 7. Submit a pull request through the GitHub website.
 
+Rust Extension Development
+--------------------------
+
+The ``json2xml-rs`` Rust extension provides ~29x faster performance. If you want to contribute to the Rust extension:
+
+**Prerequisites**
+
+Install Rust and maturin::
+
+    $ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    $ uv pip install maturin
+
+**Building the Extension**
+
+::
+
+    # Build and install in development mode
+    $ cd rust
+    $ uv pip install -e .
+    
+    # Or using maturin directly
+    $ maturin develop --release
+
+**Running Rust Tests**
+
+::
+
+    $ pytest tests/test_rust_dicttoxml.py -v
+
+**Running Benchmarks**
+
+::
+
+    $ python benchmark_rust.py
+
+**Rust Code Structure**
+
+The Rust code is located in ``rust/src/lib.rs`` and includes:
+
+- ``escape_xml()`` - XML character escaping
+- ``wrap_cdata()`` - CDATA section wrapping
+- ``convert_dict()`` - Dictionary to XML conversion
+- ``convert_list()`` - List to XML conversion
+- ``dicttoxml()`` - Main entry point exposed to Python
+
+When making changes to the Rust code:
+
+1. Ensure all existing tests pass
+2. Add tests for new functionality
+3. Run ``cargo fmt`` to format Rust code
+4. Run ``cargo clippy`` for linting
+5. Verify Python compatibility tests pass
+
 Pull Request Guidelines
 -----------------------
 

{json2xml-5.4.0 → json2xml-6.0.0}/HISTORY.rst

@@ -1,6 +1,48 @@
 History
 =======
 
+6.0.0 / 2026-01-16
+==================
+
+**Major Release: Native Rust Extension for 29x Faster Performance**
+
+This release introduces an optional native Rust extension built with PyO3 that provides
+approximately 29x faster JSON to XML conversion compared to pure Python.
+
+New Features:
+
+  * feat: add optional Rust extension (json2xml-rs) for ~29x faster performance
+  * feat: add dicttoxml_fast module with automatic backend selection
+  * feat: seamless fallback to pure Python when Rust extension is not installed
+  * feat: pre-built wheels for Linux (x86_64, aarch64), macOS (Intel, Apple Silicon), Windows
+
+Performance Improvements:
+
+  * Small JSON (47 bytes): 33x faster
+  * Medium JSON (3.2KB): 28x faster
+  * Large JSON (32KB): 30x faster
+  * Very Large JSON (323KB): 29x faster
+
+New Files:
+
+  * rust/ - PyO3 Rust extension source code
+  * json2xml/dicttoxml_fast.py - Auto-selecting wrapper module
+  * tests/test_rust_dicttoxml.py - 65 comprehensive tests for Rust extension
+  * benchmark_rust.py - Performance comparison script
+  * .github/workflows/build-rust-wheels.yml - CI for building wheels
+  * .github/workflows/rust-ci.yml - CI for Rust code quality
+
+Installation:
+
+  * Pure Python: pip install json2xml
+  * With Rust acceleration: pip install json2xml-rs (then import from dicttoxml_fast)
+
+Documentation:
+
+  * Updated README with Rust extension usage and benchmarks
+  * Updated CONTRIBUTING with Rust development guide
+
+
 5.4.0 / 2026-01-15
 ==================
 

{json2xml-5.4.0 → json2xml-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 5.4.0
+Version: 6.0.0
 Summary: Simple Python Library to convert JSON to XML
 Author-email: Vinit Kumar <mail@vinitkumar.me>
 License: Apache Software License 2.0
@@ -33,6 +33,10 @@ Provides-Extra: test
 Requires-Dist: pytest>=8.4.1; extra == "test"
 Dynamic: license-file
 
+.. image:: ./json2xml-hero.png
+   :alt: json2xml hero
+
+
 ========
 json2xml
 ========
@@ -74,6 +78,22 @@ Installation
 
     pip install json2xml
 
+**With Native Rust Acceleration (29x faster)**
+
+For maximum performance, install the optional Rust extension:
+
+.. code-block:: console
+
+    # Install json2xml with Rust acceleration (when published)
+    pip install json2xml[fast]
+    
+    # Or install the Rust extension separately
+    pip install json2xml-rs
+
+The Rust extension provides **29x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
+
+*Note: The ``json2xml-rs`` package will be available on PyPI after the first Rust release.*
+
 **As a CLI Tool**
 
 The library includes a command-line tool ``json2xml-py`` that gets installed automatically:
@@ -316,6 +336,43 @@ Using tools directly:
     ruff check json2xml tests
     mypy json2xml tests
 
+**Rust Extension Development**
+
+The optional Rust extension (``json2xml-rs``) provides 29x faster performance. To develop or build the Rust extension:
+
+Prerequisites:
+
+ .. code-block:: console
+
+    # Install Rust (if not already installed)
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    
+    # Install maturin (Rust-Python build tool)
+    uv pip install maturin
+
+Building the extension:
+
+ .. code-block:: console
+
+    # Development build (installs in current environment)
+    cd rust
+    uv pip install -e .
+    
+    # Or using maturin directly
+    maturin develop --release
+    
+    # Production wheel build
+    maturin build --release
+
+Running Rust benchmarks:
+
+ .. code-block:: console
+
+    # After building the extension
+    python benchmark_rust.py
+
+The Rust code is in ``rust/src/lib.rs`` and uses PyO3 for Python bindings.
+
 
 CLI Usage
 ^^^^^^^^^
@@ -388,6 +445,115 @@ A Go port of this library is available at `json2xml-go <https://github.com/vinit
 The Go version provides the same features and a native compiled binary for maximum performance.
 
 
+Rust Extension (PyO3)
+^^^^^^^^^^^^^^^^^^^^^
+
+For users who need maximum performance within Python, json2xml includes an optional native Rust extension built with PyO3:
+
+.. code-block:: console
+
+    pip install json2xml[fast]
+
+**Rust vs Pure Python Performance:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 15
+
+   * - Test Case
+     - Pure Python
+     - Rust Extension
+     - Speedup
+   * - **Small JSON** (47 bytes)
+     - 41µs
+     - 1.3µs
+     - **33x**
+   * - **Medium JSON** (3.2 KB)
+     - 2.1ms
+     - 76µs
+     - **28x**
+   * - **Large JSON** (32 KB)
+     - 21.5ms
+     - 727µs
+     - **30x**
+   * - **Very Large JSON** (323 KB)
+     - 215ms
+     - 7.4ms
+     - **29x**
+
+**Usage with Rust Extension:**
+
+.. code-block:: python
+
+    # Automatic backend selection (recommended)
+    from json2xml.dicttoxml_fast import dicttoxml, get_backend
+
+    print(f"Using backend: {get_backend()}")  # 'rust' or 'python'
+    
+    data = {"name": "John", "age": 30}
+    xml_bytes = dicttoxml(data)
+
+The ``dicttoxml_fast`` module automatically uses the Rust backend when available and falls back to pure Python for unsupported features (like ``xpath_format``, ``xml_namespaces``, or custom ``item_func``).
+
+**Platform Support:**
+
+Pre-built wheels are available for:
+
+- Linux (x86_64, aarch64)
+- macOS (x86_64, arm64/Apple Silicon)
+- Windows (x86_64)
+
+For other platforms, the pure Python version is used automatically.
+
+
+Performance Benchmarks
+^^^^^^^^^^^^^^^^^^^^^^
+
+Comprehensive benchmarks comparing Python, Go, and Zig implementations:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 15 15
+
+   * - Test Case
+     - Python (CPython)
+     - Go
+     - Zig
+   * - **Small JSON** (47 bytes)
+     - 68.88ms
+     - 7.13ms
+     - 2.65ms
+   * - **Medium JSON** (2.6 KB)
+     - 73.40ms
+     - 4.85ms
+     - 2.13ms
+   * - **Large JSON** (323 KB)
+     - 420.06ms
+     - 68.88ms
+     - 5.90ms
+   * - **Very Large JSON** (1.6 MB)
+     - 2.08s
+     - 288.75ms
+     - 20.62ms
+
+**Recommendation by Use Case:**
+
+- **Python integration / scripting**: Use this library (json2xml)
+- **CLI tool / moderate performance**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_
+- **Maximum performance / large files**: Use `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_
+
+For detailed benchmarks, see `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_.
+
+
+Other Implementations
+^^^^^^^^^^^^^^^^^^^^^
+
+This library is also available in other languages:
+
+- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 7x faster, native compiled binary
+- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 85x faster, maximum performance
+
+
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

{json2xml-5.4.0 → json2xml-6.0.0}/README.rst

@@ -1,3 +1,7 @@
+.. image:: ./json2xml-hero.png
+   :alt: json2xml hero
+
+
 ========
 json2xml
 ========
@@ -39,6 +43,22 @@ Installation
 
     pip install json2xml
 
+**With Native Rust Acceleration (29x faster)**
+
+For maximum performance, install the optional Rust extension:
+
+.. code-block:: console
+
+    # Install json2xml with Rust acceleration (when published)
+    pip install json2xml[fast]
+    
+    # Or install the Rust extension separately
+    pip install json2xml-rs
+
+The Rust extension provides **29x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
+
+*Note: The ``json2xml-rs`` package will be available on PyPI after the first Rust release.*
+
 **As a CLI Tool**
 
 The library includes a command-line tool ``json2xml-py`` that gets installed automatically:
@@ -281,6 +301,43 @@ Using tools directly:
     ruff check json2xml tests
     mypy json2xml tests
 
+**Rust Extension Development**
+
+The optional Rust extension (``json2xml-rs``) provides 29x faster performance. To develop or build the Rust extension:
+
+Prerequisites:
+
+ .. code-block:: console
+
+    # Install Rust (if not already installed)
+    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+    
+    # Install maturin (Rust-Python build tool)
+    uv pip install maturin
+
+Building the extension:
+
+ .. code-block:: console
+
+    # Development build (installs in current environment)
+    cd rust
+    uv pip install -e .
+    
+    # Or using maturin directly
+    maturin develop --release
+    
+    # Production wheel build
+    maturin build --release
+
+Running Rust benchmarks:
+
+ .. code-block:: console
+
+    # After building the extension
+    python benchmark_rust.py
+
+The Rust code is in ``rust/src/lib.rs`` and uses PyO3 for Python bindings.
+
 
 CLI Usage
 ^^^^^^^^^
@@ -353,6 +410,115 @@ A Go port of this library is available at `json2xml-go <https://github.com/vinit
 The Go version provides the same features and a native compiled binary for maximum performance.
 
 
+Rust Extension (PyO3)
+^^^^^^^^^^^^^^^^^^^^^
+
+For users who need maximum performance within Python, json2xml includes an optional native Rust extension built with PyO3:
+
+.. code-block:: console
+
+    pip install json2xml[fast]
+
+**Rust vs Pure Python Performance:**
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 20 15
+
+   * - Test Case
+     - Pure Python
+     - Rust Extension
+     - Speedup
+   * - **Small JSON** (47 bytes)
+     - 41µs
+     - 1.3µs
+     - **33x**
+   * - **Medium JSON** (3.2 KB)
+     - 2.1ms
+     - 76µs
+     - **28x**
+   * - **Large JSON** (32 KB)
+     - 21.5ms
+     - 727µs
+     - **30x**
+   * - **Very Large JSON** (323 KB)
+     - 215ms
+     - 7.4ms
+     - **29x**
+
+**Usage with Rust Extension:**
+
+.. code-block:: python
+
+    # Automatic backend selection (recommended)
+    from json2xml.dicttoxml_fast import dicttoxml, get_backend
+
+    print(f"Using backend: {get_backend()}")  # 'rust' or 'python'
+    
+    data = {"name": "John", "age": 30}
+    xml_bytes = dicttoxml(data)
+
+The ``dicttoxml_fast`` module automatically uses the Rust backend when available and falls back to pure Python for unsupported features (like ``xpath_format``, ``xml_namespaces``, or custom ``item_func``).
+
+**Platform Support:**
+
+Pre-built wheels are available for:
+
+- Linux (x86_64, aarch64)
+- macOS (x86_64, arm64/Apple Silicon)
+- Windows (x86_64)
+
+For other platforms, the pure Python version is used automatically.
+
+
+Performance Benchmarks
+^^^^^^^^^^^^^^^^^^^^^^
+
+Comprehensive benchmarks comparing Python, Go, and Zig implementations:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 15 15
+
+   * - Test Case
+     - Python (CPython)
+     - Go
+     - Zig
+   * - **Small JSON** (47 bytes)
+     - 68.88ms
+     - 7.13ms
+     - 2.65ms
+   * - **Medium JSON** (2.6 KB)
+     - 73.40ms
+     - 4.85ms
+     - 2.13ms
+   * - **Large JSON** (323 KB)
+     - 420.06ms
+     - 68.88ms
+     - 5.90ms
+   * - **Very Large JSON** (1.6 MB)
+     - 2.08s
+     - 288.75ms
+     - 20.62ms
+
+**Recommendation by Use Case:**
+
+- **Python integration / scripting**: Use this library (json2xml)
+- **CLI tool / moderate performance**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_
+- **Maximum performance / large files**: Use `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_
+
+For detailed benchmarks, see `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_.
+
+
+Other Implementations
+^^^^^^^^^^^^^^^^^^^^^
+
+This library is also available in other languages:
+
+- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 7x faster, native compiled binary
+- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 85x faster, maximum performance
+
+
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

{json2xml-5.4.0 → json2xml-6.0.0}/json2xml/__init__.py

@@ -2,5 +2,5 @@
 
 __author__ = """Vinit Kumar"""
 __email__ = "mail@vinitkumar.me"
-__version__ = "5.4.0"
+__version__ = "6.0.0"
 

{json2xml-5.4.0 → json2xml-6.0.0}/json2xml/cli.py

@@ -367,5 +367,5 @@ def main(argv: list[str] | None = None) -> int:
     return 0
 
 
-if __name__ == "__main__":
+if __name__ == "__main__":  # pragma: no cover
     sys.exit(main())

{json2xml-5.4.0 → json2xml-6.0.0}/json2xml/dicttoxml.py

@@ -50,7 +50,7 @@ def get_unique_id(element: str) -> str:
         if this_id not in ids:
             dup = False
             ids.append(this_id)
-        else:
+        else:  # pragma: no cover
             this_id = make_id(element)
     return ids[-1]