Skip to content

Commit 0503ee0

Browse files
committed
docs: update README with comprehensive benchmark results
- Update Rust extension benchmark numbers (28x speedup) - Add comparative table: Python vs Rust vs Go vs Zig - Update recommendations based on actual benchmark data - Remove outdated "will be available on PyPI" note (json2xml-rs is live)
1 parent be3c7ef commit 0503ee0

File tree

1 file changed

+55
-40
lines changed

1 file changed

+55
-40
lines changed

README.rst

Lines changed: 55 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -43,21 +43,19 @@ Installation
4343
4444
pip install json2xml
4545
46-
**With Native Rust Acceleration (29x faster)**
46+
**With Native Rust Acceleration (28x faster)**
4747

4848
For maximum performance, install the optional Rust extension:
4949

5050
.. code-block:: console
5151
52-
# Install json2xml with Rust acceleration (when published)
52+
# Install json2xml with Rust acceleration
5353
pip install json2xml[fast]
5454
5555
# Or install the Rust extension separately
5656
pip install json2xml-rs
5757
58-
The Rust extension provides **29x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
59-
60-
*Note: The ``json2xml-rs`` package will be available on PyPI after the first Rust release.*
58+
The Rust extension provides **28x faster** conversion compared to pure Python. It's automatically used when available, with seamless fallback to pure Python.
6159

6260
**As a CLI Tool**
6361

@@ -430,21 +428,21 @@ For users who need maximum performance within Python, json2xml includes an optio
430428
- Rust Extension
431429
- Speedup
432430
* - **Small JSON** (47 bytes)
433-
- 41µs
434-
- 1.3µs
435-
- **33x**
431+
- 40µs
432+
- 1.5µs
433+
- **27x**
436434
* - **Medium JSON** (3.2 KB)
437435
- 2.1ms
438-
- 76µs
439-
- **28x**
440-
* - **Large JSON** (32 KB)
441-
- 21.5ms
442-
- 727µs
436+
- 71µs
443437
- **30x**
438+
* - **Large JSON** (32 KB)
439+
- 21ms
440+
- 740µs
441+
- **28x**
444442
* - **Very Large JSON** (323 KB)
445-
- 215ms
446-
- 7.4ms
447-
- **29x**
443+
- 213ms
444+
- 7.5ms
445+
- **28x**
448446

449447
**Usage with Rust Extension:**
450448

@@ -474,38 +472,54 @@ For other platforms, the pure Python version is used automatically.
474472
Performance Benchmarks
475473
^^^^^^^^^^^^^^^^^^^^^^
476474

477-
Comprehensive benchmarks comparing Python, Go, and Zig implementations:
475+
Comprehensive benchmarks comparing all implementations (Apple Silicon, January 2026):
478476

479477
.. list-table::
480478
:header-rows: 1
481-
:widths: 25 20 15 15
479+
:widths: 22 18 15 15 15 15
482480

483481
* - Test Case
484-
- Python (CPython)
482+
- Python
483+
- Rust
485484
- Go
486485
- Zig
487-
* - **Small JSON** (47 bytes)
488-
- 68.88ms
489-
- 7.13ms
490-
- 2.65ms
491-
* - **Medium JSON** (2.6 KB)
492-
- 73.40ms
493-
- 4.85ms
494-
- 2.13ms
495-
* - **Large JSON** (323 KB)
496-
- 420.06ms
497-
- 68.88ms
498-
- 5.90ms
499-
* - **Very Large JSON** (1.6 MB)
500-
- 2.08s
501-
- 288.75ms
502-
- 20.62ms
486+
- Best
487+
* - **Small** (47B)
488+
- 40µs
489+
- 1.5µs
490+
- 4.6ms
491+
- 3.7ms
492+
- Rust (28x)
493+
* - **Medium** (3.2KB)
494+
- 2.1ms
495+
- 71µs
496+
- 4.1ms
497+
- 3.3ms
498+
- Rust (30x)
499+
* - **Large** (32KB)
500+
- 21ms
501+
- 740µs
502+
- 4ms
503+
- 6.1ms
504+
- Rust (28x)
505+
* - **Very Large** (323KB)
506+
- 213ms
507+
- 7.5ms
508+
- 4.4ms
509+
- 33ms
510+
- Go (48x)
511+
512+
**Key Findings:**
513+
514+
- **Rust extension**: ~28x faster than Python, zero overhead (best for Python users)
515+
- **Go CLI**: 48x faster for large files (300KB+), but has ~4ms startup overhead
516+
- **Zig CLI**: 3-6x faster for medium-large files
503517

504518
**Recommendation by Use Case:**
505519

506-
- **Python integration / scripting**: Use this library (json2xml)
507-
- **CLI tool / moderate performance**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_
508-
- **Maximum performance / large files**: Use `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_
520+
- **Python library calls**: Use ``pip install json2xml[fast]`` (Rust, 28x faster)
521+
- **Large file CLI processing**: Use `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ (Go, 48x for 300KB+)
522+
- **Pure Python required**: Use ``pip install json2xml``
509523

510524
For detailed benchmarks, see `BENCHMARKS.md <https://github.com/vinitkumar/json2xml/blob/master/BENCHMARKS.md>`_.
511525

@@ -515,8 +529,9 @@ Other Implementations
515529

516530
This library is also available in other languages:
517531

518-
- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 7x faster, native compiled binary
519-
- **Zig**: `json2xml-zig <https://github.com/vinitkumar/json2xml-zig>`_ - 85x faster, maximum performance
532+
- **Rust**: `json2xml-rs <https://pypi.org/project/json2xml-rs/>`_ - 28x faster, Python extension via PyO3
533+
- **Go**: `json2xml-go <https://github.com/vinitkumar/json2xml-go>`_ - 48x faster for large files, native CLI
534+
- **Zig**: `json2xml-zig <https://github.com/nicholasgriffintn/json2xml-zig>`_ - 6x faster, native CLI
520535

521536

522537
Help and Support to maintain this project

0 commit comments

Comments
 (0)