Add HTTP Traits

Author: JordonPhillips

packages/smithy-core/src/smithy_core/traits.py

@@ -7,11 +7,11 @@
 # they're correct regardless, so it's okay if the checks are stripped out.
 # ruff: noqa: S101
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from enum import Enum
-from typing import TYPE_CHECKING, ClassVar
+from typing import TYPE_CHECKING, ClassVar, Mapping
 
-from .types import TimestampFormat
+from .types import TimestampFormat, PathPattern
 from .shapes import ShapeID
 
 if TYPE_CHECKING:
@@ -193,3 +193,117 @@ def __post_init__(self):
     @property
     def value(self) -> str:
         return self.document_value  # type: ignore
+
+
+# TODO: Get all this moved over to the http package
+@dataclass(init=False, frozen=True)
+class HTTPTrait(Trait, id=ShapeID("smithy.api#http")):
+    path: PathPattern = field(repr=False, hash=False, compare=False)
+    code: int = field(repr=False, hash=False, compare=False)
+    query: str | None = field(default=None, repr=False, hash=False, compare=False)
+
+    def __init__(self, value: "DocumentValue | DynamicTrait" = None):
+        super().__init__(value)
+        assert isinstance(self.document_value, Mapping)
+        assert isinstance(self.document_value["method"], str)
+
+        code = self.document_value.get("code", 200)
+        assert isinstance(code, int)
+        object.__setattr__(self, "code", code)
+
+        uri = self.document_value["uri"]
+        assert isinstance(uri, str)
+        parts = uri.split("?", 1)
+
+        object.__setattr__(self, "path", PathPattern(parts[0]))
+        object.__setattr__(self, "query", parts[1] if len(parts) == 2 else None)
+
+    @property
+    def method(self) -> str:
+        return self.document_value["method"]  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HTTPErrorTrait(Trait, id=ShapeID("smithy.api#httpError")):
+    def __post_init__(self):
+        assert isinstance(self.document_value, int)
+
+    @property
+    def code(self) -> int:
+        return self.document_value  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HTTPHeaderTrait(Trait, id=ShapeID("smithy.api#httpHeader")):
+    def __post_init__(self):
+        assert isinstance(self.document_value, str)
+
+    @property
+    def key(self) -> str:
+        return self.document_value  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HTTPLabelTrait(Trait, id=ShapeID("smithy.api#httpLabel")):
+    def __post_init__(self):
+        assert self.document_value is None
+
+
+@dataclass(init=False, frozen=True)
+class HTTPPayloadTrait(Trait, id=ShapeID("smithy.api#httpPayload")):
+    def __post_init__(self):
+        assert self.document_value is None
+
+
+@dataclass(init=False, frozen=True)
+class HTTPPrefixHeadersTrait(Trait, id=ShapeID("smithy.api#httpPrefixHeaders")):
+    def __post_init__(self):
+        assert isinstance(self.document_value, str)
+
+    @property
+    def prefix(self) -> str:
+        return self.document_value  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HTTPQueryTrait(Trait, id=ShapeID("smithy.api#httpQuery")):
+    def __post_init__(self):
+        assert isinstance(self.document_value, str)
+
+    @property
+    def name(self) -> str:
+        return self.document_value  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HTTPQueryParamsTrait(Trait, id=ShapeID("smithy.api#httpQueryParams")):
+    def __post_init__(self):
+        assert self.document_value is None
+
+
+@dataclass(init=False, frozen=True)
+class HTTPResponseCodeTrait(Trait, id=ShapeID("smithy.api#httpResponseCode")):
+    def __post_init__(self):
+        assert self.document_value is None
+
+
+@dataclass(init=False, frozen=True)
+class HTTPChecksumRequiredTrait(Trait, id=ShapeID("smithy.api#httpChecksumRequired")):
+    def __post_init__(self):
+        assert self.document_value is None
+
+
+@dataclass(init=False, frozen=True)
+class EndpointTrait(Trait, id=ShapeID("smithy.api#endpoint")):
+    def __post_init__(self):
+        assert isinstance(self.document_value, str)
+
+    @property
+    def host_prefix(self) -> str:
+        return self.document_value["hostPrefix"]  # type: ignore
+
+
+@dataclass(init=False, frozen=True)
+class HostLabelTrait(Trait, id=ShapeID("smithy.api#hostLabel")):
+    def __post_init__(self):
+        assert self.document_value is None

