xtr-http-message-contracts 4.0.2__py3-none-any.whl

xtr_http_message_contracts/__init__.py

@@ -0,0 +1,89 @@
+"""The HTTP message contract: what code that handles requests depends on, and nothing more.
+
+A library that reads a request or fills in a response should not decide which
+class is one. It takes a :class:`ServerRequestInterface` and a
+:class:`ResponseInterface`, or the factory that makes them, and leaves the
+choice of implementation to the application — so two libraries written against
+this contract pass messages to each other without either knowing what the
+other installed.
+
+What is here is only what appears in that contract:
+
+- :class:`MessageInterface` — the protocol version, headers and body every
+  message has.
+- :class:`RequestInterface` / :class:`ServerRequestInterface` — a request
+  going out, and one that arrived with everything the server learned
+  alongside it.
+- :class:`ResponseInterface` — a status code, a reason phrase, and a message.
+- :class:`StreamInterface` — the body, as a cursor over bytes.
+- :class:`UriInterface` — a URI taken apart into its components.
+- :class:`UploadedFileInterface` and :class:`UploadError` — a file that came
+  in with a request, and how its upload went.
+- The six factories, also under ``xtr_http_message_contracts.factory``, for
+  building any of the above without naming a class.
+
+Every message is immutable: a ``with_*`` method leaves the instance it was
+called on alone and returns one carrying the change.
+
+A body moves bytes, so reading and writing one is awaited.
+
+```python
+from xtr_http_message_contracts import ResponseInterface, ServerRequestInterface
+
+
+async def whoami(request: ServerRequestInterface, response: ResponseInterface) -> ResponseInterface:
+    _ = await response.get_body().write(request.get_header_line("user-agent").encode())
+    return response.with_header("content-type", "text/plain")
+```
+
+An implementation builds on these types rather than redefining them, so a
+container can register one under an interface and a library that never
+imported it receives it. Bridging a message to the web framework an
+application runs on belongs with that framework's integration, not here.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .factory import (
+    RequestFactoryInterface,
+    ResponseFactoryInterface,
+    ServerRequestFactoryInterface,
+    StreamFactoryInterface,
+    UploadedFileFactoryInterface,
+    UriFactoryInterface,
+)
+from .message_interface import MessageInterface
+from .request_interface import RequestInterface
+from .response_interface import ResponseInterface
+from .server_request_interface import ServerRequestInterface
+from .stream_interface import StreamInterface
+from .upload_error import UploadError
+from .uploaded_file_interface import UploadedFileInterface
+from .uri_interface import UriInterface
+
+try:
+    __version__ = version("xtr-http-message-contracts")
+except PackageNotFoundError:  # pragma: no cover
+    # Running from a source tree or a vendored copy, with no installed
+    # metadata to read. Having no version is better than refusing to import.
+    __version__ = "0+unknown"
+
+__all__ = [
+    "MessageInterface",
+    "RequestFactoryInterface",
+    "RequestInterface",
+    "ResponseFactoryInterface",
+    "ResponseInterface",
+    "ServerRequestFactoryInterface",
+    "ServerRequestInterface",
+    "StreamFactoryInterface",
+    "StreamInterface",
+    "UploadError",
+    "UploadedFileFactoryInterface",
+    "UploadedFileInterface",
+    "UriFactoryInterface",
+    "UriInterface",
+    "__version__",
+]

xtr_http_message_contracts/factory/__init__.py

@@ -0,0 +1,41 @@
+"""The six factories, so that code which builds messages names no class.
+
+A library that has to make a request, a response, a stream, a URI or an
+uploaded file takes the matching factory and stays free of whichever
+implementation the application installed:
+
+```python
+class Probe:
+    def __init__(self, requests: RequestFactoryInterface) -> None:
+        self._requests = requests
+
+    def ping(self, url: str) -> RequestInterface:
+        return self._requests.create_request("HEAD", url)
+```
+
+- :class:`RequestFactoryInterface` / :class:`ServerRequestFactoryInterface` —
+  a request going out, and one that arrived.
+- :class:`ResponseFactoryInterface` — a response.
+- :class:`StreamFactoryInterface` — a message body, from bytes, from a file, or
+  around a file object already open.
+- :class:`UriFactoryInterface` — a URI parsed from text.
+- :class:`UploadedFileFactoryInterface` — a file that came in with a request.
+"""
+
+from __future__ import annotations
+
+from .request_factory_interface import RequestFactoryInterface
+from .response_factory_interface import ResponseFactoryInterface
+from .server_request_factory_interface import ServerRequestFactoryInterface
+from .stream_factory_interface import StreamFactoryInterface
+from .uploaded_file_factory_interface import UploadedFileFactoryInterface
+from .uri_factory_interface import UriFactoryInterface
+
+__all__ = [
+    "RequestFactoryInterface",
+    "ResponseFactoryInterface",
+    "ServerRequestFactoryInterface",
+    "StreamFactoryInterface",
+    "UploadedFileFactoryInterface",
+    "UriFactoryInterface",
+]

xtr_http_message_contracts/factory/request_factory_interface.py

@@ -0,0 +1,29 @@
+"""Build a request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts.request_interface import RequestInterface
+    from xtr_http_message_contracts.uri_interface import UriInterface
+
+__all__ = ["RequestFactoryInterface"]
+
+
+@runtime_checkable
+class RequestFactoryInterface(Protocol):
+    """Makes a request, so that a caller need not name the class that is one."""
+
+    def create_request(self, method: str, uri: UriInterface | str) -> RequestInterface:
+        """Return a new request for ``method`` and ``uri``.
+
+        Args:
+            method: The HTTP method of the request.
+            uri: The URI of the request. Given as text, the factory builds the
+                URI from it.
+
+        Returns:
+            The request.
+        """
+        ...

