smithy-core 0.0.1__py3-none-any.whl

smithy_core/__init__.py

@@ -0,0 +1,141 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+import importlib.metadata
+from dataclasses import dataclass
+from enum import Enum
+from functools import cached_property
+from urllib.parse import urlunparse
+
+from . import interfaces, rfc3986
+from .exceptions import SmithyException
+
+__version__: str = importlib.metadata.version("smithy-core")
+
+
+class HostType(Enum):
+    """Enumeration of possible host types."""
+
+    IPv6 = "IPv6"
+    """Host is an IPv6 address."""
+
+    IPv4 = "IPv4"
+    """Host is an IPv4 address."""
+
+    DOMAIN = "DOMAIN"
+    """Host type is a domain name."""
+
+    UNKNOWN = "UNKNOWN"
+    """Host type is unknown."""
+
+
+@dataclass(kw_only=True, frozen=True)
+class URI(interfaces.URI):
+    """Universal Resource Identifier, target location for a :py:class:`HTTPRequest`."""
+
+    scheme: str = "https"
+    """For example ``http`` or ``https``."""
+
+    username: str | None = None
+    """Username part of the userinfo URI component."""
+
+    password: str | None = None
+    """Password part of the userinfo URI component."""
+
+    host: str
+    """The hostname, for example ``amazonaws.com``."""
+
+    port: int | None = None
+    """An explicit port number."""
+
+    path: str | None = None
+    """Path component of the URI."""
+
+    query: str | None = None
+    """Query component of the URI as string."""
+
+    fragment: str | None = None
+    """Part of the URI specification, but may not be transmitted by a client."""
+
+    def __post_init__(self) -> None:
+        """Validate host component."""
+        if not rfc3986.HOST_MATCHER.match(self.host) and not rfc3986.IPv6_MATCHER.match(
+            f"[{self.host}]"
+        ):
+            raise SmithyException(f"Invalid host: {self.host}")
+
+    @property
+    def netloc(self) -> str:
+        """Construct netloc string in format ``{username}:{password}@{host}:{port}``
+
+        ``username``, ``password``, and ``port`` are only included if set. ``password``
+        is ignored, unless ``username`` is also set. Add square brackets around the host
+        if it is a valid IPv6 endpoint URI per :rfc:`3986#section-3.2.2`.
+        """
+        return self._netloc
+
+    # cached_property does NOT behave like property, it actually allows for setting.
+    # Therefore we need a layer of indirection.
+    @cached_property
+    def _netloc(self) -> str:
+        if self.username is not None:
+            password = "" if self.password is None else f":{self.password}"
+            userinfo = f"{self.username}{password}@"
+        else:
+            userinfo = ""
+
+        if self.port is not None:
+            port = f":{self.port}"
+        else:
+            port = ""
+
+        if self.host_type == HostType.IPv6:
+            host = f"[{self.host}]"
+        else:
+            host = self.host
+
+        return f"{userinfo}{host}{port}"
+
+    @property
+    def host_type(self) -> HostType:
+        """Return the type of host."""
+        return self._host_type
+
+    @cached_property
+    def _host_type(self) -> HostType:
+        if rfc3986.IPv6_MATCHER.match(f"[{self.host}]"):
+            return HostType.IPv6
+        if rfc3986.IPv4_MATCHER.match(self.host):
+            return HostType.IPv4
+        if rfc3986.HOST_MATCHER.match(self.host):
+            return HostType.DOMAIN
+        return HostType.UNKNOWN
+
+    def build(self) -> str:
+        """Construct URI string representation.
+
+        Validate host. Returns a string of the form
+        ``{scheme}://{username}:{password}@{host}:{port}{path}?{query}#{fragment}``
+        """
+        components = (
+            self.scheme,
+            self.netloc,
+            self.path or "",
+            "",  # params
+            self.query,
+            self.fragment,
+        )
+        return urlunparse(components)
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, URI):
+            return False
+        return (
+            self.scheme == other.scheme
+            and self.host == other.host
+            and self.port == other.port
+            and self.path == other.path
+            and self.query == other.query
+            and self.username == other.username
+            and self.password == other.password
+            and self.fragment == other.fragment
+        )