packages/smithy-core/src/smithy_core/types.py

@@ -1,11 +1,13 @@
 #  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 #  SPDX-License-Identifier: Apache-2.0
 import json
+import re
 from collections.abc import Mapping, Sequence
 from datetime import datetime
 from email.utils import format_datetime, parsedate_to_datetime
 from enum import Enum
 from typing import Any
+from dataclasses import dataclass
 
 from .exceptions import ExpectationNotMetException
 from .utils import (
@@ -16,6 +18,8 @@
     serialize_rfc3339,
 )
 
+_GREEDY_LABEL_RE = re.compile(r"\{(\w+)\+\}")
+
 type Document = (
     Mapping[str, "Document"] | Sequence["Document"] | str | int | float | bool | None
 )
@@ -111,3 +115,41 @@ def deserialize(self, value: str | float) -> datetime:
                 return ensure_utc(parsedate_to_datetime(expect_type(str, value)))
             case TimestampFormat.DATE_TIME:
                 return ensure_utc(datetime.fromisoformat(expect_type(str, value)))
+
+
+@dataclass(init=False, frozen=True)
+class PathPattern:
+    """A formattable URI path pattern.
+
+    The pattern may contain formattlable labels, which may be normal labels or greedy
+    labels. Normal labels forbid path separators, greedy labels allow them.
+    """
+
+    pattern: str
+    """The path component of the URI which is a formattable string."""
+
+    greedy_labels: set[str]
+    """The pattern labels whose values may contain path separators."""
+
+    def __init__(self, pattern: str) -> None:
+        object.__setattr__(self, "pattern", pattern)
+        object.__setattr__(
+            self, "greedy_labels", set(_GREEDY_LABEL_RE.findall(pattern))
+        )
+
+    def format(self, *args: object, **kwargs: str) -> str:
+        if args:
+            raise ValueError("PathPattern formatting requires only keyword arguments.")
+
+        for key, value in kwargs.items():
+            if "/" in value and key not in self.greedy_labels:
+                raise ValueError(
+                    'Non-greedy labels must not contain path separators ("/").'
+                )
+
+        result = self.pattern.replace("+}", "}").format(**kwargs)
+        if "//" in result:
+            raise ValueError(
+                f'Path must not contain empty segments, but was "{result}".'
+            )
+        return result

packages/smithy-core/tests/unit/test_types.py

@@ -7,7 +7,7 @@
 import pytest
 
 from smithy_core.exceptions import ExpectationNotMetException
-from smithy_core.types import JsonBlob, JsonString, TimestampFormat
+from smithy_core.types import JsonBlob, JsonString, TimestampFormat, PathPattern
 
 
 def test_json_string() -> None:
@@ -180,3 +180,42 @@ def test_invalid_timestamp_format_type_raises(
 ):
     with pytest.raises(ExpectationNotMetException):
         format.deserialize(value)
+
+
+def test_path_pattern_without_labels():
+    assert PathPattern("/foo/").format() == "/foo/"
+
+
+def test_path_pattern_with_normal_label():
+    assert PathPattern("/{foo}/").format(foo="foo") == "/foo/"
+
+
+def test_path_pattern_with_greedy_label():
+    assert PathPattern("/{foo+}/").format(foo="foo") == "/foo/"
+
+
+def test_path_pattern_greedy_label_allows_path_sep():
+    assert PathPattern("/{foo+}/").format(foo="foo/bar") == "/foo/bar/"
+
+
+def test_path_pattern_normal_label_disallows_path_sep():
+    with pytest.raises(ValueError):
+        PathPattern("/{foo}").format(foo="foo/bar")
+
+
+@pytest.mark.parametrize(
+    "greedy, value",
+    [
+        (False, ""),
+        (True, ""),
+        (True, "/"),
+        (True, "/foo"),
+        (True, "foo/"),
+        (True, "/foo/"),
+        (True, "foo//bar"),
+    ],
+)
+def test_path_pattern_disallows_empty_segments(greedy: bool, value: str):
+    pattern = PathPattern("/{foo+}/" if greedy else "/{foo}/")
+    with pytest.raises(ValueError):
+        pattern.format(foo=value)