xtr_http_message_contracts/factory/response_factory_interface.py

@@ -0,0 +1,35 @@
+"""Build a response."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts.response_interface import ResponseInterface
+
+__all__ = ["ResponseFactoryInterface"]
+
+
+@runtime_checkable
+class ResponseFactoryInterface(Protocol):
+    """Makes a response, so that a caller need not name the class that is one."""
+
+    def create_response(
+        self,
+        code: int = 200,
+        reason_phrase: str | None = None,
+    ) -> ResponseInterface:
+        """Return a new response carrying ``code`` and ``reason_phrase``.
+
+        Args:
+            code: The status code; ``200`` unless another is asked for.
+            reason_phrase: The phrase to go with ``code`` in the response.
+                ``None`` — nothing given — lets the factory fill in the
+                phrase recommended for the code; ``""`` asks for a response
+                with no phrase at all. Those are two different requests, and
+                only this tells them apart.
+
+        Returns:
+            The response.
+        """
+        ...

xtr_http_message_contracts/factory/server_request_factory_interface.py

@@ -0,0 +1,42 @@
+"""Build a server request."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_http_message_contracts.server_request_interface import ServerRequestInterface
+    from xtr_http_message_contracts.uri_interface import UriInterface
+
+__all__ = ["ServerRequestFactoryInterface"]
+
+
+@runtime_checkable
+class ServerRequestFactoryInterface(Protocol):
+    """Makes a server request, so that a caller need not name the class that is one."""
+
+    def create_server_request(
+        self,
+        method: str,
+        uri: UriInterface | str,
+        server_params: Mapping[str, object] | None = None,
+    ) -> ServerRequestInterface:
+        """Return a new server request for ``method`` and ``uri``.
+
+        The environment parameters are taken exactly as given: nothing in them
+        is parsed or processed, and in particular neither the method nor the
+        URI is read out of them, which is why both have to be passed.
+
+        Args:
+            method: The HTTP method of the request.
+            uri: The URI of the request. Given as text, the factory builds the
+                URI from it.
+            server_params: The environment parameters to seed the request
+                with. ``None`` seeds it with none.
+
+        Returns:
+            The server request.
+        """
+        ...

