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

xtr_http_message/factory/http_factory.py

@@ -0,0 +1,235 @@
+"""One factory for every kind of message, so a caller need name no class."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, cast, final
+
+from typing_extensions import override
+from xtr_http_message_contracts import UploadError
+from xtr_http_message_contracts.factory import (
+    RequestFactoryInterface,
+    ResponseFactoryInterface,
+    ServerRequestFactoryInterface,
+    StreamFactoryInterface,
+    UploadedFileFactoryInterface,
+    UriFactoryInterface,
+)
+
+from xtr_http_message.exception import InvalidArgumentError, StreamError
+from xtr_http_message.request import Request
+from xtr_http_message.response import Response
+from xtr_http_message.server_request import ServerRequest
+from xtr_http_message.stream import Stream
+from xtr_http_message.uploaded_file import UploadedFile
+from xtr_http_message.uri import Uri
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+    from typing import BinaryIO
+
+    from xtr_http_message_contracts import (
+        RequestInterface,
+        ResponseInterface,
+        ServerRequestInterface,
+        StreamInterface,
+        UploadedFileInterface,
+        UriInterface,
+    )
+
+__all__ = ["HttpFactory"]
+
+
+@final
+class HttpFactory(
+    RequestFactoryInterface,
+    ResponseFactoryInterface,
+    ServerRequestFactoryInterface,
+    StreamFactoryInterface,
+    UploadedFileFactoryInterface,
+    UriFactoryInterface,
+):
+    """Builds every kind of message this package implements.
+
+    One object rather than six, because the six belong together: a library
+    given this one can build whatever it needs, and an application that wants
+    to swap the implementation out swaps one registration.
+
+    ```python
+    from xtr_http_message.factory import HttpFactory
+
+    factory = HttpFactory()
+    response = factory.create_response(404)
+    assert response.get_reason_phrase() == "Not Found"
+    ```
+
+    It holds no state, so one instance serves a whole application.
+    """
+
+    __slots__ = ()
+
+    @override
+    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, it is read into one.
+
+        Returns:
+            The request.
+        """
+        return Request(method, uri)
+
+    @override
+    def create_response(
+        self,
+        code: int = 200,
+        reason_phrase: str | None = None,
+    ) -> ResponseInterface:
+        """Return a new response for ``code``.
+
+        Args:
+            code: The status code.
+            reason_phrase: The phrase to go with ``code``. Left out, the
+                recommended phrase for the code is filled in where there is
+                one; given as an empty string, the response carries no phrase
+                at all. That is the difference between asking for the usual
+                phrase and asking for none.
+
+        Returns:
+            The response.
+        """
+        return Response(code, None, None, "1.1", reason_phrase)
+
+    @override
+    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 read, and in particular neither the method nor the URI, 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, it is read into one.
+            server_params: The environment parameters to seed the request
+                with. ``None`` seeds it with none.
+
+        Returns:
+            The server request.
+        """
+        return ServerRequest(method, uri, None, None, "1.1", server_params)
+
+    @override
+    def create_stream(self, content: bytes = b"") -> StreamInterface:
+        """Return a new stream over ``content``, held in memory.
+
+        Args:
+            content: The bytes the stream reads back.
+
+        Returns:
+            The stream, with its cursor at the first byte.
+        """
+        return Stream.create(content)
+
+    @override
+    def create_stream_from_file(self, filename: str, mode: str = "r") -> StreamInterface:
+        """Return a new stream over the file at ``filename``.
+
+        Args:
+            filename: The path to open.
+            mode: How to open it. The payload is bytes, so the mode is taken
+                as a binary one whether or not it says so.
+
+        Returns:
+            The stream.
+
+        Raises:
+            InvalidArgumentError: When the mode is not a mode.
+            StreamError: When the path is empty, or the file cannot be opened.
+        """
+        if filename == "":
+            raise StreamError("Path cannot be empty")
+
+        binary = mode if "b" in mode else f"{mode}b"
+
+        try:
+            # The stream takes the file over and closes it, so there is no
+            # context manager here to close it first (SIM115). The mode is
+            # binary by the line above, which a mode computed at run time
+            # cannot say in a type.
+            opened = Path(filename).open(binary)  # noqa: SIM115
+        except ValueError as invalid:
+            # Not a mode at all, which is worth telling apart from a file that
+            # will not open.
+            message = f'The mode "{mode}" is invalid.'
+            raise InvalidArgumentError(message) from invalid
+        except OSError as failure:
+            message = f'The file "{filename}" cannot be opened: {failure}'
+            raise StreamError(message) from failure
+
+        return Stream.create(cast("BinaryIO", opened))
+
+    @override
+    def create_stream_from_resource(self, resource: BinaryIO) -> StreamInterface:
+        """Return a new stream over an open binary file object.
+
+        Args:
+            resource: The file object. The stream takes it over: closing the
+                stream closes it.
+
+        Returns:
+            The stream.
+        """
+        return Stream.create(resource)
+
+    @override
+    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``.
+
+        Args:
+            stream: The contents of the uploaded file.
+            size: The size in bytes. Left out, it is read off the stream.
+            error: How the upload went.
+            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:
+            InvalidArgumentError: When ``error`` is not one of the upload
+                outcomes.
+        """
+        if size is None:
+            size = stream.get_size()
+
+        return UploadedFile(stream, size, error, client_filename, client_media_type)
+
+    @override
+    def create_uri(self, uri: str = "") -> UriInterface:
+        """Return a new URI read from ``uri``.
+
+        Args:
+            uri: The URI as text. Empty builds one with no component at all.
+
+        Returns:
+            The URI.
+
+        Raises:
+            InvalidArgumentError: When the text cannot be read as a URI.
+        """
+        return Uri(uri)

