polyxml 0.4.0__tar.gz → 0.5.1__tar.gz

{polyxml-0.4.0 → polyxml-0.5.1}/Cargo.lock

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

{polyxml-0.4.0 → polyxml-0.5.1}/Cargo.toml

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

{polyxml-0.4.0 → polyxml-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: polyxml
-Version: 0.4.0
+Version: 0.5.1
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -16,7 +16,10 @@ Requires-Dist: pytest>=8.0.0 ; extra == 'dev'
 Requires-Dist: pytest-cov>=5.0.0 ; extra == 'dev'
 Requires-Dist: pydantic>=2.7.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.4.0 ; extra == 'dev'
+Requires-Dist: msgspec>=0.18.0 ; extra == 'dev'
+Requires-Dist: msgspec>=0.18.0 ; extra == 'msgpack'
 Provides-Extra: dev
+Provides-Extra: msgpack
 Summary: High-performance, polyglot XML data-binding engine built in Rust
 Author-email: Bailey Nguyen <bailey.tan.nguyen@gmail.com>
 License: MIT
@@ -31,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.5.1/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.1/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.4.0 → polyxml-0.5.1}/crates/polyxml-python/tests/test_polyxml.py

@@ -12,7 +12,6 @@ try:
 except ImportError:
 
     class XmlDate:
-
         def __init__(self, val: str):
             self.val = val
 
@@ -27,7 +26,6 @@ except ImportError:
             return self.val
 
     class XmlDateTime:
-
         def __init__(self, val: str):
             self.val = val
 
@@ -42,7 +40,6 @@ except ImportError:
             return self.val
 
     class XmlTime:
-
         def __init__(self, val: str):
             self.val = val
 
@@ -57,7 +54,6 @@ except ImportError:
             return self.val
 
     class XmlDuration:
-
         def __init__(self, val: str):
             self.val = val
 
@@ -67,6 +63,7 @@ except ImportError:
         def __str__(self):
             return self.val
 
+
 import polyxml
 
 
@@ -333,9 +330,7 @@ def test_to_bytes_invalid_type():
 
 @dataclass
 class UnionWrapper:
-    child: None | ChildNode = field(
-        default=None, metadata={"type": "Element", "name": "child"}
-    )
+    child: None | ChildNode = field(default=None, metadata={"type": "Element", "name": "child"})
     count: int | None = field(default=None, metadata={"type": "Element"})
 
 
@@ -346,3 +341,64 @@ def test_pep604_union_nested_dataclass():
     assert res.child.tag == "Payload"
     assert res.count == 42
 
+
+def test_binary_serialization_dataclass():
+    item = SimpleItem(id=42, name="TestItem", price=19.99, active=True)
+    payload = polyxml.dumps_binary(item)
+    assert isinstance(payload, bytes)
+    assert len(payload) > 0
+
+    decoded = polyxml.loads_binary(payload, SimpleItem)
+    assert isinstance(decoded, SimpleItem)
+    assert decoded.id == 42
+    assert decoded.name == "TestItem"
+    assert decoded.price == 19.99
+    assert decoded.active is True
+
+
+def test_binary_serialization_decimal():
+    @dataclass
+    class DecimalItem:
+        val: Decimal
+
+    item = DecimalItem(val=Decimal("19.99"))
+    payload = polyxml.dumps_binary(item)
+    decoded = polyxml.loads_binary(payload, DecimalItem)
+    assert decoded.val == Decimal("19.99")
+
+
+def test_binary_serialization_untyped():
+    data = {"name": "Alice", "score": 100}
+    payload = polyxml.dumps_binary(data)
+    decoded = polyxml.loads_binary(payload)
+    assert decoded == data
+
+
+def test_binary_serialization_xmldate_and_path():
+    @dataclass
+    class ExtraItem:
+        date: XmlDate
+        path: pathlib.Path
+
+    orig = ExtraItem(date=XmlDate("2026-09-12"), path=pathlib.Path("/tmp/test.xml"))
+    payload = polyxml.dumps_binary(orig)
+    decoded = polyxml.loads_binary(payload, ExtraItem)
+    assert decoded.date == XmlDate("2026-09-12")
+    assert decoded.path == pathlib.Path("/tmp/test.xml")
+
+
+def test_binary_serialization_unsupported_type():
+    class CustomObject:
+        pass
+
+    with pytest.raises(NotImplementedError, match="PolyXML binary serializer cannot serialize"):
+        polyxml.dumps_binary(CustomObject())
+
+
+def test_binary_deserialization_unsupported_type():
+    class UnhandledClass:
+        pass
+
+    payload = polyxml.dumps_binary({"a": 1})
+    with pytest.raises(NotImplementedError, match="PolyXML binary deserializer cannot deserialize"):
+        polyxml.loads_binary(payload, UnhandledClass)