xtr_http_message_contracts/factory/stream_factory_interface.py

@@ -0,0 +1,63 @@
+"""Build a stream, from bytes, from a file, or around one already open."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from typing import BinaryIO
+
+    from xtr_http_message_contracts.stream_interface import StreamInterface
+
+__all__ = ["StreamFactoryInterface"]
+
+
+@runtime_checkable
+class StreamFactoryInterface(Protocol):
+    """Makes a stream, so that a caller need not name the class that is one."""
+
+    def create_stream(self, content: bytes = b"") -> StreamInterface:
+        """Return a new stream holding ``content``.
+
+        The stream should be backed by something temporary rather than by a
+        file the caller has to clean up.
+
+        Args:
+            content: The bytes the stream starts out holding.
+
+        Returns:
+            The stream.
+        """
+        ...
+
+    def create_stream_from_file(self, filename: str, mode: str = "r") -> StreamInterface:
+        """Return a new stream reading a file that already exists.
+
+        The file is opened in ``mode``, which may be any mode the host's file
+        opener accepts, and ``filename`` may be anything it can open.
+
+        Args:
+            filename: The file, or the address of the stream, to read.
+            mode: How to open it.
+
+        Returns:
+            The stream.
+
+        Raises:
+            RuntimeError: When the file cannot be opened.
+            ValueError: When the mode is not a usable one.
+        """
+        ...
+
+    def create_stream_from_resource(self, resource: BinaryIO) -> StreamInterface:
+        """Return a new stream around a file object that is already open.
+
+        The stream must be readable, and may be writable.
+
+        Args:
+            resource: The open file object to wrap.
+
+        Returns:
+            The stream.
+        """
+        ...

xtr_http_message_contracts/factory/uploaded_file_factory_interface.py

@@ -0,0 +1,46 @@
+"""Build an uploaded file."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+from xtr_http_message_contracts.upload_error import UploadError
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts.stream_interface import StreamInterface
+    from xtr_http_message_contracts.uploaded_file_interface import UploadedFileInterface
+
+__all__ = ["UploadedFileFactoryInterface"]
+
+
+@runtime_checkable
+class UploadedFileFactoryInterface(Protocol):
+    """Makes an uploaded file, so that a caller need not name the class that is one."""
+
+    def create_uploaded_file(
+        self,
+        stream: StreamInterface,
+        size: int | None = None,
+        error: int = UploadError.OK,
+        client_filename: str | None = None,
+        client_media_type: str | None = None,
+    ) -> UploadedFileInterface:
+        """Return a new uploaded file reading from ``stream``.
+
+        Given no size, the factory works it out from the stream itself.
+
+        Args:
+            stream: The contents of the uploaded file.
+            size: The size in bytes, when it is already known.
+            error: How the upload went, as one of
+                :class:`~xtr_http_message_contracts.upload_error.UploadError`.
+            client_filename: The file name the client sent, if any.
+            client_media_type: The media type the client sent, if any.
+
+        Returns:
+            The uploaded file.
+
+        Raises:
+            ValueError: When the stream cannot be read.
+        """
+        ...

xtr_http_message_contracts/factory/uri_factory_interface.py

