json2xml 6.2.0__tar.gz → 6.4.0__tar.gz

{json2xml-6.2.0 → json2xml-6.4.0}/CONTRIBUTING.rst

@@ -186,7 +186,7 @@ A reminder for the maintainers on how to deploy.
 Make sure all your changes are committed (including an entry in HISTORY.rst).
 Then run::
 
-$ bumpversion patch # possible: major / minor / patch
+Update the version in pyproject.toml and json2xml/__init__.py
 $ git push
 $ git push --tags
 

{json2xml-6.2.0 → json2xml-6.4.0}/HISTORY.rst

@@ -1,4 +1,22 @@
 
+6.4.0 / 2026-07-13
+==================
+
+  * perf: buffer Rust serializer writes in bounded 16 KiB chunks, reducing large-payload conversion time while keeping serializer memory near 80 MiB
+  * chore: release ``json2xml-rs`` 0.4.1 and require it from ``json2xml[fast]`` for accelerated installs
+  * docs: record before-and-after Rust buffering benchmarks and the unchanged XML output size
+
+
+6.3.0 / 2026-06-10
+==================
+
+  * feat: reduce pure Python serializer allocations in hot dict, list, and scalar paths
+  * feat: preserve XML output semantics while reusing validated element-name and attribute work
+  * perf: lower peak memory pressure for large conversions after the 6.2.0 Rust bytes-writer release
+  * docs: add hyperfine Rust memory benchmark notes with reproduction details and the measured throughput tradeoff
+  * chore: release ``json2xml-rs`` 0.4.0 and require it from ``json2xml[fast]`` for accelerated installs
+
+
 6.2.0 / 2026-06-05
 ==================
 