{polyxml-0.4.0 → polyxml-0.5.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "polyxml"
-version = "0.4.0"
+version = "0.5.1"
 description = "High-performance, polyglot XML data-binding engine built in Rust"
 authors = [
     { name = "Bailey Nguyen", email = "bailey.tan.nguyen@gmail.com" }
@@ -28,11 +28,15 @@ classifiers = [
 dependencies = []
 
 [project.optional-dependencies]
+msgpack = [
+    "msgspec>=0.18.0",
+]
 dev = [
     "pytest>=8.0.0",
     "pytest-cov>=5.0.0",
     "pydantic>=2.7.0",
     "ruff>=0.4.0",
+    "msgspec>=0.18.0",
 ]
 
 [project.urls]

polyxml-0.5.1/python/polyxml/AGENT_GUIDE.md

@@ -0,0 +1,89 @@
+# PolyXML AI Agent Guide
+
+Quick-reference instructions for AI coding assistants (Claude, Cursor, Copilot, Antigravity, etc.) using `polyxml` in Python projects.
+
+---
+
+## 1. Overview & Capabilities
+
+`polyxml` is an ultra-fast, native XML data-binding engine written in pure Rust (using `quick-xml` and `lexical-core`) with stable ABI (`abi3-py312`) Python bindings. It provides bidirectional deserialization and serialization for Python 3.12+ `dataclasses` and Pydantic v2 models.
+
+---
+
+## 2. Common Recipes
+
+### A. Deserializing XML (Strings, Bytes, or Files)
+```python
+from dataclasses import dataclass, field
+import pathlib
+import polyxml
+
+
+@dataclass
+class Item:
+    id: int = field(metadata={"type": "Attribute"})
+    name: str = field(metadata={"type": "Element"})
+    price: float = field(metadata={"type": "Element"})
+
+
+# 1. From raw XML string:
+item = polyxml.deserialize('<Item id="1"><name>Bolt</name><price>0.99</price></Item>', Item)
+
+# 2. From raw bytes:
+item = polyxml.deserialize(b"<Item ...>...</Item>", Item)
+
+# 3. From pathlib.Path:
+item = polyxml.deserialize(pathlib.Path("item.xml"), Item)
+```
+
+### B. Streaming Massive XML Files with O(1) Constant Memory
+For large datasets (hundreds of MBs or GBs such as transit timetables or feeds), do **NOT** load the entire XML tree at once. Use `iterparse`:
+
+```python
+import polyxml
+from my_models import VehicleJourney
+
+# Streams elements one-by-one with zero intermediate DOM allocations
+for journey in polyxml.iterparse("large_transit_dump.xml", VehicleJourney, tag="VehicleJourney"):
+    process_journey(journey)
+```
+
+### C. Pydantic v2 Models
+PolyXML natively deserializes into Pydantic v2 `BaseModel` classes with the same API:
+
+```python
+from pydantic import BaseModel, Field
+import polyxml
+
+
+class StopPoint(BaseModel):
+    id: str = Field(json_schema_extra={"type": "Attribute"})
+    name: str
+
+
+stop = polyxml.deserialize(
+    '<StopPoint id="SP1"><name>Central Station</name></StopPoint>', StopPoint
+)
+```
+
+### D. Serializing to XML
+```python
+import polyxml
+
+# Serialize model to UTF-8 XML bytes
+xml_bytes = polyxml.serialize(item, indent=2)
+
+# If string is required:
+xml_string = xml_bytes.decode("utf-8")
+```
+
+---
+
+## 3. Common Pitfalls & Quick Fixes
+
+- **Pitfall**: Attempting `polyxml.XmlParser()`  
+  **Fix**: PolyXML uses module-level functional entrypoints: `polyxml.deserialize(...)` and `polyxml.iterparse(...)`.
+- **Pitfall**: Passing file handles or paths without reading  
+  **Fix**: `polyxml.deserialize(...)` accepts strings, byte buffers, `pathlib.Path`, or `IO` streams directly.
+- **Pitfall**: High memory usage on massive XML files  
+  **Fix**: Switch from `polyxml.deserialize` to `polyxml.iterparse(source, ModelClass, tag="TagName")`.

polyxml-0.5.1/python/polyxml/__init__.py

@@ -0,0 +1,194 @@
+"""PolyXML: High-performance, polyglot native XML data-binding engine.
+
+QUICKSTART FOR AI AGENTS & DEVELOPERS:
+
+1. Deserialize XML (string, bytes, or file Path) into a typed Dataclass or Pydantic model:
+    >>> import polyxml
+    >>> from dataclasses import dataclass, field
+    >>>
+    >>> @dataclass
+    >>> class User:
+    ...     name: str = field(metadata={"type": "Element"})
+    >>>
+    >>> user = polyxml.deserialize("<User><name>Alice</name></User>", User)
+    >>> user.name
+    'Alice'
+
+2. Stream large XML files with O(1) constant memory (Streaming / Facet Extraction):
+    >>> for user in polyxml.iterparse("massive_users.xml", User, tag="User"):
+    ...     process(user)
+
+3. Serialize a model instance back into XML bytes:
+    >>> xml_bytes = polyxml.serialize(user, indent=2)
+
+See `AGENT_GUIDE.md` or https://nth-bailey.github.io/PolyXML/ for complete documentation.
+"""
+
+import pathlib
+from collections.abc import Iterator
+from decimal import Decimal
+from typing import IO
+
+from polyxml._polyxml import (  # type: ignore[import-not-found]
+    deserialize as _deserialize,
+)
+from polyxml._polyxml import (
+    iterparse as _iterparse,
+)
+from polyxml._polyxml import (
+    serialize as _serialize,
+)
+from polyxml._polyxml import (
+    version as _version,
+)
+
+__version__: str = _version()
+
+
+def _to_bytes(source: bytes | str | pathlib.Path | IO[bytes] | IO[str]) -> bytes:
+    if isinstance(source, bytes):
+        return source
+    if isinstance(source, str):
+        if source.lstrip().startswith("<"):
+            return source.encode("utf-8")
+        path = pathlib.Path(source)
+        if path.is_file():
+            return path.read_bytes()
+        return source.encode("utf-8")
+    if isinstance(source, pathlib.Path):
+        return source.read_bytes()
+    if hasattr(source, "read"):
+        data = source.read()
+        return data.encode("utf-8") if isinstance(data, str) else data
+    raise TypeError(
+        f"Unsupported XML source type: {type(source).__name__}. "
+        "Expected bytes, str (XML string or file path), pathlib.Path, or a binary/text IO stream."
+    )
+
+
+def deserialize[T](
+    source: bytes | str | pathlib.Path | IO[bytes] | IO[str], target_type: type[T]
+) -> T:
+    """Deserialize XML bytes, string, file path, or stream into a typed model.
+
+    Args:
+        source: XML content as raw bytes, string, Path, or file stream.
+        target_type: The target dataclass or model class.
+
+    Returns:
+        The deserialized model instance.
+    """
+    return _deserialize(_to_bytes(source), target_type)
+
+
+def iterparse[T](
+    source: bytes | str | pathlib.Path | IO[bytes] | IO[str],
+    target_type: type[T],
+    tag: str | None = None,
+) -> Iterator[T]:
+    """Stream and deserialize XML elements one-by-one with O(1) constant memory.
+
+    Args:
+        source: XML content as raw bytes, string, Path, or file stream.
+        target_type: The target dataclass or model class for each element.
+        tag: Optional XML element tag name to match. Defaults to the model schema name.
+
+    Yields:
+        Deserialized model instances as they are streamed.
+    """
+    return _iterparse(_to_bytes(source), target_type, tag)
+
+
+def serialize(obj: object, *, indent: int | None = None) -> bytes:
+    """Serialize a strongly-typed model instance back into XML bytes.
+
+    Args:
+        obj: Python dataclass or Pydantic model instance.
+        indent: Optional indentation size in spaces for pretty-printing.
+
+    Returns:
+        UTF-8 encoded XML bytes representing the model instance.
+    """
+    return _serialize(obj, indent=indent)
+
+
+try:
+    import msgspec
+
+    _HAS_MSGSPEC = True
+except ImportError:  # pragma: no cover
+    msgspec = None  # type: ignore[assignment]
+    _HAS_MSGSPEC = False
+
+
+def _enc_hook(obj: object) -> str:
+    if isinstance(obj, pathlib.Path | Decimal):
+        return str(obj)
+    if hasattr(obj, "from_string") and hasattr(obj, "val"):
+        return str(obj)
+    raise NotImplementedError(
+        f"PolyXML binary serializer cannot serialize object of type {type(obj).__name__}"
+    )
+
+
+def _dec_hook(target_type: type[object], obj: object) -> object:
+    if target_type is pathlib.Path:
+        return pathlib.Path(str(obj))
+    if hasattr(target_type, "from_string"):
+        return target_type.from_string(str(obj))
+    raise NotImplementedError(
+        f"PolyXML binary deserializer cannot deserialize object into type {target_type.__name__}"
+    )
+
+
+def dumps_binary(obj: object) -> bytes:
+    """Serialize a model or dataclass into a high-throughput binary MessagePack buffer.
+
+    Args:
+        obj: Python dataclass, Pydantic model, or object.
+
+    Returns:
+        Compact binary MessagePack bytes.
+
+    Raises:
+        RuntimeError: If msgspec is not installed.
+    """
+    if not _HAS_MSGSPEC:  # pragma: no cover
+        raise RuntimeError(
+            "PolyXML binary serialization requires 'msgspec'. "
+            "Install it via: pip install 'polyxml[msgpack]' or pip install msgspec"
+        )
+    return msgspec.msgpack.encode(obj, enc_hook=_enc_hook)
+
+
+def loads_binary[T](data: bytes, target_type: type[T] | None = None) -> T | object:
+    """Deserialize binary MessagePack bytes into a strongly-typed model or object.
+
+    Args:
+        data: Binary MessagePack bytes to decode.
+        target_type: Optional target dataclass or model class. If omitted, returns dynamic structure.
+
+    Returns:
+        The deserialized model instance or object.
+
+    Raises:
+        RuntimeError: If msgspec is not installed.
+    """
+    if not _HAS_MSGSPEC:  # pragma: no cover
+        raise RuntimeError(
+            "PolyXML binary deserialization requires 'msgspec'. "
+            "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)
+
+
+__all__ = [
+    "__version__",
+    "deserialize",
+    "dumps_binary",
+    "iterparse",
+    "loads_binary",
+    "serialize",
+]

polyxml-0.4.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.4.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).

polyxml-0.4.0/python/polyxml/__init__.py

@@ -1,87 +0,0 @@
-"""PolyXML: High-performance, polyglot XML data-binding engine."""
-
-import pathlib
-from collections.abc import Iterator
-from typing import IO
-
-from polyxml._polyxml import (  # type: ignore[import-not-found]
-    deserialize as _deserialize,
-)
-from polyxml._polyxml import (
-    iterparse as _iterparse,
-)
-from polyxml._polyxml import (
-    serialize as _serialize,
-)
-from polyxml._polyxml import (
-    version as _version,
-)
-
-__version__: str = _version()
-
-
-def _to_bytes(source: bytes | str | pathlib.Path | IO[bytes] | IO[str]) -> bytes:
-    if isinstance(source, bytes):
-        return source
-    if isinstance(source, str):
-        if source.lstrip().startswith("<"):
-            return source.encode("utf-8")
-        path = pathlib.Path(source)
-        if path.is_file():
-            return path.read_bytes()
-        return source.encode("utf-8")
-    if isinstance(source, pathlib.Path):
-        return source.read_bytes()
-    if hasattr(source, "read"):
-        data = source.read()
-        return data.encode("utf-8") if isinstance(data, str) else data
-    raise TypeError(f"Unsupported XML source type: {type(source)}")
-
-
-def deserialize[T](
-    source: bytes | str | pathlib.Path | IO[bytes] | IO[str], target_type: type[T]
-) -> T:
-    """Deserialize XML bytes, string, file path, or stream into a typed model.
-
-    Args:
-        source: XML content as raw bytes, string, Path, or file stream.
-        target_type: The target dataclass or model class.
-
-    Returns:
-        The deserialized model instance.
-    """
-    return _deserialize(_to_bytes(source), target_type)
-
-
-def iterparse[T](
-    source: bytes | str | pathlib.Path | IO[bytes] | IO[str],
-    target_type: type[T],
-    tag: str | None = None,
-) -> Iterator[T]:
-    """Stream and deserialize XML elements one-by-one with O(1) constant memory.
-
-    Args:
-        source: XML content as raw bytes, string, Path, or file stream.
-        target_type: The target dataclass or model class for each element.
-        tag: Optional XML element tag name to match. Defaults to the model schema name.
-
-    Yields:
-        Deserialized model instances as they are streamed.
-    """
-    return _iterparse(_to_bytes(source), target_type, tag)
-
-
-def serialize(obj: object, *, indent: int | None = None) -> bytes:
-    """Serialize a strongly-typed model instance back into XML bytes.
-
-    Args:
-        obj: Python dataclass or Pydantic model instance.
-        indent: Optional indentation size in spaces for pretty-printing.
-
-    Returns:
-        UTF-8 encoded XML bytes representing the model instance.
-    """
-    return _serialize(obj, indent=indent)
-
-
-__all__ = ["__version__", "deserialize", "iterparse", "serialize"]