@@ -0,0 +1,29 @@
+"""Build a URI."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from xtr_http_message_contracts.uri_interface import UriInterface
+
+__all__ = ["UriFactoryInterface"]
+
+
+@runtime_checkable
+class UriFactoryInterface(Protocol):
+    """Makes a URI, so that a caller need not name the class that is one."""
+
+    def create_uri(self, uri: str = "") -> UriInterface:
+        """Return a new URI parsed from ``uri``.
+
+        Args:
+            uri: The URI as text; empty for a URI with no components at all.
+
+        Returns:
+            The URI.
+
+        Raises:
+            ValueError: When the text cannot be parsed as a URI.
+        """
+        ...

xtr_http_message_contracts/message_interface.py

@@ -0,0 +1,177 @@
+"""What a request and a response have in common."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from .stream_interface import StreamInterface
+
+__all__ = ["MessageInterface"]
+
+
+@runtime_checkable
+class MessageInterface(Protocol):
+    """An HTTP message: a protocol version, headers and a body.
+
+    Requests travel from a client to a server and responses back the other
+    way; everything they share is here.
+
+    Messages are immutable. Every ``with_*`` method keeps the instance it was
+    called on as it was and returns one carrying the change, so a message
+    handed around cannot be altered behind the back of whoever handed it on.
+    """
+
+    def get_protocol_version(self) -> str:
+        """Return the HTTP version of the message.
+
+        Returns:
+            The version number alone, such as ``"1.1"`` or ``"1.0"`` — never
+            the protocol name with it.
+        """
+        ...
+
+    def with_protocol_version(self, version: str) -> Self:
+        """Return an instance carrying ``version``.
+
+        Args:
+            version: The HTTP version number alone, such as ``"1.1"``.
+
+        Returns:
+            A new instance; this one is left as it was.
+        """
+        ...
+
+    def get_headers(self) -> Mapping[str, Sequence[str]]:
+        """Return every header, each name mapped to all of its values.
+
+        A name comes back in the case it was first given in, even though names
+        are matched without regard to case elsewhere, so a message can be
+        written out the way it arrived:
+
+        ```python
+        for name, values in message.get_headers().items():
+            print(f"{name}: {', '.join(values)}")
+        ```
+
+        Returns:
+            Each header name as it will go over the wire, mapped to the
+            values recorded under it.
+        """
+        ...
+
+    def has_header(self, name: str) -> bool:
+        """Tell whether a header is present, matching ``name`` without case.
+
+        Args:
+            name: The header name, in any case.
+
+        Returns:
+            ``True`` when some header name matches ``name`` ignoring case;
+            ``False`` when none does.
+        """
+        ...
+
+    def get_header(self, name: str) -> Sequence[str]:
+        """Return every value recorded under a header, matched without case.
+
+        Args:
+            name: The header name, in any case.
+
+        Returns:
+            All the values under that header, in order. A header the message
+            does not carry gives an empty sequence.
+        """
+        ...
+
+    def get_header_line(self, name: str) -> str:
+        """Return the values of a header joined with commas, matched without case.
+
+        Not every header can be written this way; where comma-joining would
+        change the meaning, read :meth:`get_header` and join the values with
+        whatever separator that header calls for.
+
+        Args:
+            name: The header name, in any case.
+
+        Returns:
+            The values joined with commas. A header the message does not
+            carry gives an empty string.
+        """
+        ...
+
+    def with_header(self, name: str, value: str | Sequence[str]) -> Self:
+        """Return an instance whose ``name`` header holds ``value`` and nothing else.
+
+        Whatever was recorded under that header is replaced. The case of
+        ``name`` is kept and is what :meth:`get_headers` reports, even though
+        the header it replaces is found without regard to case.
+
+        Args:
+            name: The header name, in any case.
+            value: One value, or every value the header is to hold.
+
+        Returns:
+            A new instance; this one is left as it was.
+
+        Raises:
+            ValueError: When the name or a value is not a valid header name or
+                value.
+        """
+        ...
+
+    def with_added_header(self, name: str, value: str | Sequence[str]) -> Self:
+        """Return an instance with ``value`` appended to the ``name`` header.
+
+        What the header already held stays; the new values go after it. A
+        header the message did not carry is added.
+
+        Args:
+            name: The header name, in any case.
+            value: One value, or every value to append.
+
+        Returns:
+            A new instance; this one is left as it was.
+
+        Raises:
+            ValueError: When the name or a value is not a valid header name or
+                value.
+        """
+        ...
+
+    def without_header(self, name: str) -> Self:
+        """Return an instance with the ``name`` header gone.
+
+        The header to drop is found without regard to case.
+
+        Args:
+            name: The header name, in any case.
+
+        Returns:
+            A new instance; this one is left as it was.
+        """
+        ...
+
+    def get_body(self) -> StreamInterface:
+        """Return the body of the message.
+
+        Returns:
+            The body, as a stream.
+        """
+        ...
+
+    def with_body(self, body: StreamInterface) -> Self:
+        """Return an instance carrying ``body``.
+
+        Args:
+            body: The stream the new instance reads its body from.
+
+        Returns:
+            A new instance; this one is left as it was.
+
+        Raises:
+            ValueError: When the body cannot be used as one.
+        """
+        ...

