Feat/update python 3.15

.github/workflows/pythonpackage.yml

@@ -26,13 +26,18 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: [pypy-3.10, pypy-3.11, '3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15.0-beta.2']
+        # Pin PyPy 3.11 to the 7.3.23 build so CI keeps exercising the
+        # CPython 3.11.15-compatible runtime documented in BENCHMARKS.md.
+        python-version: [pypy-3.10, pypy-3.11-v7.3.23, '3.10', '3.11', '3.12', '3.13', '3.14', '3.14t', '3.15.0-beta.3']
         os: [
           ubuntu-latest,
           windows-latest,
           macos-latest,
           "ubuntu-24.04-arm"
         ]
+        exclude:
+          - os: ubuntu-latest
+            python-version: '3.14t'
     steps:
     - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
       with:

.github/workflows/rust-ci.yml

@@ -4,12 +4,20 @@ on:
   push:
     branches: [master, main]
     paths:
+      - 'json2xml/backend_selector.py'
+      - 'json2xml/dicttoxml.py'
+      - 'json2xml/dicttoxml_fast.py'
+      - 'json2xml/json2xml.py'
       - 'rust/**'
       - 'tests/test_rust_dicttoxml.py'
       - '.github/workflows/rust-ci.yml'
   pull_request:
     branches: [master, main]
     paths:
+      - 'json2xml/backend_selector.py'
+      - 'json2xml/dicttoxml.py'
+      - 'json2xml/dicttoxml_fast.py'
+      - 'json2xml/json2xml.py'
       - 'rust/**'
       - 'tests/test_rust_dicttoxml.py'
       - '.github/workflows/rust-ci.yml'

BENCHMARKS.md

@@ -8,7 +8,7 @@ Comprehensive performance comparison between all json2xml implementations.
 - **OS**: macOS 26.5 (Darwin 25.5.0)
 - **Python**: 3.14.4
 - **Date**: May 27, 2026
-- **CLI tools**: `json2xml-go` and `json2xml-zig` from `/Users/vinitkumar/.local/bin`
+- **CLI tools**: `json2xml-go` and `json2xml-zig` on `PATH` (the published run used a local `~/.local/bin` install)
 
 To make new runs comparable, record the same fields for your machine before
 publishing results:
@@ -63,6 +63,34 @@ which json2xml-go json2xml-zig 2>/dev/null || true
 
 *CLI tools have process spawn overhead (~3-6ms) which dominates for small inputs.
 
+### Multi-Python CLI Benchmark (June 25, 2026)
+
+This rerun compares the same CLI workload across uv-managed CPython 3.14.6, CPython 3.15.0b3, PyPy 3.11.15, and `json2xml-go`. The listed environment is the recorded machine for this run, not a requirement for contributors on other platforms.
+
+#### Environment
+
+- **Machine**: Apple Silicon (arm64)
+- **OS**: macOS 26.5.1 (Darwin 25.5.0)
+- **Interpreters**: CPython 3.14.6, CPython 3.15.0b3, PyPy 3.11.15
+- **Date**: June 25, 2026
+- **Go CLI**: `json2xml-go` on `PATH` (the recorded run used a local `~/.local/bin` install)
+
+#### Results
+
+| Test Case | CPython 3.14.6 | CPython 3.15.0b3 | PyPy 3.11.15 | Go |
+|-----------|----------------|------------------|--------------|----|
+| Small (47B) | 61.86ms | 47.61ms | 98.45ms | 4.46ms |
+| Medium (2.6KB) | 62.85ms | 43.41ms | 97.96ms | 4.88ms |
+| Large (323KB, 1K records) | 174.11ms | 146.74ms | 271.24ms | 62.23ms |
+| Very Large (1.62MB, 5K records) | 759.26ms | 691.53ms | 526.96ms | 269.96ms |
+
+#### Takeaways
+
+- **CPython 3.15.0b3 beat CPython 3.14.6 in every test**, from **1.14x faster on average** across the four cases.
+- **PyPy 3.11.15 still lagged on smaller inputs** because startup cost dominates, but it **overtook both CPython builds on the 5K-record case**.
+- **Go remained the fastest CLI path overall**, mainly because the conversion work dominates process startup once the payload gets large.
+- These numbers are **end-to-end subprocess timings**, not isolated serializer throughput, so interpreter startup and environment activation costs are part of the result by design.
+
 ## Key Observations
 
 ### 1. Rust Extension is the Best Choice for Python Users 🦀
@@ -194,10 +222,14 @@ python benchmark_rust.py
 ### Multi-Python Version Benchmark
 
 Creates per-interpreter virtual environments under `.benchmark_venvs/` and
