json2xml 5.3.1__tar.gz → 6.0.0__tar.gz

{json2xml-5.3.1 → 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.3.1 → json2xml-6.0.0}/HISTORY.rst

@@ -1,7 +1,75 @@
 History
 =======
 
-5.3.0 / 2025-12-08
+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
+==================
+
+  * test: add comprehensive CLI tests for 99% coverage
+  * docs: add CLI usage and cross-reference to Go version
+  * feat: add CLI support for json2xml-py (#266)
+  * chore(deps): bump urllib3 from 2.6.0 to 2.6.3 in /docs (#265)
+  * update documentation and make it more correct (#263)
+  * feat: update doc packages
+  * chore: update GitHub Actions to latest versions (#262)
+  * chore(deps): bump urllib3 from 2.5.0 to 2.6.0 in /docs (#261)
+  * feat: update python3.15.0 to alpha 3 (#260)
+  * feat: bump to match the version
+  * feat: add xPath support (#259)
+  * chore(deps): bump starlette from 0.47.2 to 0.49.1 in /docs (#257)
+  * feat: improvements to ruff and new python 3.15 (#255)
+  * Modernize Python code to 3.10+ with pyupgrade (#254)
+  * check arm build ubuntu (#253)
+  * Remove duplicate typecheck job from pythonpackage workflow
+  * Migrate from mypy to ty for type checking (#252)
+  * Add Python 3.14t (freethreaded) to testing matrix (#251)
+  * prod release (#249)
+  * bump python to latest rc2
+  * fix: switch to release candidate 2 of Python 3.14
+
+
+5.3.1 / 2025-12-08
 ==================
 
   * chore: bump version

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 5.3.1
+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
 ========
@@ -55,6 +59,8 @@ Documentation: https://json2xml.readthedocs.io.
 
 The library was initially dependent on the `dict2xml` project, but it has now been integrated into json2xml itself. This has led to cleaner code, the addition of types and tests, and overall improved performance.
 
+**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.
+
 
 
 Architecture Diagram
@@ -63,6 +69,46 @@ Architecture Diagram
 .. image:: ./diagram.png
 
 
+Installation
+^^^^^^^^^^^^
+
+**As a Library**
+
+.. code-block:: console
+
+    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:
+
+.. code-block:: console
+
+    pip install json2xml
+
+    # Now you can use it from the command line
+    json2xml-py data.json
+    json2xml-py -s '{"name": "John", "age": 30}'
+    json2xml-py -u https://api.example.com/data.json
+
+For CLI options, run ``json2xml-py --help``.
+
 Features
 ^^^^^^^^
 
@@ -72,6 +118,7 @@ json2xml supports the following features:
 * Conversion from a `json` file to XML
 * Conversion from an API that emits `json` data to XML
 * Compliant with the `json-to-xml` function specification from `XPath 3.1 <https://www.w3.org/TR/xpath-functions-31/#func-json-to-xml>`_
+* **Command-line tool** for easy conversion from the terminal
 
 Usage
 ^^^^^
@@ -289,6 +336,223 @@ 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
+^^^^^^^^^
+
+The ``json2xml-py`` command-line tool provides an easy way to convert JSON to XML from the terminal.
+
+**Basic Examples**
+
+.. code-block:: console
+
+    # Convert a JSON file to XML
+    json2xml-py data.json
+
+    # Convert with custom wrapper element
+    json2xml-py -w root data.json
+
+    # Read JSON from string
+    json2xml-py -s '{"name": "John", "age": 30}'
+
+    # Read from stdin
+    cat data.json | json2xml-py -
+
+    # Output to file
+    json2xml-py -o output.xml data.json
+
+    # Use XPath 3.1 format
+    json2xml-py -x data.json
+
+    # Disable pretty printing and type attributes
+    json2xml-py --no-pretty --no-type data.json
+
+**CLI Options**
+
+.. code-block:: text
+
+    Input Options:
+      -u, --url string        Read JSON from URL
+      -s, --string string     Read JSON from string
+      [input-file]            Read JSON from file (use - for stdin)
+
+    Output Options:
+      -o, --output string     Output file (default: stdout)
+
+    Conversion Options:
+      -w, --wrapper string    Wrapper element name (default "all")
+      -r, --root              Include root element (default true)
+      -p, --pretty            Pretty print output (default true)
+      -t, --type              Include type attributes (default true)
+      -i, --item-wrap         Wrap list items in <item> elements (default true)
+      -x, --xpath             Use XPath 3.1 json-to-xml format
+      -c, --cdata             Wrap string values in CDATA sections
+      -l, --list-headers      Repeat headers for each list item
+
+    Other Options:
+      -v, --version           Show version information
+      -h, --help              Show help message
+
+
+Go Version
+^^^^^^^^^^
+
+A Go port of this library is available at `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_.
+
+**Install the Go CLI:**
+
+.. code-block:: console
+
+    go install github.com/vinitkumar/json2xml-go/cmd/json2xml@latest
+
+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
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^