smithy-http 0.0.1__py3-none-any.whl

smithy_http/interceptors/user_agent.py

@@ -0,0 +1,153 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+import platform
+from typing import Any, Self
+
+import smithy_core
+from smithy_core.interceptors import InputContext, Interceptor, RequestContext
+from smithy_core.types import PropertyKey
+
+from smithy_http import Field
+from smithy_http.aio.interfaces import HTTPRequest
+from smithy_http.user_agent import UserAgent, UserAgentComponent
+
+USER_AGENT = PropertyKey(key="user_agent", value_type=UserAgent)
+
+
+class UserAgentInterceptor(Interceptor[Any, Any, HTTPRequest, None]):
+    """Adds interceptors that initialize UserAgent in the context and add the user-agent
+    header."""
+
+    def read_before_execution(self, context: InputContext[Any]) -> None:
+        context.properties[USER_AGENT] = _UserAgentBuilder.from_environment().build()
+
+    def modify_before_signing(
+        self, context: RequestContext[Any, HTTPRequest]
+    ) -> HTTPRequest:
+        user_agent = context.properties[USER_AGENT]
+        request = context.transport_request
+        request.fields.set_field(Field(name="User-Agent", values=[str(user_agent)]))
+        return context.transport_request
+
+
+_USERAGENT_ALLOWED_OS_NAMES = (
+    "windows",
+    "linux",
+    "macos",
+    "android",
+    "ios",
+    "watchos",
+    "tvos",
+    "other",
+)
+_USERAGENT_PLATFORM_NAME_MAPPINGS = {"darwin": "macos"}
+_USERAGENT_SDK_NAME = "python"
+
+
+class _UserAgentBuilder:
+    def __init__(
+        self,
+        *,
+        platform_name: str | None,
+        platform_version: str | None,
+        platform_machine: str | None,
+        python_version: str | None,
+        python_implementation: str | None,
+        sdk_version: str | None,
+    ) -> None:
+        self._platform_name = platform_name
+        self._platform_version = platform_version
+        self._platform_machine = platform_machine
+        self._python_version = python_version
+        self._python_implementation = python_implementation
+        self._sdk_version = sdk_version
+
+    @classmethod
+    def from_environment(cls) -> Self:
+        return cls(
+            platform_name=platform.system(),
+            platform_version=platform.release(),
+            platform_machine=platform.machine(),
+            python_version=platform.python_version(),
+            python_implementation=platform.python_implementation(),
+            sdk_version=smithy_core.__version__,
+        )
+
+    def build(self) -> UserAgent:
+        user_agent = UserAgent()
+        user_agent.sdk_metadata.extend(self._build_sdk_metadata())
+        user_agent.ua_metadata.append(UserAgentComponent(prefix="ua", name="2.1"))
+        user_agent.os_metadata.extend(self._build_os_metadata())
+        user_agent.os_metadata.extend(self._build_architecture_metadata())
+        user_agent.language_metadata.extend(self._build_language_metadata())
+
+        return user_agent
+
+    def _build_sdk_metadata(self) -> list[UserAgentComponent]:
+        if self._sdk_version:
+            return [
+                UserAgentComponent(prefix=_USERAGENT_SDK_NAME, name=self._sdk_version)
+            ]
+        return []
+
+    def _build_os_metadata(self) -> list[UserAgentComponent]:
+        """Build the OS/platform components of the User-Agent header string.
+
+        For recognized platform names that match or map to an entry in the list
+        of standardized OS names, a single component with prefix "os" is
+        returned. Otherwise, one component "os/other" is returned and a second
+        with prefix "md" and the raw platform name.
+
+        String representations of example return values:
+         * ``os/macos#10.13.6``
+         * ``os/linux``
+         * ``os/other``
+         * ``os/other md/foobar#1.2.3``
+        """
+        if self._platform_name in (None, ""):
+            return [UserAgentComponent("os", "other")]
+
+        plt_name_lower = self._platform_name.lower()
+        if plt_name_lower in _USERAGENT_ALLOWED_OS_NAMES:
+            os_family = plt_name_lower
+        elif plt_name_lower in _USERAGENT_PLATFORM_NAME_MAPPINGS:
+            os_family = _USERAGENT_PLATFORM_NAME_MAPPINGS[plt_name_lower]
+        else:
+            os_family = None
+
+        if os_family is not None:
+            return [UserAgentComponent("os", os_family, self._platform_version)]
+        else:
+            return [
+                UserAgentComponent("os", "other"),
+                UserAgentComponent("md", self._platform_name, self._platform_version),
+            ]
+
+    def _build_architecture_metadata(self) -> list[UserAgentComponent]:
+        """Build architecture component of the User-Agent header string.
+
+        Returns the machine type with prefix "md" and name "arch", if one is available.
+        Common values include "x86_64", "arm64", "i386".
+        """
+        if self._platform_machine:
+            return [UserAgentComponent("md", "arch", self._platform_machine.lower())]
+        return []
+
+    def _build_language_metadata(self) -> list[UserAgentComponent]:
+        """Build the language components of the User-Agent header string.
+
+        Returns the Python version in a component with prefix "lang" and name
+        "python". The Python implementation (e.g. CPython, PyPy) is returned as
+        separate metadata component with prefix "md" and name "pyimpl".
+
+        String representation of an example return value:
+        ``lang/python#3.10.4 md/pyimpl#CPython``
+        """
+        lang_md = [
+            UserAgentComponent("lang", "python", self._python_version),
+        ]
+        if self._python_implementation:
+            lang_md.append(
+                UserAgentComponent("md", "pyimpl", self._python_implementation)
+            )
+        return lang_md