smithy_core/aio/__init__.py

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

smithy_core/aio/endpoints.py

@@ -0,0 +1,21 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from typing import Any
+
+from ..endpoints import Endpoint, EndpointResolverParams, resolve_static_uri
+from ..exceptions import EndpointResolutionError
+from ..interfaces import Endpoint as _Endpoint
+from .interfaces import EndpointResolver
+
+
+class StaticEndpointResolver(EndpointResolver):
+    """A basic endpoint resolver that forwards a static URI."""
+
+    async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> _Endpoint:
+        static_uri = resolve_static_uri(params)
+        if static_uri is None:
+            raise EndpointResolutionError(
+                "Unable to resolve endpoint: endpoint_uri is required"
+            )
+
+        return Endpoint(uri=static_uri)

smithy_core/aio/eventstream.py

@@ -0,0 +1,233 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+from asyncio import Future
+from typing import Any, Self
+
+from ..deserializers import DeserializeableShape
+from ..serializers import SerializeableShape
+from .interfaces.eventstream import EventPublisher, EventReceiver
+
+
+class DuplexEventStream[
+    IE: SerializeableShape,
+    OE: DeserializeableShape,
+    O: DeserializeableShape,
+]:
+    """An event stream that both sends and receives messages.
+
+    To ensure that streams are closed upon exiting, this class may be used as an async
+    context manager.
+
+    .. code-block:: python
+
+        async def main():
+            client = ChatClient()
+            input = StreamMessagesInput(chat_room="aws-python-sdk", username="hunter7")
+
+            async with client.stream_messages(input=input) as stream:
+                stream.input_stream.send(
+                    MessageStreamMessage("Chat logger starting up.")
+                )
+                response_task = asyncio.create_task(handle_output(stream))
+                stream.input_stream.send(MessageStreamMessage("Chat logger active."))
+                await response_handler
+
+            async def handle_output(stream: EventStream) -> None:
+                _, output_stream = await stream.await_output()
+                async for event in output_stream:
+                    match event:
+                        case MessageStreamMessage():
+                            print(event.value)
+                        case MessageStreamShutdown():
+                            return
+                        case _:
+                            stream.input_stream.send(
+                                MessageStreamMessage(
+                                    "Unknown message type received. Shutting down."
+                                )
+                            )
+                            return
+    """
+
+    input_stream: EventPublisher[IE]
+    """An event stream that sends events to the service."""
+
+    output_stream: EventReceiver[OE] | None = None
+    """An event stream that receives events from the service.
+
+    This value may be None until ``await_output`` has been called.
+
+    This value will also be None if the operation has no output stream.
+    """
+
+    output: O | None = None
+    """The initial response from the service.
+
+    This value may be None until ``await_output`` has been called.
+
+    This may include context necessary to interpret output events or prepare
+    input events. It will always be available before any events.
+    """
+
+    def __init__(
+        self,
+        *,
+        input_stream: EventPublisher[IE],
+        output_future: Future[tuple[O, EventReceiver[OE]]],
+    ) -> None:
+        self.input_stream = input_stream
+        self._output_future = output_future
+
+    async def await_output(self) -> tuple[O, EventReceiver[OE]]:
+        """Await the operation's output.
+
+        The EventStream will be returned as soon as the input stream is ready to
+        receive events, which may be before the initial response has been received
+        and the service is ready to send events.
+
+        Awaiting this method will wait until the initial response was received and the
+        service is ready to send events. The initial response and output stream will
+        be returned by this operation and also cached in ``response`` and
+        ``output_stream``, respectively.
+
+        The default implementation of this method performs the caching behavior,
+        delegating to the abstract ``_await_output`` method to actually retrieve the
+        initial response and output stream.
+
+        :returns: A tuple containing the initial response and output stream. If the
+            operation has no output stream, the second value will be None.
+        """
+        self.output, self.output_stream = await self._output_future
+        return self.output, self.output_stream
+
+    async def close(self) -> None:
+        """Closes the event stream.
+
+        This closes both the input and output streams.
+        """
+        if self.output_stream is None:
+            _, self.output_stream = await self.await_output()
+
+        await self.input_stream.close()
+        await self.output_stream.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any):
+        await self.close()
+
+
+class InputEventStream[IE: SerializeableShape, O]:
+    """An event stream that streams messages to the service.
+
+    To ensure that streams are closed upon exiting, this class may be used as an async
+    context manager.
+
+    .. code-block:: python
+
+        async def main():
+            client = ChatClient()
+            input = PublishMessagesInput(chat_room="aws-python-sdk", username="hunter7")
+
+            async with client.publish_messages(input=input) as stream:
+                stream.input_stream.send(
+                    MessageStreamMessage("High severity ticket alert!")
+                )
+                await stream.await_output()
+    """
+
+    input_stream: EventPublisher[IE]
+    """An event stream that sends events to the service."""
+
+    output: O | None = None
+    """The initial response from the service.
+
+    This value may be None until ``await_output`` has been called.
+
+    This may include context necessary to interpret output events or prepare
+    input events. It will always be available before any events.
+    """
+
+    def __init__(
+        self,
+        *,
+        input_stream: EventPublisher[IE],
+        output_future: Future[O],
+    ) -> None:
+        self.input_stream = input_stream
+        self._output_future = output_future
+
+    async def await_output(self) -> O:
+        """Await the operation's initial response.
+
+        The EventStream will be returned as soon as the input stream is ready to receive
+        events, which may be before the initial response has been received and the
+        service is ready to send events.
+
+        Awaiting this method will wait until the initial response was received.
+
+        :returns: The service's initial response.
+        """
+        if self.output is None:
+            self.output = await self._output_future
+        return self.output
+
+    async def close(self) -> None:
+        """Closes the event stream."""
+        await self.input_stream.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any):
+        await self.close()
+
+
+class OutputEventStream[OE: DeserializeableShape, O: DeserializeableShape]:
+    """An event stream that streams messages from the service.
+
+    To ensure that streams are closed upon exiting, this class may be used as an async
+    context manager.
+
+    .. code-block:: python
+
+        async def main():
+            client = ChatClient()
+            input = ReceiveMessagesInput(chat_room="aws-python-sdk")
+
+            async with client.receive_messages(input=input) as stream:
+                async for event in stream.output_stream:
+                    match event:
+                        case MessageStreamMessage():
+                            print(event.value)
+                        case _:
+                            return
+    """
+
+    output_stream: EventReceiver[OE]
+    """An event stream that receives events from the service.
+
+    This value will also be None if the operation has no output stream.
+    """
+
+    output: O
+    """The initial response from the service.
+
+    This may include context necessary to interpret output events or prepare input
+    events. It will always be available before any events.
+    """
+
+    def __init__(self, output_stream: EventReceiver[OE], output: O) -> None:
+        self.output_stream = output_stream
+        self.output = output
+
+    async def close(self) -> None:
+        """Closes the event stream."""
+        await self.output_stream.close()
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any):
+        await self.close()