xtr_http_message_contracts/request_interface.py

@@ -0,0 +1,119 @@
+"""A request on its way out, as a client sends it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol, Self, runtime_checkable
+
+from .message_interface import MessageInterface
+
+if TYPE_CHECKING:
+    from .uri_interface import UriInterface
+
+__all__ = ["RequestInterface"]
+
+
+@runtime_checkable
+class RequestInterface(MessageInterface, Protocol):
+    """An outgoing, client-side request.
+
+    On top of what every message carries — a protocol version, headers and a
+    body — a request carries a method and a URI.
+
+    A request being built must take its ``Host`` header from the URI it is
+    given whenever no ``Host`` header was given with it.
+
+    Requests are immutable. Every ``with_*`` method keeps the instance it was
+    called on as it was and returns one carrying the change.
+    """
+
+    def get_request_target(self) -> str:
+        """Return the request-target of the message.
+
+        That is the target as it will go out for a client, as it came in for a
+        server, or exactly as :meth:`with_request_target` set it.
+
+        Usually it is the origin-form of the URI the request carries — the
+        path with the query string after it — unless something else was set
+        explicitly.
+
+        Returns:
+            The request-target, or ``"/"`` when there is no URI to build one
+            from and none was set.
+        """
+        ...
+
+    def with_request_target(self, request_target: str) -> Self:
+        """Return an instance carrying ``request_target`` exactly as given.
+
+        Use it where the origin-form will not do: an absolute-form target, an
+        authority-form one, or the asterisk-form.
+
+        Args:
+            request_target: The request-target, taken verbatim.
+
+        Returns:
+            A new instance; this one is left as it was.
+        """
+        ...
+
+    def get_method(self) -> str:
+        """Return the HTTP method of the request.
+
+        Returns:
+            The method, in the case it was given in.
+        """
+        ...
+
+    def with_method(self, method: str) -> Self:
+        """Return an instance carrying ``method``.
+
+        Methods are written in capitals by convention but compared with
+        regard to case, so what is given should be kept as it is rather than
+        recased.
+
+        Args:
+            method: The method, case-sensitive.
+
+        Returns:
+            A new instance; this one is left as it was.
+
+        Raises:
+            ValueError: When the method is not a valid HTTP method.
+        """
+        ...
+
+    def get_uri(self) -> UriInterface:
+        """Return the URI the request is for.
+
+        Returns:
+            The URI of the request.
+        """
+        ...
+
+    def with_uri(self, uri: UriInterface, preserve_host: bool = False) -> Self:
+        """Return an instance carrying ``uri``.
+
+        By default the ``Host`` header of the new instance follows the URI: it
+        is set from the URI's host component when the URI has one, and a
+        ``Host`` header already present carries over untouched when it has
+        none.
+
+        Passing ``preserve_host=True`` asks instead that an existing ``Host``
+        header be kept, which plays out in three ways:
+
+        - no ``Host`` header, or an empty one, and a URI with a host: the
+          ``Host`` header of the new instance is set from the URI;
+        - no ``Host`` header, or an empty one, and a URI without a host: the
+          new instance gets no ``Host`` header either;
+        - a ``Host`` header that is present and not empty: it is left exactly
+          as it is.
+
+        Args:
+            uri: The URI the new instance is for.
+            preserve_host: Whether to keep the ``Host`` header the request
+                already carries.
+
+        Returns:
+            A new instance; this one is left as it was.
+        """
+        ...