json2xml 5.3.1__tar.gz → 5.4.0__tar.gz

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

@@ -1,7 +1,33 @@
 History
 =======
 
-5.3.0 / 2025-12-08
+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-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 5.3.1
+Version: 5.4.0
 Summary: Simple Python Library to convert JSON to XML
 Author-email: Vinit Kumar <mail@vinitkumar.me>
 License: Apache Software License 2.0
@@ -55,6 +55,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 +65,30 @@ Architecture Diagram
 .. image:: ./diagram.png
 
 
+Installation
+^^^^^^^^^^^^
+
+**As a Library**
+
+.. code-block:: console
+
+    pip install json2xml
+
+**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 +98,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
 ^^^^^
@@ -290,6 +317,77 @@ Using tools directly:
     mypy json2xml tests
 
 
+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.
+
+
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

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

@@ -20,6 +20,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
@@ -28,6 +30,30 @@ Architecture Diagram
 .. image:: ./diagram.png
 
 
+Installation
+^^^^^^^^^^^^
+
+**As a Library**
+
+.. code-block:: console
+
+    pip install json2xml
+
+**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
 ^^^^^^^^
 
@@ -37,6 +63,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
 ^^^^^
@@ -255,6 +282,77 @@ Using tools directly:
     mypy json2xml tests
 
 
+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.
+
+
 Help and Support to maintain this project
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

json2xml-5.4.0/docs/benchmarks.rst

@@ -0,0 +1,221 @@
+Benchmarks
+==========
+
+Comprehensive performance comparison between Python implementations and the Go version of json2xml.
+
+Test Environment
+----------------
+
+* **Machine**: Apple Silicon (aarch64)
+* **OS**: macOS
+* **Date**: January 14, 2026
+
+Implementations Tested
+~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 20 50
+
+   * - Implementation
+     - Version
+     - Notes
+   * - CPython
+     - 3.14.2
+     - Homebrew installation
+   * - CPython
+     - 3.15.0a4
+     - Latest alpha via uv
+   * - PyPy
+     - 3.10.16
+     - JIT-compiled Python
+   * - Go
+     - 1.0.0
+     - json2xml-go
+
+Test Data
+~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 20 50 30
+
+   * - Size
+     - Description
+     - Bytes
+   * - Small
+     - Simple object ``{"name": "John", "age": 30, "city": "New York"}``
+     - 47
+   * - Medium
+     - ``bigexample.json`` (patent data)
+     - 2,598
+   * - Large
+     - 1,000 generated records with nested structures
+     - 323,130
+   * - Very Large
+     - 5,000 generated records with nested structures
+     - 1,619,991
+
+Results
+-------
+
+Individual Test Results
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 25 20 20 20 15
+
+   * - Test
+     - CPython 3.14.2
+     - CPython 3.15.0a4
+     - PyPy 3.10.16
+     - Go
+   * - **Small JSON** (47 bytes)
+     - 75.46ms
+     - 55.74ms (1.4x faster)
+     - 121.47ms (1.6x slower)
+     - 3.69ms (20.4x faster)
+   * - **Medium JSON** (2.6KB)
+     - 73.87ms
+     - 57.98ms (1.3x faster)
+     - 125.73ms (1.7x slower)
+     - 4.32ms (17.1x faster)
+   * - **Large JSON** (323KB)
+     - 419.67ms
+     - 328.98ms (1.3x faster)
+     - 517.51ms (1.2x slower)
+     - 67.13ms (6.3x faster)
+   * - **Very Large JSON** (1.6MB)
+     - 2.09s
+     - 1.86s (1.1x faster)
+     - 1.42s (1.5x faster)
+     - 287.58ms (7.3x faster)
+
+Summary (Average Across All Tests)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 40 30 30
+
+   * - Implementation
+     - Avg Time
+     - vs CPython 3.14.2
+   * - **Go**
+     - 90.68ms
+     - **7.34x faster** 🚀
+   * - **PyPy 3.10.16**
+     - 545.58ms
+     - **1.22x faster**
+   * - **CPython 3.15.0a4**
+     - 575.45ms
+     - **1.16x faster**
+   * - **CPython 3.14.2**
+     - 665.23ms
+     - baseline
+
+Key Observations
+----------------
+
+1. Go is the Clear Winner
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Go outperforms all Python implementations by a significant margin:
+
+* **7.34x faster** than CPython 3.14.2 on average
+* Up to **20x faster** for small inputs due to minimal startup overhead
+* Consistent performance across all input sizes
+
+2. CPython 3.15.0a4 Shows Promising Improvements
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The latest Python alpha demonstrates consistent performance gains:
+
+* **13-35% faster** than CPython 3.14.2 across all test sizes
+* Improvements likely due to ongoing interpreter optimizations
+
+3. PyPy Has Interesting Trade-offs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+PyPy's JIT compiler creates a unique performance profile:
+
+* **Slower for small/medium inputs**: JIT compilation overhead hurts for quick operations
+* **Faster for very large inputs**: JIT shines on the 5K record test (1.5x faster than CPython)
+* Best suited for long-running processes or batch processing
+
+4. Startup Overhead Dominates Small Inputs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python's interpreter startup time is significant:
+
+* CPython takes **55-75ms** even for 47 bytes of JSON
+* Go takes only **3.7ms** for the same operation
+* For CLI tools processing small files, Go provides a much better user experience
+
+When to Use Each Implementation
+-------------------------------
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Use Case
+     - Recommended
+   * - CLI tool for small/medium files
+     - **Go** (json2xml-go)
+   * - High-throughput batch processing
+     - **Go** or **PyPy**
+   * - Integration with Python codebase
+     - **CPython 3.15+**
+   * - One-off conversions in scripts
+     - **CPython** (any version)
+
+Running the Benchmarks
+----------------------
+
+Python Multi-Implementation Benchmark
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Set the Go CLI path
+   export JSON2XML_GO_CLI=/path/to/json2xml-go
+
+   # Run the benchmark
+   python benchmark_multi_python.py
+
+Simple Python vs Go Benchmark
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: bash
+
+   # Set paths via environment variables (optional)
+   export JSON2XML_GO_CLI=/path/to/json2xml-go
+   export JSON2XML_EXAMPLES_DIR=/path/to/examples
+
+   # Run the benchmark
+   python benchmark.py
+
+Reproducing Results
+-------------------
+
+1. Install required Python versions using ``uv``:
+
+   .. code-block:: bash
+
+      uv python install 3.14 3.15.0a4 pypy@3.10
+
+2. Build the Go binary:
+
+   .. code-block:: bash
+
+      cd /path/to/json2xml-go
+      go build -o json2xml-go ./cmd/json2xml-go
+
+3. Run the multi-Python benchmark:
+
+   .. code-block:: bash
+
+      cd /path/to/json2xml
+      python benchmark_multi_python.py