smithy_core/aio/interfaces/__init__.py

@@ -0,0 +1,200 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from collections.abc import AsyncIterable, Callable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+from ...documents import TypeRegistry
+from ...endpoints import EndpointResolverParams
+from ...exceptions import UnsupportedStreamException
+from ...interfaces import Endpoint, TypedProperties, URI
+from ...interfaces import StreamingBlob as SyncStreamingBlob
+from .eventstream import EventPublisher, EventReceiver
+
+if TYPE_CHECKING:
+    from ...deserializers import DeserializeableShape, ShapeDeserializer
+    from ...schemas import APIOperation
+    from ...serializers import SerializeableShape
+    from ...shapes import ShapeID
+
+
+@runtime_checkable
+class AsyncByteStream(Protocol):
+    """A file-like object with an async read method."""
+
+    async def read(self, size: int = -1) -> bytes: ...
+
+
+@runtime_checkable
+class AsyncWriter(Protocol):
+    """An object with an async write method."""
+
+    async def write(self, data: bytes) -> None: ...
+
+
+# A union of all acceptable streaming blob types. Deserialized payloads will
+# always return a ByteStream, or AsyncByteStream if async is enabled.
+type StreamingBlob = SyncStreamingBlob | AsyncByteStream | AsyncIterable[bytes]
+
+
+class Request(Protocol):
+    """Protocol-agnostic representation of a request."""
+
+    destination: URI
+    """The URI where the request should be sent to."""
+
+    body: StreamingBlob = b""
+    """The request payload."""
+
+    async def consume_body_async(self) -> bytes:
+        """Iterate over request body and return as bytes."""
+        ...
+
+    def consume_body(self) -> bytes:
+        """Iterate over request body and return as bytes."""
+        ...
+
+
+class Response(Protocol):
+    """Protocol-agnostic representation of a response."""
+
+    @property
+    def body(self) -> StreamingBlob:
+        """The response payload as iterable of chunks of bytes."""
+        ...
+
+    async def consume_body_async(self) -> bytes:
+        """Iterate over response body and return as bytes."""
+        ...
+
+    def consume_body(self) -> bytes:
+        """Iterate over request body and return as bytes."""
+        ...
+
+
+class EndpointResolver(Protocol):
+    """Resolves an operation's endpoint based given parameters."""
+
+    async def resolve_endpoint(self, params: EndpointResolverParams[Any]) -> Endpoint:
+        """Resolve an endpoint for the given operation.
+
+        :param params: The parameters available to resolve the endpoint.
+        """
+        ...
+
+
+class ClientTransport[I: Request, O: Response](Protocol):
+    """Protocol-agnostic representation of a client tranport (e.g. an HTTP client)."""
+
+    async def send(self, request: I) -> O:
+        """Send a request over the transport and receive the response."""
+        ...
+
+
+class ClientProtocol[I: Request, O: Response](Protocol):
+    """A protocol used by a client to communicate with a server."""
+
+    @property
+    def id(self) -> "ShapeID":
+        """The ID of the protocol."""
+        ...
+
+    def serialize_request[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+    ](
+        self,
+        *,
+        operation: "APIOperation[OperationInput, OperationOutput]",
+        input: OperationInput,
+        endpoint: URI,
+        context: TypedProperties,
+    ) -> I:
+        """Serialize an operation input into a transport request.
+
+        :param operation: The operation whose request is being serialized.
+        :param input: The input shape to be serialized.
+        :param endpoint: The base endpoint to serialize.
+        :param context: A context bag for the request.
+        """
+        ...
+
+    def set_service_endpoint(
+        self,
+        *,
+        request: I,
+        endpoint: Endpoint,
+    ) -> I:
+        """Update the endpoint of a transport request.
+
+        :param request: The request whose endpoint should be updated.
+        :param endpoint: The endpoint to set on the request.
+        """
+        ...
+
+    async def deserialize_response[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+    ](
+        self,
+        *,
+        operation: "APIOperation[OperationInput, OperationOutput]",
+        request: I,
+        response: O,
+        error_registry: TypeRegistry,
+        context: TypedProperties,
+    ) -> OperationOutput:
+        """Deserializes the output from the tranport response or throws an exception.
+
+        :param operation: The operation whose response is being deserialized.
+        :param request: The transport request that was sent for this response.
+        :param response: The response to deserialize.
+        :param error_registry: A TypeRegistry used to deserialize errors.
+        :param context: A context bag for the request.
+        """
+        ...
+
+    def create_event_publisher[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+        Event: "SerializeableShape",
+    ](
+        self,
+        *,
+        operation: "APIOperation[OperationInput, OperationOutput]",
+        request: I,
+        event_type: type[Event],
+        context: TypedProperties,
+    ) -> EventPublisher[Event]:
+        """Creates an event publisher for a protocol event stream.
+
+        :param operation: The event stream operation.
+        :param request: The transport request that was sent for this stream.
+        :param event_type: The type of event to publish.
+        :param context: A context bag for the request.
+        """
+        raise UnsupportedStreamException()
+
+    def create_event_receiver[
+        OperationInput: "SerializeableShape",
+        OperationOutput: "DeserializeableShape",
+        Event: "DeserializeableShape",
+    ](
+        self,
+        *,
+        operation: "APIOperation[OperationInput, OperationOutput]",
+        request: I,
+        response: O,
+        event_type: type[Event],
+        event_deserializer: Callable[["ShapeDeserializer"], Event],
+        context: TypedProperties,
+    ) -> EventReceiver[Event]:
+        """Creates an event receiver for a protocol event stream.
+
+        :param operation: The event stream operation.
+        :param request: The transport request that was sent for this stream.
+        :param response: The transport response that was received for this stream.
+        :param event_type: The type of event to publish.
+        :param event_deserializer: The deserializer to be used to deserialize events.
+        :param context: A context bag for the request.
+        """
+        raise UnsupportedStreamException()