-compares the hard-coded Python paths in `benchmark_multi_python.py`. Edit
-`PYTHON_VERSIONS` in that script or install the listed interpreters before
-running it. Set `JSON2XML_GO_CLI=/path/to/json2xml-go` if the Go binary is not
-named `json2xml-go` on `PATH`.
+compares the configured Python interpreter paths in `benchmark_multi_python.py`.
+By default the script looks for uv-managed CPython 3.14.6, CPython 3.15.0b3,
+and PyPy 3.11.15 under `JSON2XML_UV_PYTHON_DIR` (default:
+`~/.local/share/uv/python`). Override individual interpreter paths with
+`JSON2XML_PYTHON_CPYTHON_314_6`, `JSON2XML_PYTHON_CPYTHON_315_0B3`, or
+`JSON2XML_PYTHON_PYPY_311_15` if your layout differs. Set
+`JSON2XML_GO_CLI=/path/to/json2xml-go` if the Go binary is not named
+`json2xml-go` on `PATH`.
 
 ```bash
 python benchmark_multi_python.py

benchmark_multi_python.py

@@ -3,9 +3,9 @@
 Multi-Python Benchmark: Compare json2xml performance across Python implementations.
 
 Compares:
-- CPython 3.14.2 (homebrew)
-- CPython 3.15.0a4 (latest alpha)
-- PyPy 3.10.16
+- CPython 3.14.6
+- CPython 3.15.0b3
+- PyPy 3.11.15
 - Go (json2xml-go)
 
 Each Python version gets its own virtual environment with json2xml installed.
@@ -24,28 +24,45 @@
 from dataclasses import dataclass
 from pathlib import Path
 
-
 # Configuration
 BASE_DIR = Path(__file__).resolve().parent
 VENVS_DIR = BASE_DIR / ".benchmark_venvs"
 GO_CLI = Path(os.environ.get("JSON2XML_GO_CLI", "json2xml-go"))
+UV_PYTHON_DIR = Path(
+    os.environ.get("JSON2XML_UV_PYTHON_DIR", str(Path.home() / ".local/share/uv/python"))
+)
+
+
+def _uv_python_path(distribution: str, executable: str) -> str:
+    """Build a uv-managed interpreter path from a configurable base directory."""
+    return str(UV_PYTHON_DIR / distribution / "bin" / executable)
+
 
 # Python implementations to benchmark
 PYTHON_VERSIONS = [
     {
-        "name": "CPython 3.14.2",
-        "python": "/opt/homebrew/bin/python3.14",
-        "venv_name": "venv_cpython314_2",
+        "name": "CPython 3.14.6",
+        "python": os.environ.get(
+            "JSON2XML_PYTHON_CPYTHON_314_6",
+            _uv_python_path("cpython-3.14.6-macos-aarch64-none", "python3.14"),
+        ),
+        "venv_name": "venv_cpython314_6",
     },
     {
-        "name": "CPython 3.15.0a4",
-        "python": str(Path.home() / ".local/share/uv/python/cpython-3.15.0a4-macos-aarch64-none/bin/python3.15"),
-        "venv_name": "venv_cpython315a4",
+        "name": "CPython 3.15.0b3",
+        "python": os.environ.get(
+            "JSON2XML_PYTHON_CPYTHON_315_0B3",
+            _uv_python_path("cpython-3.15.0b3-macos-aarch64-none", "python3.15"),
+        ),
+        "venv_name": "venv_cpython315b3",
     },
     {
-        "name": "PyPy 3.10.16",
-        "python": str(Path.home() / ".local/share/uv/python/pypy-3.10.19-macos-aarch64-none/bin/pypy3.10"),
-        "venv_name": "venv_pypy310",
+        "name": "PyPy 3.11.15",
+        "python": os.environ.get(
+            "JSON2XML_PYTHON_PYPY_311_15",
+            _uv_python_path("pypy-3.11.15-macos-aarch64-none", "pypy3.11"),
+        ),
+        "venv_name": "venv_pypy311",
     },
 ]
 
@@ -129,7 +146,7 @@ def setup_venv(python_path: str, venv_path: Path) -> bool:
             return False
 
         # Install json2xml in the venv
-        print(f"  Installing json2xml...")
+        print("  Installing json2xml...")
         pip_path = venv_path / "bin" / "pip"
         result = subprocess.run(
             [str(pip_path), "install", "-e", str(BASE_DIR), "-q"],
@@ -276,7 +293,7 @@ def main() -> int:
         print(f"  Go (json2xml-go): {colorize('✓', Colors.GREEN)} Ready")
     else:
         print(f"  Go (json2xml-go): {colorize('✗', Colors.RED)} Not found at {GO_CLI}")
-        print(f"    Set JSON2XML_GO_CLI env var or ensure json2xml-go is in PATH")
+        print("    Set JSON2XML_GO_CLI env var or ensure json2xml-go is in PATH")
     print()
 
     if not active_pythons:
@@ -377,10 +394,10 @@ def main() -> int:
                     avg_times[name].append(result.avg_ms)
 
         # Print summary table
-        print(f"  {'Implementation':<35} {'Avg Time':>12} {'vs CPython 3.14.2':>20}")
+        print(f"  {'Implementation':<35} {'Avg Time':>12} {'vs CPython 3.14.6':>20}")
         print(f"  {'-' * 35} {'-' * 12} {'-' * 20}")
 
-        baseline_name = "CPython 3.14.2"
+        baseline_name = "CPython 3.14.6"
         baseline_avg = sum(avg_times.get(baseline_name, [0])) / len(avg_times.get(baseline_name, [1]))
 
         sorted_impls = sorted(avg_times.items(), key=lambda x: sum(x[1]) / len(x[1]))

json2xml/backend_selector.py

@@ -0,0 +1,64 @@
+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."""
+
+    name: str
+
+    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):
+        for key, value in obj.items():
+            if isinstance(key, str) and (key.startswith("@") or key.endswith("@flat")):
+                return True
+            if has_special_keys(value):
+                return True
+        return False
+
+    if isinstance(obj, list):
+        for item in obj:
+            if has_special_keys(item):
+                return True
+
+    return False