{json2xml-6.2.0 → json2xml-6.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 6.2.0
+Version: 6.4.0
 Summary: Simple Python Library to convert JSON to XML
 Author-email: Vinit Kumar <mail@vinitkumar.me>
 License: Apache Software License 2.0
@@ -32,7 +32,7 @@ Requires-Dist: setuptools; extra == "dev"
 Requires-Dist: pygments>=2.20.0; extra == "dev"
 Requires-Dist: xmltodict>=0.12.0; extra == "dev"
 Provides-Extra: fast
-Requires-Dist: json2xml-rs>=0.3.0; extra == "fast"
+Requires-Dist: json2xml-rs>=0.4.1; extra == "fast"
 Dynamic: license-file
 
 .. image:: ./json2xml-hero.png

{json2xml-6.2.0 → json2xml-6.4.0}/docs/rust_memory_benchmark.rst

@@ -6,7 +6,7 @@ This benchmark compares peak memory usage before and after the Rust serializer s
 Summary
 -------
 
-The current branch reduces serializer peak RSS by about **77.44 MiB** on a 100,000-record payload that produces **78.17 MiB** of XML. That is a **49.1% reduction** in serializer memory delta compared with the previous PR commit.
+The current branch still reduces serializer peak RSS by about **77.43 MiB** on a 100,000-record payload that produces **78.17 MiB** of XML. That is a **49.1% reduction** in serializer memory delta compared with the previous PR commit.
 
 .. list-table::
    :header-rows: 1
@@ -23,10 +23,10 @@ The current branch reduces serializer peak RSS by about **77.44 MiB** on a 100,0
      - 157.70 MiB
      - 0.180s
    * - Current
-     - ``07d840f``
-     - 271.65 MiB
-     - 80.26 MiB
-     - 0.265s
+     - ``43543e8`` + worktree
+     - 270.91 MiB
+     - 80.27 MiB
+     - 0.232s
 
 The memory result matches the implementation change: the previous version held roughly one final XML payload in Rust plus one Python ``bytes`` payload, while the current version writes into the Python ``bytes`` object directly.
 
@@ -36,14 +36,14 @@ Methodology
 The benchmark uses ``benchmark_memory_rust.py`` with a deterministic generated payload so the Rust fast path can be measured without file parsing or pure-Python fallback behavior.
 
 * Machine: Apple Silicon arm64
-* OS: macOS 26.5
+* OS: macOS 26.5.1
 * Python: 3.14.0
 * Build: ``python3 -m maturin develop --release --offline``
 * Payload: 100,000 nested records
 * Input JSON size: 44.31 MiB
 * Output XML size: 78.17 MiB
 * Measurement: process ``ru_maxrss`` after payload creation versus peak after ``json2xml_rs.dicttoxml(payload, attr_type=True)``
-* Sampling: three fresh Python processes per version
+* Sampling: five fresh Python processes for the current version using ``hyperfine 1.20.0 --runs 5 --show-output --export-json``
 
 The baseline RSS is captured after the large Python payload is already built. The reported serializer delta is ``peak_rss - baseline_rss``, which focuses the comparison on output construction rather than payload allocation.
 
@@ -89,11 +89,41 @@ Raw Samples
      - 271.55 MiB
      - 80.30 MiB
      - 0.258s
+   * - current-hyperfine-1
+     - 190.77 MiB
+     - 271.12 MiB
+     - 80.36 MiB
+     - 0.233s
+   * - current-hyperfine-2
+     - 190.66 MiB
+     - 271.02 MiB
+     - 80.36 MiB
+     - 0.234s
+   * - current-hyperfine-3
+     - 190.62 MiB
+     - 270.98 MiB
+     - 80.36 MiB
+     - 0.234s
+   * - current-hyperfine-4
+     - 190.78 MiB
+     - 270.84 MiB
+     - 80.06 MiB
+     - 0.231s
+   * - current-hyperfine-5
+     - 190.38 MiB
+     - 270.61 MiB
+     - 80.23 MiB
+     - 0.229s
+
+Hyperfine Result
+----------------
+
+Hyperfine measured full fresh-process runtime for the current benchmark command at **684.3 ms +/- 26.5 ms** across five runs, with a range of **664.1 ms to 728.0 ms**. The exported hyperfine memory sample was **272.59 MiB**, which is consistent with the script's average peak RSS of **270.91 MiB**.
 
 Tradeoff
 --------
 
-The memory improvement comes with a throughput cost in this release benchmark. Average conversion time increased from 0.180s to 0.265s, about **47.5% slower** for this payload.
+The memory improvement comes with a throughput cost in this release benchmark. Average conversion time increased from the previous 0.180s to the current hyperfine-sampled 0.232s, about **29.0% slower** for this payload.
 
 That cost is likely from routing every XML write through ``std::io::Write`` and PyO3's bytes writer. The memory win is substantial for large outputs, but latency-sensitive callers may want more timing data before treating the bytes-writer path as a universal improvement.
 
@@ -105,6 +135,7 @@ Run each version in a fresh process after installing the desired Rust extension
 .. code-block:: bash
 
    python3 -m maturin develop --release --offline
-   python3 benchmark_memory_rust.py --records 100000 --label current-release-1
+   hyperfine --runs 5 --show-output --export-json /private/tmp/json2xml-rust-memory-hyperfine.json \
+     'python3 benchmark_memory_rust.py --records 100000 --label current-hyperfine'
 
 For the previous comparison, install commit ``7dd86b0`` in a temporary worktree, then run the same command from the main checkout so the benchmark script stays identical.

{json2xml-6.2.0 → json2xml-6.4.0}/json2xml/__init__.py

@@ -2,4 +2,4 @@
 
 __author__ = """Vinit Kumar"""
 __email__ = "mail@vinitkumar.me"
-__version__ = "6.2.0"
+__version__ = "6.4.0"

json2xml-6.4.0/json2xml/backend_selector.py

@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+
+@dataclass(frozen=True, slots=True)
+class ConversionRequest:
+    """Normalized conversion request shared across backend adapters."""
+
+    obj: Any
+    root: bool
+    custom_root: str
+    ids: list[int] | None
+    attr_type: bool
+    item_wrap: bool
+    item_func: Any
+    cdata: bool
+    xml_namespaces: dict[str, Any] | None
+    list_headers: bool
+    xpath_format: bool
+
+
+class BackendAdapter(Protocol):
+    """Small adapter seam for conversion backends."""
+
+    @property
+    def name(self) -> str:
+        raise NotImplementedError  # pragma: no cover
+
+    def can_handle(self, request: ConversionRequest) -> bool:
+        raise NotImplementedError  # pragma: no cover
+
+    def render(self, request: ConversionRequest) -> bytes:
+        raise NotImplementedError  # pragma: no cover
+
+
+class BackendSelector:
+    """Pick the first backend that can preserve request semantics."""
+
+    def __init__(self, *backends: BackendAdapter) -> None:
+        self._backends = backends
+
+    def render(self, request: ConversionRequest) -> bytes:
+        for backend in self._backends:
+            if backend.can_handle(request):
+                return backend.render(request)
+        raise RuntimeError("No XML backend can handle the requested conversion")
+
+
+def has_special_keys(obj: Any) -> bool:
+    """Return True when the payload uses Python-only special key semantics."""
+    if isinstance(obj, dict):
+        return any(
+            (isinstance(key, str) and (key.startswith("@") or key.endswith("@flat")))
+            or has_special_keys(value)
+            for key, value in obj.items()
+        )
+
+    if isinstance(obj, list):
+        return any(has_special_keys(item) for item in obj)
+
+    return False

{json2xml-6.2.0 → json2xml-6.4.0}/json2xml/cli.py

@@ -43,6 +43,7 @@ from __future__ import annotations
 
 import argparse
 import sys
+from dataclasses import dataclass
 from pathlib import Path
 from typing import NoReturn
 
@@ -62,12 +63,142 @@ AUTHOR = "Vinit Kumar"
 EMAIL = "mail@vinitkumar.me"
 
 
+@dataclass(frozen=True, slots=True)
+class CLIConversionOptions:
+    """Parsed CLI options normalized for the conversion workflow."""
+
+    input_file: str | None
+    url: str | None
+    string: str | None
+    output: str | None
+    wrapper: str
+    root: bool
+    pretty: bool
+    attr_type: bool
+    item_wrap: bool
+    xpath_format: bool
+    cdata: bool
+    list_headers: bool
+
+    @classmethod
+    def from_namespace(cls, args: argparse.Namespace) -> "CLIConversionOptions":
+        return cls(
+            input_file=args.input_file,
+            url=args.url,
+            string=args.string,
+            output=args.output,
+            wrapper=args.wrapper,
+            root=args.root,
+            pretty=args.pretty,
+            attr_type=args.attr_type,
+            item_wrap=args.item_wrap,
+            xpath_format=args.xpath_format,
+            cdata=args.cdata,
+            list_headers=args.list_headers,
+        )
+
+
 def exit_with_error(message: str) -> NoReturn:
     """Print an error message and terminate CLI processing."""
     print(message, file=sys.stderr)
     raise SystemExit(1)
 
 
+class CLIApplication:
+    """Thin command adapter around input resolution, conversion, and output."""
+
+    def read_input(self, options: CLIConversionOptions) -> JSONValue:
+        if options.url:
+            try:
+                return readfromurl(options.url)
+            except URLReadError as error:
+                exit_with_error(f"Error reading from URL: {error}")
+
+        if options.string:
+            try:
+                return readfromstring(options.string)
+            except StringReadError as error:
+                exit_with_error(
+                    "Error: Invalid JSON in --string input. "
+                    "Pass a valid JSON object, array, string, number, boolean, or null. "
+                    f"({error})"
+                )
+
+        if options.input_file:
+            if options.input_file == "-":
+                return read_from_stdin()
+            if not Path(options.input_file).is_file():
+                exit_with_error(
+                    f"Error: JSON file not found: {options.input_file}. "
+                    "Check the path or use - to read JSON from stdin."
+                )
+            try:
+                return readfromjson(options.input_file)
+            except JSONReadError as error:
+                exit_with_error(
+                    f"Error: Could not parse JSON file: {options.input_file}. "
+                    f"Check that the file contains valid JSON. ({error})"
+                )
+
+        if not sys.stdin.isatty():
+            return read_from_stdin()
+
+        exit_with_error(
+            "Error: No input provided. Pass a JSON file, use - for stdin, "
+            "or provide --string/--url."
+        )
+        raise AssertionError("unreachable")
+
+    def read_from_stdin(self) -> JSONValue:
+        try:
+            json_str = sys.stdin.read().strip()
+            if not json_str:
+                exit_with_error(
+                    "Error: Empty stdin. Pipe JSON into stdin or pass a file/--string."
+                )
+            return readfromstring(json_str)
+        except StringReadError as error:
+            exit_with_error(
+                "Error: Invalid JSON from stdin. Pipe valid JSON into stdin "
+                f"or pass a file/--string. ({error})"
+            )
+
+    def convert(self, data: JSONValue, options: CLIConversionOptions) -> str | bytes:
+        converter = Json2xml(
+            data=data,
+            wrapper=options.wrapper,
+            root=options.root,
+            pretty=options.pretty,
+            attr_type=options.attr_type,
+            item_wrap=options.item_wrap,
+            xpath_format=options.xpath_format,
+            cdata=options.cdata,
+            list_headers=options.list_headers,
+        )
+        xml_output = converter.to_xml()
+        if xml_output is None:
+            raise ValueError("Empty data, no XML generated")
+        return xml_output
+
+    def write_output(self, output: str | bytes, output_file: str | None) -> None:
+        if isinstance(output, bytes):
+            output = output.decode("utf-8")
+
+        if output_file:
+            try:
+                with open(output_file, "w", encoding="utf-8") as file_obj:
+                    file_obj.write(output)
+            except OSError as error:
+                print(f"Error writing to file: {error}", file=sys.stderr)
+                sys.exit(1)
+            return
+
+        print(output)
+
+
+_APP = CLIApplication()
+
+
 # @lat: [[architecture#CLI entrypoint]]
 def create_parser() -> argparse.ArgumentParser:
     """Create and configure the argument parser."""
@@ -238,153 +369,39 @@ Examples:
 
 
 # @lat: [[behavior#Input readers]]
-def read_input(args: argparse.Namespace) -> JSONValue:
-    """
-    Read JSON input from the specified source.
-
-    Priority: URL > String > File > Stdin
-
-    Args:
-        args: Parsed command line arguments.
-
-    Returns:
-        Parsed JSON data as dict or list.
-
-    Raises:
-        SystemExit: When no input is provided or reading fails.
-    """
-    # Priority: URL > String > File > Stdin
-    if args.url:
-        try:
-            return readfromurl(args.url)
-        except URLReadError as e:
-            exit_with_error(f"Error reading from URL: {e}")
-
-    if args.string:
-        try:
-            return readfromstring(args.string)
-        except StringReadError as e:
-            exit_with_error(
-                "Error: Invalid JSON in --string input. "
-                f"Pass a valid JSON object, array, string, number, boolean, or null. ({e})"
-            )
-
-    if args.input_file:
-        if args.input_file == "-":
-            # Read from stdin
-            return read_from_stdin()
-        if not Path(args.input_file).is_file():
-            exit_with_error(
-                f"Error: JSON file not found: {args.input_file}. "
-                "Check the path or use - to read JSON from stdin."
-            )
-        try:
-            return readfromjson(args.input_file)
-        except JSONReadError as e:
-            exit_with_error(
-                f"Error: Could not parse JSON file: {args.input_file}. "
-                f"Check that the file contains valid JSON. ({e})"
-            )
-
-    # Check if there's data on stdin
-    if not sys.stdin.isatty():
-        return read_from_stdin()
-
-    exit_with_error(
-        "Error: No input provided. Pass a JSON file, use - for stdin, "
-        "or provide --string/--url."
-    )
+def read_input(args: argparse.Namespace | CLIConversionOptions) -> JSONValue:
+    """Read JSON input from the specified source."""
+    options = args if isinstance(args, CLIConversionOptions) else CLIConversionOptions.from_namespace(args)
+    return _APP.read_input(options)
 
 
 def read_from_stdin() -> JSONValue:
-    """
-    Read JSON from standard input.
-
-    Returns:
-        Parsed JSON data.
-
-    Raises:
-        SystemExit: When stdin is empty or contains invalid JSON.
-    """
-    try:
-        json_str = sys.stdin.read().strip()
-        if not json_str:
-            exit_with_error(
-                "Error: Empty stdin. Pipe JSON into stdin or pass a file/--string."
-            )
-        return readfromstring(json_str)
-    except StringReadError as e:
-        exit_with_error(
-            "Error: Invalid JSON from stdin. Pipe valid JSON into stdin "
-            f"or pass a file/--string. ({e})"
-        )
+    """Read JSON from standard input."""
+    return _APP.read_from_stdin()
 
 
 def write_output(output: str | bytes, output_file: str | None) -> None:
-    """
-    Write XML output to the specified destination.
-
-    Args:
-        output: XML content to write.
-        output_file: Path to output file, or None for stdout.
-    """
-    if isinstance(output, bytes):
-        output = output.decode("utf-8")
-
-    if output_file:
-        try:
-            with open(output_file, "w", encoding="utf-8") as f:
-                f.write(output)
-        except OSError as e:
-            print(f"Error writing to file: {e}", file=sys.stderr)
-            sys.exit(1)
-    else:
-        print(output)
+    """Write XML output to the specified destination."""
+    _APP.write_output(output, output_file)
 
 
 def main(argv: list[str] | None = None) -> int:
-    """
-    Main entry point for the CLI.
-
-    Args:
-        argv: Command line arguments (defaults to sys.argv[1:]).
-
-    Returns:
-        Exit code (0 for success, 1 for error).
-    """
+    """Main entry point for the CLI."""
     parser = create_parser()
     args = parser.parse_args(argv)
+    options = CLIConversionOptions.from_namespace(args)
 
-    # Read input data
     try:
-        data = read_input(args)
-    except Exception as e:
-        print(f"Error reading input: {e}", file=sys.stderr)
+        data = read_input(options)
+    except Exception as error:
+        print(f"Error reading input: {error}", file=sys.stderr)
         return 1
 
-    # Convert to XML
     try:
-        converter = Json2xml(
-            data=data,
-            wrapper=args.wrapper,
-            root=args.root,
-            pretty=args.pretty,
-            attr_type=args.attr_type,
-            item_wrap=args.item_wrap,
-            xpath_format=args.xpath_format,
-            cdata=args.cdata,
-            list_headers=args.list_headers,
-        )
-        xml_output = converter.to_xml()
-
-        if xml_output is None:
-            print("Error: Empty data, no XML generated", file=sys.stderr)
-            return 1
-
-        write_output(xml_output, args.output)
-
-    except Exception as e:
-        print(f"Error converting to XML: {e}", file=sys.stderr)
+        xml_output = _APP.convert(data, options)
+        write_output(xml_output, options.output)
+    except Exception as error:
+        print(f"Error converting to XML: {error}", file=sys.stderr)
         return 1
 
     return 0