smithy_core/aio/interfaces/eventstream.py

@@ -0,0 +1,69 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0
+from typing import Any, Protocol, Self
+
+from ...deserializers import DeserializeableShape
+from ...serializers import SerializeableShape
+
+
+class EventPublisher[E: SerializeableShape](Protocol):
+    """Asynchronously sends events to a service.
+
+    This may be used as a context manager to ensure the stream is closed before exiting.
+    """
+
+    async def send(self, event: E) -> None:
+        """Sends an event to the service.
+
+        :param event: The event to send.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Closes the event stream."""
+        ...
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc_value: Any, traceback: Any):
+        await self.close()
+
+
+class EventReceiver[E: DeserializeableShape](Protocol):
+    """Asynchronously receives events from a service.
+
+    Events may be received via the ``receive`` method or by using this class as
+    an async iterable.
+
+    This may also be used as a context manager to ensure the stream is closed before
+    exiting.
+    """
+
+    async def receive(self) -> E | None:
+        """Receive a single event from the service.
+
+        :returns: An event or None. None indicates that no more events will be sent by
+            the service.
+        """
+        ...
+
+    async def close(self) -> None:
+        """Closes the event stream."""
+        ...
+
+    async def __anext__(self) -> E:
+        result = await self.receive()
+        if result is None:
+            await self.close()
+            raise StopAsyncIteration
+        return result
+
+    def __aiter__(self) -> Self:
+        return self
+
+    async def __enter__(self) -> Self:
+        return self
+
+    async def __exit__(self, exc_type: Any, exc_value: Any, traceback: Any):
+        await self.close()

smithy_core/aio/interfaces/identity.py

@@ -0,0 +1,22 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from typing import Protocol
+
+from ...interfaces.identity import IdentityPropertiesType_contra, IdentityType_cov
+
+
+class IdentityResolver(Protocol[IdentityType_cov, IdentityPropertiesType_contra]):
+    """Used to load a user's `Identity` from a given source.
+
+    Each `Identity` may have one or more resolver implementations.
+    """
+
+    async def get_identity(
+        self, *, identity_properties: IdentityPropertiesType_contra
+    ) -> IdentityType_cov:
+        """Load the user's identity from this resolver.
+
+        :param identity_properties: Properties used to help determine the identity to
+            return.
+        """
+        ...