json2xml 6.3.0__tar.gz → 6.5.0__tar.gz

{json2xml-6.3.0 → json2xml-6.5.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.3.0 → json2xml-6.5.0}/HISTORY.rst

@@ -1,4 +1,23 @@
 
+6.5.0 / 2026-07-15
+==================
+
+  * perf: reduce pure Python serializer time by 31.1% on the deterministic 5,000-record benchmark through exact native-type dispatch
+  * perf: release ``json2xml-rs`` 0.4.2 with hybrid SIMD/word XML escape scanning and a 6.23% benchmark reduction
+  * fix: preserve numeric, string, dictionary, and sequence subclass behavior across the optimized Python dispatch paths
+  * test: require exactly 100% statement coverage from the complete Python suite and add dense Rust XML escape scanning regression coverage
+  * chore: require ``json2xml-rs>=0.4.2`` from ``json2xml[fast]`` and validate release wheels before PyPI publication
+  * docs: add Python and Rust before/after flamegraphs, buffer-capacity measurements, and release performance notes
+
+
+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
 ==================
 

{json2xml-6.3.0 → json2xml-6.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: json2xml
-Version: 6.3.0
+Version: 6.5.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.4.0; extra == "fast"
+Requires-Dist: json2xml-rs>=0.4.2; extra == "fast"
 Dynamic: license-file
 
 .. image:: ./json2xml-hero.png

{json2xml-6.3.0 → json2xml-6.5.0}/json2xml/__init__.py

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

json2xml-6.5.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.3.0 → json2xml-6.5.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