From 4e889234e4389f9504c402f6cff33d7c0ec0d807 Mon Sep 17 00:00:00 2001 From: Vinit Kumar Date: Tue, 28 Apr 2026 19:04:54 +0530 Subject: [PATCH 1/4] Improve README positioning for json2xml --- README.rst | 89 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 87 insertions(+), 2 deletions(-) diff --git a/README.rst b/README.rst index 09e5500..0f0a12a 100644 --- a/README.rst +++ b/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,92 @@ The library was initially dependent on the `dict2xml` project, but it has now be **Looking for a Go version?** Check out `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] + +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 `_ 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 `_ for more detail. + Architecture Diagram @@ -538,4 +624,3 @@ Help and Support to maintain this project ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - You can sponsor my work for this plugin here: https://github.com/sponsors/vinitkumar/ - From 748564988f83c070a98924403601c46c44a3bfff Mon Sep 17 00:00:00 2001 From: Vinit Kumar Date: Tue, 28 Apr 2026 19:05:12 +0530 Subject: [PATCH 2/4] Add public roadmap for json2xml --- ROADMAP.md | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) create mode 100644 ROADMAP.md diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..153972e --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,60 @@ +# json2xml Roadmap + +json2xml is a small, practical JSON-to-XML toolkit for Python users, CLI workflows, and performance experiments across native implementations. + +This roadmap keeps the project direction visible for users and contributors. + +## Current Focus + +- Make the README and examples easier for new users to scan. +- Keep the Python API stable while improving typed, tested behavior. +- Maintain the Rust acceleration path as the fastest option for Python callers. +- Keep Python, Rust, Go, and Zig benchmark results reproducible. + +## Near-Term Work + +### Documentation and Examples + +- Add examples for converting API responses, local files, stdin, and string payloads. +- Document the differences between pure Python, Rust extension, Go CLI, and Zig CLI usage. +- Add a short "choose the right implementation" guide. +- Expand troubleshooting docs for installation and native wheel fallback. + +### CLI Experience + +- Improve error messages for invalid JSON, missing input, and unsupported option combinations. +- Add more CLI examples for shell pipelines and output files. +- Confirm behavior is consistent across macOS, Linux, and Windows. + +### Performance and Benchmarks + +- Keep `BENCHMARKS.md` updated when benchmark scripts or implementation details change. +- Add benchmark notes that explain process startup overhead for CLI tools. +- Add larger input fixtures that reflect real integration workloads. +- Make it easy for contributors to reproduce benchmark runs locally. + +### Rust Extension + +- Continue improving fallback behavior when native support is unavailable. +- Add tests for unsupported or partially supported conversion features. +- Keep PyO3 and packaging configuration current. +- Verify wheels across supported Python and platform versions. + +## Good First Issues + +These are intentionally small and useful: + +- Add one new README example for a real-world JSON shape. +- Add a regression test for a documented conversion option. +- Improve one CLI help message or error case. +- Add a short benchmark reproduction note. +- Clarify one section of `CONTRIBUTING.rst`. + +## Larger Ideas + +- Streaming support for very large JSON inputs. +- More explicit XML namespace handling examples. +- Better comparison docs against adjacent JSON-to-XML tools. +- A small gallery of before/after JSON and XML examples. + +If you want to help, open an issue with a focused proposal or pick an existing issue labeled `good first issue`, `help wanted`, `docs`, `cli`, or `performance`. From 933ef1bbe59f0ebe0cfbb0fb31f0fb66d8787f83 Mon Sep 17 00:00:00 2001 From: Vinit Kumar Date: Tue, 28 Apr 2026 19:05:27 +0530 Subject: [PATCH 3/4] Clarify json2xml contribution entry points --- CONTRIBUTING.rst | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 1fe4406..a8c18af 100644 --- a/CONTRIBUTING.rst +++ b/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** From 08a2b10988b7e055f822468321ad6ad6dca4d336 Mon Sep 17 00:00:00 2001 From: Vinit Kumar Date: Tue, 28 Apr 2026 19:22:50 +0530 Subject: [PATCH 4/4] fix: overshadow of the variable --- tests/test_utils.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/test_utils.py b/tests/test_utils.py index c5ae230..a33fc07 100644 --- a/tests/test_utils.py +++ b/tests/test_utils.py @@ -31,7 +31,7 @@ class JsonTestHandler(BaseHTTPRequestHandler): """Tiny HTTP handler for exercising the real URL reader.""" - responses: ClassVar[dict[str, tuple[int, bytes]]] = { + json_responses: ClassVar[dict[str, tuple[int, bytes]]] = { "/data.json": (200, b'{"key": "value", "number": 42}'), "/api": (200, b'{"result": "success"}'), "/invalid.json": (200, b"invalid json content"), @@ -41,7 +41,7 @@ class JsonTestHandler(BaseHTTPRequestHandler): def do_GET(self) -> None: path = self.path.split("?", 1)[0] - status, body = self.responses.get(path, (404, b'{"error": "not found"}')) + status, body = self.json_responses.get(path, (404, b'{"error": "not found"}')) self.send_response(status) self.send_header("Content-Type", "application/json") self.send_header("Content-Length", str(len(body)))