polyxml 0.5.0__tar.gz → 0.6.0__tar.gz

{polyxml-0.5.0 → polyxml-0.6.0}/Cargo.lock

@@ -395,7 +395,7 @@ dependencies = [
 
 [[package]]
 name = "polyxml"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "criterion",
  "lexical-core",
@@ -408,14 +408,14 @@ dependencies = [
 
 [[package]]
 name = "polyxml-c"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "polyxml",
 ]
 
 [[package]]
 name = "polyxml-js"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "napi",
  "napi-build",
@@ -425,7 +425,7 @@ dependencies = [
 
 [[package]]
 name = "polyxml-python"
-version = "0.5.0"
+version = "0.6.0"
 dependencies = [
  "lexical-core",
  "polyxml",

{polyxml-0.5.0 → polyxml-0.6.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/polyxml-core", "crates/polyxml-python"]
 
 [workspace.package]
-version = "0.5.0"
+version = "0.6.0"
 edition = "2021"
 rust-version = "1.80"
 license = "MIT"

{polyxml-0.5.0 → polyxml-0.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyxml
-Version: 0.5.0
+Version: 0.6.0
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -34,5 +34,34 @@ Project-URL: Repository, https://github.com/nth-bailey/PolyXML
 
 High-performance native XML data-binding engine for Python dataclasses and Pydantic models.
 
-Powered by polyxml-core written in Rust and PyO3 (abi3-py312).
+Powered by `polyxml-core` written in Rust and PyO3 (`abi3-py312`).
+
+## Features
+
+- **⚡ Blazing Fast**: 16x faster deserialization and 38x faster serialization than standard Python tools.
+- **🌊 Streaming `iterparse()`**: Parse multi-gigabyte XML files with O(1) constant memory (<5 MB RAM).
+- **📦 Zero-GIL Binary Serialization**: Native `dumps_binary()` and `loads_binary()` using MessagePack (`msgspec`), up to 12.4x faster than pickle.
+- **🎯 Full Type Support**: Dataclasses and Pydantic v2 models with zero boilerplate.
+
+## Quickstart
+
+```python
+from dataclasses import dataclass, field
+import polyxml
+
+@dataclass
+class Item:
+    id: int = field(metadata={"type": "Attribute"})
+    name: str = field(metadata={"type": "Element"})
+
+# 1. XML Deserialization
+item = polyxml.deserialize(b'<Item id="1"><name>Gadget</name></Item>', Item)
+
+# 2. XML Serialization
+xml = polyxml.serialize(item, indent=2)
+
+# 3. High-Speed Binary Serialization (Key-Value databases / IPC)
+blob = polyxml.dumps_binary(item)
+restored = polyxml.loads_binary(blob, Item)
+```
 

polyxml-0.6.0/README.md

@@ -0,0 +1,34 @@
+# PolyXML Python Bindings
+
+High-performance native XML data-binding engine for Python dataclasses and Pydantic models.
+
+Powered by `polyxml-core` written in Rust and PyO3 (`abi3-py312`).
+
+## Features
+
+- **⚡ Blazing Fast**: 16x faster deserialization and 38x faster serialization than standard Python tools.
+- **🌊 Streaming `iterparse()`**: Parse multi-gigabyte XML files with O(1) constant memory (<5 MB RAM).
+- **📦 Zero-GIL Binary Serialization**: Native `dumps_binary()` and `loads_binary()` using MessagePack (`msgspec`), up to 12.4x faster than pickle.
+- **🎯 Full Type Support**: Dataclasses and Pydantic v2 models with zero boilerplate.
+
+## Quickstart
+
+```python
+from dataclasses import dataclass, field
+import polyxml
+
+@dataclass
+class Item:
+    id: int = field(metadata={"type": "Attribute"})
+    name: str = field(metadata={"type": "Element"})
+
+# 1. XML Deserialization
+item = polyxml.deserialize(b'<Item id="1"><name>Gadget</name></Item>', Item)
+
+# 2. XML Serialization
+xml = polyxml.serialize(item, indent=2)
+
+# 3. High-Speed Binary Serialization (Key-Value databases / IPC)
+blob = polyxml.dumps_binary(item)
+restored = polyxml.loads_binary(blob, Item)
+```

polyxml-0.6.0/crates/polyxml-python/README.md

@@ -0,0 +1,34 @@
+# PolyXML Python Bindings
+
+High-performance native XML data-binding engine for Python dataclasses and Pydantic models.
+
+Powered by `polyxml-core` written in Rust and PyO3 (`abi3-py312`).
+
+## Features
+
+- **⚡ Blazing Fast**: 16x faster deserialization and 38x faster serialization than standard Python tools.
+- **🌊 Streaming `iterparse()`**: Parse multi-gigabyte XML files with O(1) constant memory (<5 MB RAM).
+- **📦 Zero-GIL Binary Serialization**: Native `dumps_binary()` and `loads_binary()` using MessagePack (`msgspec`), up to 12.4x faster than pickle.
+- **🎯 Full Type Support**: Dataclasses and Pydantic v2 models with zero boilerplate.
+
+## Quickstart
+
+```python
+from dataclasses import dataclass, field
+import polyxml
+
+@dataclass
+class Item:
+    id: int = field(metadata={"type": "Attribute"})
+    name: str = field(metadata={"type": "Element"})
+
+# 1. XML Deserialization
+item = polyxml.deserialize(b'<Item id="1"><name>Gadget</name></Item>', Item)
+
+# 2. XML Serialization
+xml = polyxml.serialize(item, indent=2)
+
+# 3. High-Speed Binary Serialization (Key-Value databases / IPC)
+blob = polyxml.dumps_binary(item)
+restored = polyxml.loads_binary(blob, Item)
+```

{polyxml-0.5.0 → polyxml-0.6.0}/crates/polyxml-python/tests/test_polyxml.py

@@ -1,9 +1,12 @@
 import io
 import pathlib
+from collections import UserString
 from dataclasses import dataclass, field
 from decimal import Decimal
 from enum import Enum
+from xml.etree.ElementTree import QName
 
+import msgspec
 import pytest
 from pydantic import BaseModel, Field
 
@@ -402,3 +405,140 @@ def test_binary_deserialization_unsupported_type():
     payload = polyxml.dumps_binary({"a": 1})
     with pytest.raises(NotImplementedError, match="PolyXML binary deserializer cannot deserialize"):
         polyxml.loads_binary(payload, UnhandledClass)
+
+
+class StatusEnum(Enum):
+    ACTIVE = "active"
+    INACTIVE = "inactive"
+
+
+class CustomDuration(UserString):
+    pass
+
+
+class FromStringHolder:
+    def __init__(self, val: str):
+        self.val = val
+
+    @classmethod
+    def from_string(cls, val: str):
+        return cls(val)
+
+    def __str__(self):
+        return self.val
+
+    def __eq__(self, other):
+        return isinstance(other, FromStringHolder) and self.val == other.val
+
+
+@dataclass
+class RichXmlItem:
+    status: StatusEnum
+    qname: QName
+    duration: CustomDuration
+    holder: FromStringHolder
+
+
+def test_binary_serialization_xml_types():
+    orig = RichXmlItem(
+        status=StatusEnum.ACTIVE,
+        qname=QName("http://example.com", "elem"),
+        duration=CustomDuration("P1Y2M3D"),
+        holder=FromStringHolder("parsed_value"),
+    )
+    payload = polyxml.dumps_binary(orig)
+    decoded = polyxml.loads_binary(payload, RichXmlItem)
+    assert decoded.status == StatusEnum.ACTIVE
+    assert decoded.qname == QName("http://example.com", "elem")
+    assert decoded.duration == CustomDuration("P1Y2M3D")
+    assert decoded.holder == FromStringHolder("parsed_value")
+
+
+def test_binary_serialization_tag_class_dataclass():
+    item = SimpleItem(id=99, name="TaggedItem", price=49.99, active=True)
+    payload = polyxml.dumps_binary(item, tag_class=True)
+
+    # Loads without passing target_type
+    decoded_auto = polyxml.loads_binary(payload)
+    assert isinstance(decoded_auto, SimpleItem)
+    assert decoded_auto.id == 99
+    assert decoded_auto.name == "TaggedItem"
+
+    # Loads with explicit target_type on tagged payload
+    decoded_explicit = polyxml.loads_binary(payload, SimpleItem)
+    assert isinstance(decoded_explicit, SimpleItem)
+    assert decoded_explicit.id == 99
+
+
+def test_binary_serialization_tag_class_pydantic():
+    device = PydanticDevice(serial="SN-9999", model="AeroEdge", power=250.0)
+    payload = polyxml.dumps_binary(device, tag_class=True)
+    decoded = polyxml.loads_binary(payload)
+    assert isinstance(decoded, PydanticDevice)
+    assert decoded.serial == "SN-9999"
+    assert decoded.model == "AeroEdge"
+    assert decoded.power == 250.0
+
+
+def test_binary_serialization_tag_class_primitive():
+    payload = polyxml.dumps_binary("plain_string", tag_class=True)
+    decoded = polyxml.loads_binary(payload)
+    assert decoded == "plain_string"
+
+
+def test_binary_serialization_hooks_direct():
+    from polyxml import _dec_hook, _enc_hook
+
+    assert _enc_hook(StatusEnum.ACTIVE) == "active"
+    assert _dec_hook(Decimal, "19.99") == Decimal("19.99")
+    assert _dec_hook(StatusEnum, "active") == StatusEnum.ACTIVE
+
+
+def test_binary_serialization_resolve_class():
+    from polyxml import _resolve_class
+
+    assert _resolve_class("") is None
+    assert _resolve_class("NoColonHere") is None
+    assert _resolve_class("nonexistent.module:FakeClass") is None
+    assert _resolve_class("polyxml:dumps_binary") is polyxml.dumps_binary
+    # Hits the _CLASS_CACHE branch
+    assert _resolve_class("polyxml:dumps_binary") is polyxml.dumps_binary
+
+
+def test_binary_serialization_tagged_unresolvable_class():
+    # Tagged payload with a class that cannot be resolved
+    raw_inner = msgspec.msgpack.encode({"key": "value"})
+    tagged_data = msgspec.msgpack.encode(("nonexistent.module:FakeClass", raw_inner))
+
+    decoded = polyxml.loads_binary(tagged_data)
+    assert decoded == {"key": "value"}
+
+
+def test_binary_serialization_tagged_payload_decode_error():
+    # Explicit target_type on tagged payload where inner payload fails to decode
+    raw_inner = msgspec.msgpack.encode({"unexpected": "structure"})
+    tagged_data = msgspec.msgpack.encode(("nonexistent:Fake", raw_inner))
+
+    with pytest.raises(msgspec.ValidationError):
+        polyxml.loads_binary(tagged_data, SimpleItem)
+
+
+def test_binary_serialization_target_type_non_tagged_decode_errors():
+    # Target type passed with invalid msgpack bytes
+    with pytest.raises(msgspec.DecodeError):
+        polyxml.loads_binary(b"\xc1", SimpleItem)
+
+    # Target type passed with valid non-tagged msgpack that fails validation
+    with pytest.raises(msgspec.ValidationError):
+        polyxml.loads_binary(msgspec.msgpack.encode(123), SimpleItem)
+
+
+def test_binary_serialization_loads_corrupted_or_non_tagged():
+    # Plain non-tagged list of two items where second is not bytes
+    data = msgspec.msgpack.encode(["not_a_class_tag", 12345])
+    decoded = polyxml.loads_binary(data)
+    assert decoded == ["not_a_class_tag", 12345]
+
+    # Non-decodable data to custom type
+    with pytest.raises(msgspec.DecodeError):
+        polyxml.loads_binary(b"\xc1")

{polyxml-0.5.0 → polyxml-0.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "polyxml"
-version = "0.5.0"
+version = "0.6.0"
 description = "High-performance, polyglot XML data-binding engine built in Rust"
 authors = [
     { name = "Bailey Nguyen", email = "bailey.tan.nguyen@gmail.com" }

{polyxml-0.5.0 → polyxml-0.6.0}/python/polyxml/__init__.py

@@ -24,10 +24,15 @@ QUICKSTART FOR AI AGENTS & DEVELOPERS:
 See `AGENT_GUIDE.md` or https://nth-bailey.github.io/PolyXML/ for complete documentation.
 """
 
+import importlib
 import pathlib
+from collections import UserString
 from collections.abc import Iterator
+from dataclasses import is_dataclass
 from decimal import Decimal
+from enum import Enum
 from typing import IO
+from xml.etree.ElementTree import QName
 
 from polyxml._polyxml import (  # type: ignore[import-not-found]
     deserialize as _deserialize,
@@ -120,11 +125,38 @@ except ImportError:  # pragma: no cover
     msgspec = None  # type: ignore[assignment]
     _HAS_MSGSPEC = False
 
+_CLASS_CACHE: dict[str, type[object]] = {}
 
-def _enc_hook(obj: object) -> str:
+
+def _resolve_class(class_identifier: str) -> type[object] | None:
+    if not class_identifier:
+        return None
+    if class_identifier in _CLASS_CACHE:
+        return _CLASS_CACHE[class_identifier]
+    if ":" in class_identifier:
+        module_name, class_name = class_identifier.rsplit(":", 1)
+        try:
+            mod = importlib.import_module(module_name)
+            resolved = getattr(mod, class_name)
+            _CLASS_CACHE[class_identifier] = resolved
+            return resolved
+        except (ImportError, AttributeError):
+            return None
+    return None
+
+
+def _enc_hook(obj: object) -> object:
     if isinstance(obj, pathlib.Path | Decimal):
         return str(obj)
-    if hasattr(obj, "from_string") and hasattr(obj, "val"):
+    if isinstance(obj, Enum):
+        return obj.value
+    if isinstance(obj, QName):
+        return str(obj)
+    if isinstance(obj, UserString):
+        return str(obj)
+    if hasattr(obj, "model_dump") and callable(obj.model_dump):
+        return obj.model_dump()
+    if hasattr(obj, "from_string"):
         return str(obj)
     raise NotImplementedError(
         f"PolyXML binary serializer cannot serialize object of type {type(obj).__name__}"
@@ -134,18 +166,30 @@ def _enc_hook(obj: object) -> str:
 def _dec_hook(target_type: type[object], obj: object) -> object:
     if target_type is pathlib.Path:
         return pathlib.Path(str(obj))
+    if target_type is Decimal:
+        return Decimal(str(obj))
+    if isinstance(target_type, type) and issubclass(target_type, Enum):
+        return target_type(obj)
+    if target_type is QName or (isinstance(target_type, type) and issubclass(target_type, QName)):
+        return QName(str(obj))
+    if hasattr(target_type, "model_validate") and callable(target_type.model_validate):
+        return target_type.model_validate(obj)
     if hasattr(target_type, "from_string"):
         return target_type.from_string(str(obj))
+    if isinstance(target_type, type) and issubclass(target_type, UserString):
+        return target_type(str(obj))
     raise NotImplementedError(
         f"PolyXML binary deserializer cannot deserialize object into type {target_type.__name__}"
     )
 
 
-def dumps_binary(obj: object) -> bytes:
+def dumps_binary(obj: object, *, tag_class: bool = False) -> bytes:
     """Serialize a model or dataclass into a high-throughput binary MessagePack buffer.
 
     Args:
         obj: Python dataclass, Pydantic model, or object.
+        tag_class: When True, embeds the class identifier in the binary payload
+            allowing loads_binary to reconstruct the exact model class dynamically.
 
     Returns:
         Compact binary MessagePack bytes.
@@ -158,6 +202,16 @@ def dumps_binary(obj: object) -> bytes:
             "PolyXML binary serialization requires 'msgspec'. "
             "Install it via: pip install 'polyxml[msgpack]' or pip install msgspec"
         )
+    if tag_class:
+        if is_dataclass(obj) or hasattr(obj.__class__, "model_fields"):
+            cls = obj.__class__
+            identifier = f"{cls.__module__}:{cls.__qualname__}"
+            _CLASS_CACHE[identifier] = cls
+            payload = msgspec.msgpack.encode(obj, enc_hook=_enc_hook)
+            return msgspec.msgpack.encode((identifier, payload))
+        payload = msgspec.msgpack.encode(obj, enc_hook=_enc_hook)
+        return msgspec.msgpack.encode(("", payload))
+
     return msgspec.msgpack.encode(obj, enc_hook=_enc_hook)
 
 
@@ -166,7 +220,9 @@ def loads_binary[T](data: bytes, target_type: type[T] | None = None) -> T | obje
 
     Args:
         data: Binary MessagePack bytes to decode.
-        target_type: Optional target dataclass or model class. If omitted, returns dynamic structure.
+        target_type: Optional target dataclass or model class. If omitted and the
+            payload was serialized with tag_class=True, dynamically reconstructs the
+            original model instance. Otherwise returns a dynamic dictionary/structure.
 
     Returns:
         The deserialized model instance or object.
@@ -180,8 +236,39 @@ def loads_binary[T](data: bytes, target_type: type[T] | None = None) -> T | obje
             "Install it via: pip install 'polyxml[msgpack]' or pip install msgspec"
         )
     if target_type is not None:
-        return msgspec.msgpack.decode(data, type=target_type, dec_hook=_dec_hook)
-    return msgspec.msgpack.decode(data, dec_hook=_dec_hook)
+        try:
+            return msgspec.msgpack.decode(data, type=target_type, dec_hook=_dec_hook)
+        except (msgspec.DecodeError, msgspec.ValidationError):
+            try:
+                decoded = msgspec.msgpack.decode(data)
+                if (
+                    isinstance(decoded, (list, tuple))
+                    and len(decoded) == 2
+                    and isinstance(decoded[0], str)
+                    and isinstance(decoded[1], (bytes, bytearray))
+                ):
+                    return msgspec.msgpack.decode(decoded[1], type=target_type, dec_hook=_dec_hook)
+            except Exception:
+                pass
+            raise
+
+    try:
+        decoded = msgspec.msgpack.decode(data)
+        if (
+            isinstance(decoded, (list, tuple))
+            and len(decoded) == 2
+            and isinstance(decoded[0], str)
+            and isinstance(decoded[1], (bytes, bytearray))
+        ):
+            tag, payload = decoded
+            if tag:
+                resolved_cls = _resolve_class(tag)
+                if resolved_cls is not None:
+                    return msgspec.msgpack.decode(payload, type=resolved_cls, dec_hook=_dec_hook)
+            return msgspec.msgpack.decode(payload, dec_hook=_dec_hook)
+        return decoded
+    except Exception:
+        return msgspec.msgpack.decode(data, dec_hook=_dec_hook)
 
 
 __all__ = [

polyxml-0.5.0/README.md

@@ -1,5 +0,0 @@
-# PolyXML Python Bindings
-
-High-performance native XML data-binding engine for Python dataclasses and Pydantic models.
-
-Powered by polyxml-core written in Rust and PyO3 (abi3-py312).

polyxml-0.5.0/crates/polyxml-python/README.md

@@ -1,5 +0,0 @@
-# PolyXML Python Bindings
-
-High-performance native XML data-binding engine for Python dataclasses and Pydantic models.
-
-Powered by polyxml-core written in Rust and PyO3 (abi3-py312).