smithy_http/interfaces/__init__.py

@@ -0,0 +1,141 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from collections.abc import Iterator
+from dataclasses import dataclass
+from enum import Enum
+from typing import Protocol
+
+
+class FieldPosition(Enum):
+    """The type of a field.
+
+    Defines its placement in a request or response.
+    """
+
+    HEADER = 0
+    """Header field.
+
+    In HTTP this is a header as defined in RFC 9110 Section 6.3. Implementations of
+    other protocols may use this FieldPosition for similar types of metadata.
+    """
+
+    TRAILER = 1
+    """Trailer field.
+
+    In HTTP this is a trailer as defined in RFC 9110 Section 6.5. Implementations of
+    other protocols may use this FieldPosition for similar types of metadata.
+    """
+
+
+class Field(Protocol):
+    """A name-value pair representing a single field in a request or response.
+
+    The kind will dictate metadata placement within an the message, for example as
+    header or trailer field in a HTTP request as defined in RFC 9110 Section 5.
+
+    All field names are case insensitive and case-variance must be treated as
+    equivalent. Names may be normalized but should be preserved for accuracy during
+    transmission.
+    """
+
+    name: str
+    values: list[str]
+    kind: FieldPosition = FieldPosition.HEADER
+
+    def add(self, value: str) -> None:
+        """Append a value to a field."""
+        ...
+
+    def set(self, values: list[str]) -> None:
+        """Overwrite existing field values."""
+        ...
+
+    def remove(self, value: str) -> None:
+        """Remove all matching entries from list."""
+        ...
+
+    def as_string(self) -> str:
+        """Serialize the ``Field``'s values into a single line string."""
+        ...
+
+    def as_tuples(self) -> list[tuple[str, str]]:
+        """Get list of ``name``, ``value`` tuples where each tuple represents one
+        value."""
+        ...
+
+
+class Fields(Protocol):
+    """Protocol agnostic mapping of key-value pair request metadata, such as HTTP
+    fields."""
+
+    # Entries are keyed off the name of a provided Field
+    entries: dict[str, Field]
+    encoding: str = "utf-8"
+
+    def set_field(self, field: Field) -> None:
+        """Alias for __setitem__ to utilize the field.name for the entry key."""
+        ...
+
+    def __setitem__(self, name: str, field: Field) -> None:
+        """Set entry for a Field name."""
+        ...
+
+    def __getitem__(self, name: str) -> Field:
+        """Retrieve Field entry."""
+        ...
+
+    def __delitem__(self, name: str) -> None:
+        """Delete entry from collection."""
+        ...
+
+    def __iter__(self) -> Iterator[Field]:
+        """Allow iteration over entries."""
+        ...
+
+    def __len__(self) -> int:
+        """Get total number of Field entries."""
+        ...
+
+    def __contains__(self, key: str) -> bool:
+        """Allows in/not in checks on Field entries."""
+        ...
+
+    def get_by_type(self, kind: FieldPosition) -> list[Field]:
+        """Helper function for retrieving specific types of fields.
+
+        Used to grab all headers or all trailers.
+        """
+        ...
+
+    def extend(self, other: "Fields") -> None:
+        """Merges ``entries`` of ``other`` into the current ``entries``.
+
+        For every `Field` in the ``entries`` of ``other``: If the normalized name
+        already exists in the current ``entries``, the values from ``other`` are
+        appended. Otherwise, the ``Field`` is added to the list of ``entries``.
+        """
+        ...
+
+
+QueryParamsList = list[tuple[str, str]]
+
+
+@dataclass(kw_only=True)
+class HTTPClientConfiguration:
+    """Client-level HTTP configuration.
+
+    :param force_http_2: Whether to require HTTP/2.
+    """
+
+    force_http_2: bool = False
+
+
+@dataclass(kw_only=True)
+class HTTPRequestConfiguration:
+    """Request-level HTTP configuration.
+
+    :param read_timeout: How long, in seconds, the client will attempt to read the first
+        byte over an established, open connection before timing out.
+    """
+
+    read_timeout: float | None = None

smithy_http/plugins/__init__.py

@@ -0,0 +1,15 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from typing import Any, Protocol
+
+from smithy_core.interceptors import Interceptor
+
+from smithy_http.interceptors.user_agent import UserAgentInterceptor
+
+
+class _InterceptorConfig(Protocol):
+    interceptors: list[Interceptor[Any, Any, Any, Any]]
+
+
+def user_agent_plugin(config: _InterceptorConfig) -> None:
+    config.interceptors.append(UserAgentInterceptor())

smithy_http/restjson.py

@@ -0,0 +1,29 @@
+#  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#  SPDX-License-Identifier: Apache-2.0
+from typing import NamedTuple
+
+from smithy_core.documents import DocumentValue
+
+_REST_JSON_CODE_HEADER = "x-amzn-errortype"
+
+_REST_JSON_CODE_KEYS = {"__type", "code"}
+
+_REST_JSON_MESSAGE_KEYS = {"message", "errormessage", "error_message"}
+
+
+class RestJsonErrorInfo(NamedTuple):
+    """Generic error information from a RestJson protocol error."""
+
+    code: str
+    """The error code."""
+
+    message: str
+    """The generic error message.
+
+    A modeled error may have the error bound somewhere else. This is based off of
+    checking the most common locations and is intended for use with excpetions that
+    either didn't model the message or which are unknown.
+    """
+
+    json_body: dict[str, DocumentValue] | None = None
+    """The HTTP response body parsed as JSON."""