xtr_http_message/request.py

@@ -0,0 +1,74 @@
+"""A request on its way out, as a client sends it."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from xtr_http_message_contracts import RequestInterface
+
+from ._request_trait import RequestTrait
+from .uri import Uri
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from typing import BinaryIO
+
+    from xtr_http_message_contracts import StreamInterface, UriInterface
+
+__all__ = ["Request"]
+
+_HOST = "Host"
+
+
+@final
+class Request(RequestTrait, RequestInterface):
+    """An outgoing, client-side request: a method, a URI, headers and a body.
+
+    ```python
+    from xtr_http_message import Request
+
+    request = Request("GET", "https://example.com/orders?page=2")
+    assert request.get_header_line("host") == "example.com"
+    assert request.get_request_target() == "/orders?page=2"
+    ```
+
+    The ``Host`` header is taken from the URI unless one was given with the
+    request, and is sent in front of every other header.
+    """
+
+    __slots__ = ()
+
+    def __init__(
+        self,
+        method: str,
+        uri: UriInterface | str,
+        headers: Mapping[str, str | Sequence[str]] | None = None,
+        body: bytes | BinaryIO | StreamInterface | None = None,
+        version: str = "1.1",
+    ) -> None:
+        """Build a request.
+
+        Args:
+            method: The HTTP method, kept exactly as given.
+            uri: The URI of the request. Given as text, it is read into a
+                :class:`~xtr_http_message.uri.Uri`.
+            headers: Each header name mapped to one value or to several.
+            body: The payload, in any of the shapes a stream is built from.
+                Left out, nothing is opened until the body is asked for.
+            version: The HTTP version number alone.
+
+        Raises:
+            InvalidArgumentError: When the URI cannot be read, or a header
+                name or value is not one.
+        """
+        super().__init__()
+
+        self._method = method
+        self._uri = Uri(uri) if isinstance(uri, str) else uri
+        self._set_headers(headers or {})
+        self._protocol = version
+
+        if not self.has_header(_HOST):
+            self._update_host_from_uri()
+
+        self._set_body(body)

xtr_http_message/response.py

@@ -0,0 +1,196 @@
+"""A response on its way out, as a server sends it."""
+
+from __future__ import annotations
+
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Final, Self, final
+
+from typing_extensions import override
+from xtr_http_message_contracts import ResponseInterface
+
+from ._message_trait import MessageTrait
+from .exception import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from typing import BinaryIO
+
+    from xtr_http_message_contracts import StreamInterface
+
+__all__ = ["Response"]
+
+_LOWEST_STATUS = 100
+_HIGHEST_STATUS = 599
+
+# The reason phrase recommended for each status code that has one. A code
+# absent from here is still a status code; it simply has no phrase to offer.
+_PHRASES: Final[Mapping[int, str]] = MappingProxyType(
+    {
+        100: "Continue",
+        101: "Switching Protocols",
+        102: "Processing",
+        200: "OK",
+        201: "Created",
+        202: "Accepted",
+        203: "Non-Authoritative Information",
+        204: "No Content",
+        205: "Reset Content",
+        206: "Partial Content",
+        207: "Multi-status",
+        208: "Already Reported",
+        300: "Multiple Choices",
+        301: "Moved Permanently",
+        302: "Found",
+        303: "See Other",
+        304: "Not Modified",
+        305: "Use Proxy",
+        306: "Switch Proxy",
+        307: "Temporary Redirect",
+        400: "Bad Request",
+        401: "Unauthorized",
+        402: "Payment Required",
+        403: "Forbidden",
+        404: "Not Found",
+        405: "Method Not Allowed",
+        406: "Not Acceptable",
+        407: "Proxy Authentication Required",
+        408: "Request Time-out",
+        409: "Conflict",
+        410: "Gone",
+        411: "Length Required",
+        412: "Precondition Failed",
+        413: "Request Entity Too Large",
+        414: "Request-URI Too Large",
+        415: "Unsupported Media Type",
+        416: "Requested range not satisfiable",
+        417: "Expectation Failed",
+        418: "I'm a teapot",
+        422: "Unprocessable Entity",
+        423: "Locked",
+        424: "Failed Dependency",
+        425: "Unordered Collection",
+        426: "Upgrade Required",
+        428: "Precondition Required",
+        429: "Too Many Requests",
+        431: "Request Header Fields Too Large",
+        451: "Unavailable For Legal Reasons",
+        500: "Internal Server Error",
+        501: "Not Implemented",
+        502: "Bad Gateway",
+        503: "Service Unavailable",
+        504: "Gateway Time-out",
+        505: "HTTP Version not supported",
+        506: "Variant Also Negotiates",
+        507: "Insufficient Storage",
+        508: "Loop Detected",
+        511: "Network Authentication Required",
+    }
+)
+
+
+@final
+class Response(MessageTrait, ResponseInterface):
+    """A response: a status code, the phrase that goes with it, headers and a body.
+
+    ```python
+    from xtr_http_message import Response
+
+    response = Response(201, {"content-type": "application/json"}, b'{"id": 7}')
+    assert response.get_reason_phrase() == "Created"
+    ```
+
+    Given no reason phrase, the one recommended for the status code is filled
+    in; given an empty one, the response carries none, since a status line
+    need not have a phrase at all.
+    """
+
+    __slots__ = ("_reason_phrase", "_status_code")
+
+    def __init__(
+        self,
+        status: int = 200,
+        headers: Mapping[str, str | Sequence[str]] | None = None,
+        body: bytes | BinaryIO | StreamInterface | None = None,
+        version: str = "1.1",
+        reason: str | None = None,
+    ) -> None:
+        """Build a response.
+
+        Args:
+            status: The status code.
+            headers: Each header name mapped to one value or to several.
+            body: The payload, in any of the shapes a stream is built from.
+                Left out, nothing is opened until the body is asked for.
+            version: The HTTP version number alone.
+            reason: The reason phrase. ``None`` — the default — takes the one
+                recommended for ``status``; an empty string leaves the
+                response with none.
+
+        Raises:
+            InvalidArgumentError: When a header name or value is not one.
+        """
+        super().__init__()
+
+        self._set_body(body)
+
+        self._status_code: int = status
+        self._set_headers(headers or {})
+
+        if reason is None:
+            self._reason_phrase: str = _PHRASES.get(status, "")
+        else:
+            self._reason_phrase = reason
+
+        self._protocol = version
+
+    @override
+    def get_status_code(self) -> int:
+        """Return the status code of the response.
+
+        Returns:
+            The three-digit code saying how the server got on with the
+            request.
+        """
+        return self._status_code
+
+    @override
+    def get_reason_phrase(self) -> str:
+        """Return the reason phrase that goes with the status code.
+
+        Returns:
+            The reason phrase, or an empty string when the response carries
+            none.
+        """
+        return self._reason_phrase
+
+    @override
+    def with_status(self, code: int, reason_phrase: str = "") -> Self:
+        """Return an instance carrying ``code`` and, optionally, ``reason_phrase``.
+
+        Args:
+            code: The status code to set.
+            reason_phrase: The phrase to go with ``code``. Left out or empty,
+                the one recommended for ``code`` is filled in where there is
+                one.
+
+        Returns:
+            A new instance; this one is left as it was.
+
+        Raises:
+            InvalidArgumentError: When the code is not a status code.
+        """
+        if code < _LOWEST_STATUS or code > _HIGHEST_STATUS:
+            message = (
+                "Status code has to be an integer between 100 and 599. "
+                f"A status code of {code} was given"
+            )
+            raise InvalidArgumentError(message)
+
+        if reason_phrase == "":
+            reason_phrase = _PHRASES.get(code, "")
+
+        new = self._copy()
+        new._status_code = code  # noqa: SLF001 — a copy of this very class.
+        new._reason_phrase = reason_phrase  # noqa: SLF001 — a copy of this very class.
+
+        return new