smithy-xml 0.1.0__tar.gz

smithy_xml-0.1.0/.changes/0.1.0.json

@@ -0,0 +1,8 @@
+{
+  "changes": [
+    {
+      "type": "feature",
+      "description": "Added initial support for XML deserialization in Smithy clients."
+    }
+  ]
+}

smithy_xml-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Eclipse
+.classpath
+.project
+.settings/
+
+# Intellij
+.idea/
+*.iml
+*.iws
+
+# VS Code
+.vscode/
+
+# Mac
+.DS_Store
+
+# Maven
+target/
+**/dependency-reduced-pom.xml
+
+# Gradle
+**/.gradle
+build/
+*/out/
+**/*/out/
+
+# Python
+__pycache__
+*.swp
+.mypy_cache
+.coverage
+coverage.xml
+htmlcov
+*.egg-info
+dist
+.venv

smithy_xml-0.1.0/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## v0.1.0
+
+### Features
+* Added initial support for XML deserialization in Smithy clients.

smithy_xml-0.1.0/NOTICE

@@ -0,0 +1 @@
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.

smithy_xml-0.1.0/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: smithy-xml
+Version: 0.1.0
+Summary: XML serialization and deserialization support for Smithy tooling.
+Project-URL: Changelog, https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-xml/CHANGELOG.md
+Project-URL: Code, https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-xml/
+Project-URL: Issue tracker, https://github.com/smithy-lang/smithy-python/issues
+Author: Amazon Web Services
+License: Apache License 2.0
+License-File: NOTICE
+Keywords: sdk,smithy,xml
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: smithy-core
+Description-Content-Type: text/markdown
+
+# smithy-xml
+
+This package provides generic XML serialization and deserialization support
+for Smithy clients and servers.

smithy_xml-0.1.0/README.md

@@ -0,0 +1,4 @@
+# smithy-xml
+
+This package provides generic XML serialization and deserialization support
+for Smithy clients and servers.

smithy_xml-0.1.0/pyproject.toml

@@ -0,0 +1,50 @@
+[project]
+name = "smithy-xml"
+dynamic = ["version"]
+requires-python = ">=3.12"
+authors = [
+  {name = "Amazon Web Services"},
+]
+description = "XML serialization and deserialization support for Smithy tooling."
+readme = "README.md"
+license = {text = "Apache License 2.0"}
+keywords = ["smithy", "sdk", "xml"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Natural Language :: English",
+  "License :: OSI Approved :: Apache Software License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Topic :: Software Development :: Libraries"
+]
+dependencies = [
+    "smithy-core",
+]
+
+[project.urls]
+"Changelog" = "https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-xml/CHANGELOG.md"
+"Code" = "https://github.com/smithy-lang/smithy-python/blob/develop/packages/smithy-xml/"
+"Issue tracker" = "https://github.com/smithy-lang/smithy-python/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+path = "src/smithy_xml/__init__.py"
+
+[tool.hatch.build]
+exclude = [
+  "tests",
+]
+
+[tool.ruff]
+src = ["src"]

smithy_xml-0.1.0/src/smithy_xml/__init__.py

@@ -0,0 +1,65 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+
+from io import BytesIO
+from xml.etree.ElementTree import iterparse
+
+from smithy_core.codecs import Codec
+from smithy_core.deserializers import ShapeDeserializer
+from smithy_core.interfaces import BytesReader, BytesWriter
+from smithy_core.serializers import ShapeSerializer
+from smithy_core.types import TimestampFormat
+
+from ._private.deserializers import XMLShapeDeserializer as _XMLShapeDeserializer
+from ._private.readers import XMLEventReader as _XMLEventReader
+from .settings import XMLSettings
+
+__version__ = "0.1.0"
+__all__ = ("XMLCodec", "XMLSettings")
+
+
+class XMLCodec(Codec):
+    """A codec for converting shapes to/from XML."""
+
+    def __init__(
+        self,
+        use_timestamp_format: bool = True,
+        default_timestamp_format: TimestampFormat = TimestampFormat.DATE_TIME,
+        default_namespace: str | None = None,
+    ) -> None:
+        """Initializes an XMLCodec.
+
+        :param use_timestamp_format: Whether the codec should use the
+            `smithy.api#timestampFormat` trait, if present.
+        :param default_timestamp_format: The default timestamp format to use if the
+            `smithy.api#timestampFormat` trait is not enabled or not present.
+        :param default_namespace: Default XML namespace (`xmlns`) applied to the root
+            element during serialization.
+        """
+        self._settings = XMLSettings(
+            use_timestamp_format=use_timestamp_format,
+            default_timestamp_format=default_timestamp_format,
+            default_namespace=default_namespace,
+        )
+
+    @property
+    def media_type(self) -> str:
+        return "application/xml"
+
+    def create_serializer(self, sink: BytesWriter) -> ShapeSerializer:
+        raise NotImplementedError("XML serialization is not supported")
+
+    def create_deserializer(
+        self,
+        source: bytes | BytesReader,
+        *,
+        wrapper_elements: tuple[str, ...] = (),
+    ) -> ShapeDeserializer:
+        if isinstance(source, bytes):
+            source = BytesIO(source)
+        reader = _XMLEventReader(
+            iterparse(source, events=("start", "end"))  # noqa: S314
+        )
+        return _XMLShapeDeserializer(
+            settings=self._settings, reader=reader, wrapper_elements=wrapper_elements
+        )

smithy_xml-0.1.0/src/smithy_xml/_private/__init__.py

@@ -0,0 +1,2 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0

smithy_xml-0.1.0/src/smithy_xml/_private/deserializers.py

@@ -0,0 +1,380 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+
+import datetime
+from base64 import b64decode
+from collections.abc import Callable
+from decimal import Decimal
+from xml.etree.ElementTree import Element
+
+from smithy_core.deserializers import ShapeDeserializer, SpecificShapeDeserializer
+from smithy_core.documents import Document
+from smithy_core.exceptions import SmithyError
+from smithy_core.schemas import Schema
+from smithy_core.shapes import ShapeID, ShapeType
+from smithy_core.traits import (
+    TimestampFormatTrait,
+    XMLAttributeTrait,
+    XMLFlattenedTrait,
+    XMLNameTrait,
+)
+
+from ..settings import XMLSettings
+from .readers import XMLEvent, XMLEventReader
+
+
+def _local_name(tag: str) -> str:
+    """Strip namespace URI from an element tag: {uri}local -> local."""
+    if tag.startswith("{"):
+        return tag.split("}", 1)[1]
+    return tag
+
+
+def _expected_root_name(schema: Schema) -> str | None:
+    """Get the expected root element name for root validation."""
+    if schema.shape_type not in (ShapeType.STRUCTURE, ShapeType.UNION):
+        return None
+    if xml_name := schema.get_trait(XMLNameTrait):
+        return xml_name.value
+    return schema.id.name
+
+
+def _validate_element_name(expected: str, elem: Element) -> None:
+    """Raise XMLParseError if the element's local name doesn't match expected."""
+    found = _local_name(elem.tag)
+    if found != expected:
+        raise XMLParseError(f"Expected element '{expected}', got '{found}'")
+
+
+def _xml_member_name(member_schema: Schema) -> str:
+    """Get the XML element name for a member, respecting @xmlName."""
+    if xml_name := member_schema.get_trait(XMLNameTrait):
+        return xml_name.value
+    return member_schema.expect_member_name()
+
+
+def _parse_xml_float(text: str) -> float:
+    """Parse an XML float string, handling NaN and Infinity."""
+    match text:
+        case "NaN":
+            return float("nan")
+        case "Infinity":
+            return float("inf")
+        case "-Infinity":
+            return float("-inf")
+        case _:
+            return float(text)
+
+
+class XMLParseError(SmithyError):
+    def __init__(self, message: str) -> None:
+        super().__init__(f"Error parsing XML: {message}")
+
+
+class XMLShapeDeserializer(ShapeDeserializer):
+    """Deserializer that reads XML from a streaming pull parser."""
+
+    def __init__(
+        self,
+        settings: XMLSettings,
+        reader: XMLEventReader,
+        wrapper_elements: tuple[str, ...] = (),
+    ) -> None:
+        self._settings = settings
+        self._reader = reader
+        self._is_root = not bool(wrapper_elements)
+        self._xml_names: dict[ShapeID, dict[str, Schema]] = {}
+        self._preconsumed_start: Element | None = None
+
+        # Wrapper elements are protocol transport containers (e.g. awsQuery's
+        # <OpResponse><OpResult>). The last wrapper's start element is kept
+        # so that the next read can reuse it.
+        for wrapper in wrapper_elements:
+            event = next(self._reader)
+            if event.type != "start":
+                raise XMLParseError(f"Expected start element, got '{event.type}'")
+            _validate_element_name(wrapper, event.elem)
+            self._preconsumed_start = event.elem
+
+    def is_null(self) -> bool:
+        return False
+
+    def read_null(self) -> None:
+        return None
+
+    def read_boolean(self, schema: Schema) -> bool:
+        text = self._read_text()
+        match text:
+            case "true":
+                return True
+            case "false":
+                return False
+            case _:
+                raise XMLParseError(f"Expected 'true' or 'false', got '{text}'")
+
+    def read_blob(self, schema: Schema) -> bytes:
+        return b64decode(self._read_text())
+
+    def read_integer(self, schema: Schema) -> int:
+        return int(self._read_text())
+
+    def read_float(self, schema: Schema) -> float:
+        return _parse_xml_float(self._read_text())
+
+    def read_big_decimal(self, schema: Schema) -> Decimal:
+        return Decimal(self._read_text())
+
+    def read_string(self, schema: Schema) -> str:
+        return self._read_text()
+
+    def read_document(self, schema: Schema) -> Document:
+        raise NotImplementedError("XML does not support document types")
+
+    def read_timestamp(self, schema: Schema) -> datetime.datetime:
+        format = self._settings.default_timestamp_format
+        if self._settings.use_timestamp_format:
+            if format_trait := schema.get_trait(TimestampFormatTrait):
+                format = format_trait.format
+
+        text = self._read_text()
+        return format.deserialize(text)
+
+    def read_struct(
+        self,
+        schema: Schema,
+        consumer: Callable[[Schema, "ShapeDeserializer"], None],
+    ) -> None:
+        xml_names = self._get_xml_names(schema)
+        start_from_wrapper = self._preconsumed_start is not None
+        start_elem = self._consume_start_event()
+        if self._is_root:
+            self._is_root = False
+            expected = _expected_root_name(schema)
+            if expected is not None:
+                _validate_element_name(expected, start_elem)
+
+        # Wrapper elements are protocol transport containers, not modeled structs,
+        # so their attributes cannot be deserialized as struct members.
+        if not start_from_wrapper:
+            for member_schema in schema.members.values():
+                if member_schema.get_trait(XMLAttributeTrait) is None:
+                    continue
+                expected_attr_name = _xml_member_name(member_schema)
+                for attr_name, attr_value in start_elem.attrib.items():
+                    attr_local_name = _local_name(attr_name)
+                    if attr_local_name == expected_attr_name:
+                        consumer(
+                            member_schema,
+                            _AttributeDeserializer(attr_value, self._settings),
+                        )
+                        break
+
+        # Flattened members lack an enclosing element, so there is no way to
+        # know when all items have been parsed. Their events are collected
+        # during iteration and replayed through a bounded reader afterwards.
+        flattened_buffers: dict[str, list[XMLEvent]] = {}
+        flattened_names = {
+            xml_name: member_schema
+            for xml_name, member_schema in xml_names.items()
+            if member_schema.get_trait(XMLFlattenedTrait) is not None
+        }
+
+        while self._reader.peek().type != "end":
+            tag = _local_name(self._reader.peek().elem.tag)
+
+            if tag in flattened_names:
+                flattened_buffers.setdefault(tag, []).extend(self._buffer_element())
+            elif tag in xml_names:
+                consumer(xml_names[tag], self)
+            else:
+                # Skip unknown tag
+                self._consume_start_event()
+                self._skip_to_end()
+
+        next(self._reader)
+
+        for tag, events in flattened_buffers.items():
+            member_schema = flattened_names[tag]
+            buffered_de = XMLShapeDeserializer(
+                self._settings,
+                XMLEventReader(iter(events)),
+            )
+            consumer(member_schema, buffered_de)
+
+    def read_list(
+        self,
+        schema: Schema,
+        consumer: Callable[["ShapeDeserializer"], None],
+    ) -> None:
+        is_flattened = schema.get_trait(XMLFlattenedTrait) is not None
+        if not is_flattened:
+            self._consume_start_event()
+            while self._reader.peek().type != "end":
+                consumer(self)
+        else:
+            while self._reader.has_next():
+                consumer(self)
+
+        if not is_flattened:
+            next(self._reader)
+
+    def read_map(
+        self,
+        schema: Schema,
+        consumer: Callable[[str, "ShapeDeserializer"], None],
+    ) -> None:
+        is_flattened = schema.get_trait(XMLFlattenedTrait) is not None
+        key_schema = schema.members["key"]
+        value_schema = schema.members["value"]
+        key_tag = _xml_member_name(key_schema)
+        value_tag = _xml_member_name(value_schema)
+
+        if not is_flattened:
+            self._consume_start_event()
+            while self._reader.peek().type != "end":
+                self._read_map_entry(key_tag, value_tag, consumer)
+        else:
+            while self._reader.has_next():
+                self._read_map_entry(key_tag, value_tag, consumer)
+
+        if not is_flattened:
+            next(self._reader)
+
+    def _read_text(self) -> str:
+        """Consume a complete element (start through end) and return its text."""
+        elem = self._consume_start_event()
+        self._skip_to_end()
+        # elem.text is populated only after consuming the "end" event
+        return elem.text or ""
+
+    def _consume_start_event(self) -> Element:
+        """Consume and return the next start element.
+
+        If a start element was pre-consumed (e.g. from consuming wrapper elements),
+        it is returned first and cleared.
+        """
+        if self._preconsumed_start is not None:
+            elem = self._preconsumed_start
+            self._preconsumed_start = None
+            return elem
+        event = next(self._reader)
+        if event.type != "start":
+            raise XMLParseError(f"Expected start element, got '{event.type}'")
+        return event.elem
+
+    def _skip_to_end(self) -> None:
+        """Skip to the matching end event. Assumes start was already consumed."""
+        depth = 1
+        while depth > 0:
+            event = next(self._reader)
+            if event.type == "start":
+                depth += 1
+            elif event.type == "end":
+                depth -= 1
+
+    def _buffer_element(self) -> list[XMLEvent]:
+        """Buffer a complete element's events (start through matching end)."""
+        events: list[XMLEvent] = []
+        event = next(self._reader)
+        events.append(event)
+        depth = 1
+        while depth > 0:
+            event = next(self._reader)
+            events.append(event)
+            if event.type == "start":
+                depth += 1
+            elif event.type == "end":
+                depth -= 1
+        return events
+
+    def _get_xml_names(self, schema: Schema) -> dict[str, Schema]:
+        """Get or build the XML element name -> member schema mapping for a shape."""
+        if schema.id in self._xml_names:
+            return self._xml_names[schema.id]
+        result: dict[str, Schema] = {}
+        for member_schema in schema.members.values():
+            if member_schema.get_trait(XMLAttributeTrait) is not None:
+                continue
+            xml_name = _xml_member_name(member_schema)
+            result[xml_name] = member_schema
+        self._xml_names[schema.id] = result
+        return result
+
+    def _read_map_entry(
+        self,
+        key_tag: str,
+        value_tag: str,
+        consumer: Callable[[str, "ShapeDeserializer"], None],
+    ) -> None:
+        """Read one map entry element and emit key/value pairs via consumer."""
+        self._consume_start_event()
+
+        key: str | None = None
+        while self._reader.peek().type != "end":
+            child_tag = _local_name(self._reader.peek().elem.tag)
+            if child_tag == key_tag:
+                key = self._read_text()
+            elif child_tag == value_tag:
+                if key is None:
+                    raise XMLParseError(
+                        "Map key element must appear before value element"
+                    )
+                consumer(key, self)
+            else:
+                # Skip unknown child tag
+                self._consume_start_event()
+                self._skip_to_end()
+
+        next(self._reader)
+
+
+class _AttributeDeserializer(SpecificShapeDeserializer):
+    """Deserializer for a value extracted from an XML attribute string."""
+
+    def __init__(self, value: str, settings: XMLSettings) -> None:
+        self._value = value
+        self._settings = settings
+
+    def read_string(self, schema: Schema) -> str:
+        return self._value
+
+    def read_boolean(self, schema: Schema) -> bool:
+        match self._value:
+            case "true":
+                return True
+            case "false":
+                return False
+            case _:
+                raise XMLParseError(f"Expected 'true' or 'false', got '{self._value}'")
+
+    def read_byte(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_short(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_integer(self, schema: Schema) -> int:
+        return int(self._value)
+
+    def read_long(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_big_integer(self, schema: Schema) -> int:
+        return self.read_integer(schema)
+
+    def read_float(self, schema: Schema) -> float:
+        return _parse_xml_float(self._value)
+
+    def read_double(self, schema: Schema) -> float:
+        return self.read_float(schema)
+
+    def read_big_decimal(self, schema: Schema) -> Decimal:
+        return Decimal(self._value)
+
+    def read_timestamp(self, schema: Schema) -> datetime.datetime:
+        format = self._settings.default_timestamp_format
+        if self._settings.use_timestamp_format:
+            if format_trait := schema.get_trait(TimestampFormatTrait):
+                format = format_trait.format
+
+        return format.deserialize(self._value)

smithy_xml-0.1.0/src/smithy_xml/_private/readers.py

@@ -0,0 +1,55 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+
+from collections.abc import Iterator
+from typing import NamedTuple
+from xml.etree.ElementTree import Element
+
+
+class XMLEvent(NamedTuple):
+    type: str
+    elem: Element
+
+
+class XMLEventReader:
+    """Buffered iterator over XML pull parser events with peek support.
+
+    Wraps an iterator of ``(event, element)`` tuples — either from
+    ``iterparse`` (streaming from a byte source) or from an in-memory list
+    (for flattened member replay).
+    """
+
+    def __init__(self, events: Iterator[tuple[str, Element] | XMLEvent]) -> None:
+        self._iter = events
+        self._pending: XMLEvent | None = None
+
+    def __iter__(self):
+        return self
+
+    def __next__(self) -> XMLEvent:
+        if self._pending is not None:
+            result = self._pending
+            self._pending = None
+            return result
+        return self._next()
+
+    def _next(self) -> XMLEvent:
+        event = next(self._iter)
+        if isinstance(event, XMLEvent):
+            return event
+        event_type, elem = event
+        return XMLEvent(event_type, elem)
+
+    def has_next(self) -> bool:
+        if self._pending is not None:
+            return True
+        try:
+            self._pending = self._next()
+            return True
+        except StopIteration:
+            return False
+
+    def peek(self) -> XMLEvent:
+        if self._pending is None:
+            self._pending = self._next()
+        return self._pending

smithy_xml-0.1.0/src/smithy_xml/py.typed

@@ -0,0 +1 @@
+Marker

smithy_xml-0.1.0/src/smithy_xml/settings.py

@@ -0,0 +1,20 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from dataclasses import dataclass
+
+from smithy_core.types import TimestampFormat
+
+
+@dataclass(slots=True)
+class XMLSettings:
+    """Settings for the XML codec."""
+
+    use_timestamp_format: bool = True
+    """Whether the codec should use the `smithy.api#timestampFormat` trait, if present."""
+
+    default_timestamp_format: TimestampFormat = TimestampFormat.DATE_TIME
+    """The default timestamp format to use if the `smithy.api#timestampFormat` trait is
+    not enabled or not present."""
+
+    default_namespace: str | None = None
+    """Default XML namespace (`xmlns`) applied to the root element during serialization."""