{json2xml-5.3.1 → json2xml-5.4.0}/docs/index.rst

@@ -8,6 +8,7 @@ Welcome to json2xml's documentation!
    readme
    installation
    usage
+   benchmarks
    modules
    contributing
    authors

{json2xml-5.3.1 → json2xml-5.4.0}/docs/installation.rst

@@ -23,6 +23,18 @@ you through the process.
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
 
+Using uv (recommended)
+----------------------
+
+`uv`_ is a fast Python package installer. You can install json2xml using:
+
+.. code-block:: console
+
+    $ uv pip install json2xml
+
+.. _uv: https://github.com/astral-sh/uv
+
+
 From sources
 ------------
 
@@ -38,13 +50,44 @@ Or download the `tarball`_:
 
 .. code-block:: console
 
-    $ curl  -OL https://github.com/vinitkumar/json2xml/tarball/master
+    $ curl -OL https://github.com/vinitkumar/json2xml/tarball/master
 
 Once you have a copy of the source, you can install it with:
 
 .. code-block:: console
 
-    $ python setup.py install
+    $ pip install .
+
+Or for development (editable install):
+
+.. code-block:: console
+
+    $ pip install -e .
+
+
+Development Setup
+-----------------
+
+For contributing to json2xml, set up a development environment:
+
+.. code-block:: console
+
+    # Create and activate virtual environment (using uv - recommended)
+    $ uv venv
+    $ source .venv/bin/activate  # On Windows: .venv\Scripts\activate
+
+    # Install dependencies
+    $ uv pip install -r requirements-dev.txt
+    $ uv pip install -e .
+
+
+Requirements
+------------
+
+json2xml requires Python 3.10 or later and depends on:
+
+* ``defusedxml`` - For secure XML parsing
+* ``urllib3`` - For fetching JSON from URLs
 
 
 .. _Github repo: https://github.com/vinitkumar/json2xml