msgspec-xml 0.1.0__py3-none-any.whl

msgspec_xml/__init__.py

@@ -0,0 +1,5 @@
+__all__ = ["Decoder", "Encoder", "decode", "encode"]
+__version__ = "0.1.0"
+
+from msgspec_xml.decoder import Decoder, decode
+from msgspec_xml.encoder import Encoder, encode

msgspec_xml/decoder.py

@@ -0,0 +1,76 @@
+__all__ = ["Decoder", "decode"]
+
+from typing import Any, Generic, TypeVar
+from xml.etree.ElementTree import Element
+
+from defusedxml import ElementTree
+from msgspec import Struct, convert
+from msgspec.structs import FieldInfo, fields
+
+from msgspec_xml.introspection import (
+    FieldType,
+    attribute_name,
+    element_tag,
+    inspect_annotation,
+    item_tag,
+)
+
+T = TypeVar("T", bound=Struct)
+_MISSING: Any = object()
+
+
+class Decoder(Generic[T]):
+    def __init__(self, type_: type[T]):
+        self._type = type_
+
+    def decode(self, xml: str | bytes) -> T:
+        root = ElementTree.fromstring(xml)
+        data = _decode_struct(element=root, cls=self._type)
+        return convert(data, type=self._type, strict=False)
+
+
+def decode(xml: str | bytes, type_: type[T]) -> T:
+    return Decoder(type_=type_).decode(xml=xml)
+
+
+def _decode_struct(element: Element, cls: type[Struct]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for field in fields(cls):
+        info = inspect_annotation(annotation=field.type)
+        value = _decode_field(element=element, field=field, info=info)
+        if value is not _MISSING:
+            result[field.encode_name] = value
+    return result
+
+
+def _decode_field(element: Element, field: FieldInfo, info: FieldType) -> Any:  # noqa: ANN401
+    xml = info.xml
+    if xml.attr:
+        name = attribute_name(field=field, info=info)
+        return element.attrib.get(name, _MISSING)
+    if xml.text:
+        return (element.text or "").strip()
+    if info.item is not None:
+        return _decode_list(element=element, field=field, info=info)
+    child = element.find(element_tag(field=field, info=info))
+    if child is None:
+        return _MISSING
+    if info.is_struct:
+        return _decode_struct(element=child, cls=info.type)
+    return (child.text or "").strip()
+
+
+def _decode_list(element: Element, field: FieldInfo, info: FieldType) -> list[Any]:
+    item = info.item
+    assert item is not None  # noqa: S101
+    parent = element.find(info.xml.wrapper) if info.xml.wrapper else element
+    if parent is None:
+        return []
+    tag = item_tag(field=field, info=info)
+    return [_decode_item(element=child, item=item) for child in parent.findall(tag)]
+
+
+def _decode_item(element: Element, item: FieldType) -> Any:  # noqa: ANN401
+    if item.is_struct:
+        return _decode_struct(element=element, cls=item.type)
+    return (element.text or "").strip()

msgspec_xml/encoder.py

@@ -0,0 +1,69 @@
+__all__ = ["Encoder", "encode"]
+
+from xml.etree import ElementTree as ET
+from xml.etree.ElementTree import Element
+
+from msgspec import Struct, to_builtins
+from msgspec.structs import FieldInfo, fields
+
+from msgspec_xml.introspection import (
+    FieldType,
+    attribute_name,
+    class_tag,
+    element_tag,
+    inspect_annotation,
+    item_tag,
+)
+
+
+class Encoder:
+    def encode(self, obj: Struct) -> bytes:
+        root = _encode_struct(obj=obj, tag=class_tag(cls=type(obj)))
+        return ET.tostring(root, encoding="UTF-8")
+
+
+def encode(obj: Struct) -> bytes:
+    return Encoder().encode(obj=obj)
+
+
+def _encode_struct(obj: Struct, tag: str) -> Element:
+    element = ET.Element(tag)
+    for field in fields(type(obj)):
+        value = getattr(obj, field.name)
+        if value is None:
+            continue
+        info = inspect_annotation(annotation=field.type)
+        _encode_field(element=element, field=field, info=info, value=value)
+    return element
+
+
+def _encode_field(element: Element, field: FieldInfo, info: FieldType, value: object) -> None:
+    xml = info.xml
+    if xml.attr:
+        element.set(attribute_name(field=field, info=info), _stringify(value))
+    elif xml.text:
+        element.text = _stringify(value)
+    elif info.item is not None:
+        _encode_list(element=element, field=field, info=info, value=value)  # ty: ignore[invalid-argument-type]
+    elif info.is_struct:
+        element.append(_encode_struct(obj=value, tag=element_tag(field=field, info=info)))  # ty: ignore[invalid-argument-type]
+    else:
+        child = ET.SubElement(element, element_tag(field=field, info=info))
+        child.text = _stringify(value)
+
+
+def _encode_list(element: Element, field: FieldInfo, info: FieldType, value: list) -> None:
+    item = info.item
+    assert item is not None  # noqa: S101
+    parent = ET.SubElement(element, info.xml.wrapper) if info.xml.wrapper else element
+    tag = item_tag(field=field, info=info)
+    for item_value in value:
+        if item.is_struct:
+            parent.append(_encode_struct(obj=item_value, tag=tag))
+        else:
+            child = ET.SubElement(parent, tag)
+            child.text = _stringify(item_value)
+
+
+def _stringify(value: object) -> str:
+    return str(to_builtins(value))

msgspec_xml/introspection.py

@@ -0,0 +1,84 @@
+__all__ = [
+    "FieldType",
+    "attribute_name",
+    "class_tag",
+    "element_tag",
+    "inspect_annotation",
+    "item_tag",
+]
+
+from types import NoneType
+from typing import Annotated, Any, Optional, get_args, get_origin
+
+from msgspec import Struct
+from msgspec.inspect import is_struct_type
+from msgspec.structs import FieldInfo
+
+from msgspec_xml.metadata import XML
+
+
+class FieldType(Struct, frozen=True, kw_only=True):
+    type: Any
+    xml: XML
+    is_struct: bool = False
+    item: Optional["FieldType"] = None
+
+
+def inspect_annotation(annotation: Any) -> FieldType:  # noqa: ANN401
+    annotation, xml = _split_xml(annotation)
+    annotation = _unwrap_optional(annotation=annotation)
+    if get_origin(annotation) is list:
+        (item_annotation,) = get_args(annotation)
+        return FieldType(
+            type=annotation, xml=xml, item=inspect_annotation(annotation=item_annotation)
+        )
+    return FieldType(type=annotation, xml=xml, is_struct=is_struct_type(annotation))
+
+
+def class_tag(cls: type[Struct]) -> str:
+    tag = getattr(cls, "__tag__", None)
+    if tag is not None:
+        return tag
+    config_tag = cls.__struct_config__.tag
+    if isinstance(config_tag, str):
+        return config_tag
+    return cls.__name__
+
+
+def attribute_name(field: FieldInfo, info: FieldType) -> str:
+    return info.xml.tag or field.encode_name
+
+
+def element_tag(field: FieldInfo, info: FieldType) -> str:
+    if info.xml.tag:
+        return info.xml.tag
+    if info.is_struct:
+        return class_tag(cls=info.type)
+    return field.encode_name
+
+
+def item_tag(field: FieldInfo, info: FieldType) -> str:
+    item = info.item
+    if item is None:
+        raise TypeError("item_tag() requires a list field")
+    if item.xml.tag:
+        return item.xml.tag
+    if info.xml.tag:
+        return info.xml.tag
+    if item.is_struct:
+        return class_tag(cls=item.type)
+    return field.encode_name
+
+
+def _split_xml(annotation: Any) -> tuple[Any, XML]:  # noqa: ANN401
+    if get_origin(annotation) is Annotated:
+        base, *metadata = get_args(annotation)
+        return base, next((value for value in metadata if isinstance(value, XML)), XML())
+    return annotation, XML()
+
+
+def _unwrap_optional(annotation: Any) -> Any:  # noqa: ANN401
+    args = get_args(annotation)
+    if len(args) == 2 and NoneType in args:
+        return next(arg for arg in args if arg is not NoneType)
+    return annotation

msgspec_xml/metadata.py

@@ -0,0 +1,38 @@
+__all__ = ["XML"]
+
+from msgspec import Struct
+
+
+class XML(Struct, frozen=True, forbid_unknown_fields=True):
+    tag: str | None = None
+    wrapper: str | None = None
+    attr: bool = False
+    text: bool = False
+
+    def __post_init__(self) -> None:
+        if self.attr and self.text:
+            raise ValueError("A field cannot be both an XML attribute and element text.")
+        if self.wrapper is not None and self.attr:
+            raise ValueError("Wrapper elements cannot be used on XML attributes.")
+        if self.wrapper is not None and self.text:
+            raise ValueError("Wrapper elements cannot be used on XML text.")
+        if self.tag == "":
+            raise ValueError("tag cannot be empty.")
+        if self.wrapper == "":
+            raise ValueError("wrapper cannot be empty.")
+
+    @property
+    def is_element(self) -> bool:
+        return not self.attr and not self.text
+
+    @property
+    def is_attribute(self) -> bool:
+        return self.attr
+
+    @property
+    def is_text(self) -> bool:
+        return self.text
+
+    @property
+    def is_wrapped(self) -> bool:
+        return self.wrapper is not None

msgspec_xml-0.1.0.dist-info/METADATA

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: msgspec-xml
+Version: 0.1.0
+Project-URL: Issues, https://codefloe.com/buriedincode/msgspec-xml/issues
+Project-URL: Source, https://codefloe.com/buriedincode/msgspec-xml
+Author-email: BuriedInCode <buriedincode@duckpond.nz>
+Maintainer-email: BuriedInCode <buriedincode@duckpond.nz>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: defusedxml>=0.7.0
+Requires-Dist: msgspec>=0.21.0
+Description-Content-Type: text/markdown
+
+# msgspec-xml

msgspec_xml-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+msgspec_xml/__init__.py,sha256=rac6RGVCax9JsQfc-BGa8gqdOUt4uuwXFK6bfwtlys4,172
+msgspec_xml/decoder.py,sha256=7YAjKcb5HQkU7tI5z04_aw4abPk0bi7lJEYGIFkWgzo,2419
+msgspec_xml/encoder.py,sha256=d1gxVPOvE-vG5RIu195Hc6KACp-GovDAQ7bALxy0uQU,2254
+msgspec_xml/introspection.py,sha256=pIQ4UklUhPb2S3AUIRkbX5uVCQnYd5P__Jr6ONVqnoE,2416
+msgspec_xml/metadata.py,sha256=gyZjzqaIN7EBrEv3k4Z8LJBAj30lVPQrcK3uqJAJJLY,1138
+msgspec_xml-0.1.0.dist-info/METADATA,sha256=j-dzqle5nsh97dgHASGCO7wealmojlJfHJW3UOKg4XI,1032
+msgspec_xml-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+msgspec_xml-0.1.0.dist-info/licenses/LICENSE,sha256=LQpab7RDZrnpwV_Sl0I9lET5A12-ERe84DWicEf9Fo8,1070
+msgspec_xml-0.1.0.dist-info/RECORD,,

msgspec_xml-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

msgspec_xml-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jonah Jackson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.