plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/http/response.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import datetime
 import io
 import json
@@ -6,10 +8,11 @@ import os
 import re
 import sys
 import time
+from collections.abc import Iterator
 from email.header import Header
-from functools import cached_property
 from http.client import responses
 from http.cookies import SimpleCookie
+from typing import IO, Any
 
 from plain import signals
 from plain.http.cookie import sign_cookie_value
@@ -27,7 +30,7 @@ _charset_from_content_type_re = _lazy_re_compile(
 
 
 class ResponseHeaders(CaseInsensitiveMapping):
-    def __init__(self, data):
+    def __init__(self, data: dict[str, Any] | None = None):
         """
         Populate the initial data using __setitem__ to ensure values are
         correctly encoded.
@@ -37,7 +40,9 @@ class ResponseHeaders(CaseInsensitiveMapping):
             for header, value in self._unpack_items(data):
                 self[header] = value
 
-    def _convert_to_charset(self, value, charset, mime_encode=False):
+    def _convert_to_charset(
+        self, value: str | bytes, charset: str, mime_encode: bool = False
+    ) -> str:
         """
         Convert headers key/value to ascii/latin-1 native strings.
         `charset` must be 'ascii' or 'latin-1'. If `mime_encode` is True and
@@ -72,22 +77,26 @@ class ResponseHeaders(CaseInsensitiveMapping):
             if mime_encode:
                 value = Header(value, "utf-8", maxlinelen=sys.maxsize).encode()
             else:
-                e.reason += f", HTTP response headers must be in {charset} format"
+                if hasattr(e, "reason") and isinstance(e.reason, str):
+                    e.reason += f", HTTP response headers must be in {charset} format"
                 raise
         return value
 
-    def __delitem__(self, key):
+    def __delitem__(self, key: str) -> None:
         self.pop(key)
 
-    def __setitem__(self, key, value):
+    def __setitem__(self, key: str, value: str | bytes | None) -> None:
         key = self._convert_to_charset(key, "ascii")
-        value = self._convert_to_charset(value, "latin-1", mime_encode=True)
-        self._store[key.lower()] = (key, value)
+        if value is None:
+            self._store[key.lower()] = (key, None)
+        else:
+            value = self._convert_to_charset(value, "latin-1", mime_encode=True)
+            self._store[key.lower()] = (key, value)
 
-    def pop(self, key, default=None):
+    def pop(self, key: str, default: Any = None) -> Any:
         return self._store.pop(key.lower(), default)
 
-    def setdefault(self, key, value):
+    def setdefault(self, key: str, value: str | bytes) -> None:
         if key not in self:
             self[key] = value
 
@@ -109,11 +118,11 @@ class ResponseBase:
     def __init__(
         self,
         *,
-        content_type=None,
-        status_code=None,
-        reason=None,
-        charset=None,
-        headers=None,
+        content_type: str | None = None,
+        status_code: int | None = None,
+        reason: str | None = None,
+        charset: str | None = None,
+        headers: dict[str, Any] | None = None,
     ):
         self.headers = ResponseHeaders(headers)
         self._charset = charset
@@ -141,9 +150,11 @@ class ResponseBase:
             if not 100 <= self.status_code <= 599:
                 raise ValueError("HTTP status code must be an integer from 100 to 599.")
         self._reason_phrase = reason
+        # Exception that caused this response, if any (primarily for 500 errors)
+        self.exception: Exception | None = None
 
     @property
-    def reason_phrase(self):
+    def reason_phrase(self) -> str:
         if self._reason_phrase is not None:
             return self._reason_phrase
         # Leave self._reason_phrase unset in order to use the default
@@ -151,11 +162,11 @@ class ResponseBase:
         return responses.get(self.status_code, "Unknown Status Code")
 
     @reason_phrase.setter
-    def reason_phrase(self, value):
+    def reason_phrase(self, value: str) -> None:
         self._reason_phrase = value
 
     @property
-    def charset(self):
+    def charset(self) -> str:
         if self._charset is not None:
             return self._charset
         # The Content-Type header may not yet be set, because the charset is
@@ -170,22 +181,11 @@ class ResponseBase:
         return settings.DEFAULT_CHARSET
 
     @charset.setter
-    def charset(self, value):
+    def charset(self, value: str) -> None:
         self._charset = value
 
-    def serialize_headers(self):
-        """HTTP headers as a bytestring."""
-        return b"\r\n".join(
-            [
-                key.encode("ascii") + b": " + value.encode("latin-1")
-                for key, value in self.headers.items()
-            ]
-        )
-
-    __bytes__ = serialize_headers
-
     @property
-    def _content_type_for_repr(self):
+    def _content_type_for_repr(self) -> str:
         return (
             ', "{}"'.format(self.headers["Content-Type"])
             if "Content-Type" in self.headers
@@ -194,16 +194,16 @@ class ResponseBase:
 
     def set_cookie(
         self,
-        key,
-        value="",
-        max_age=None,
-        expires=None,
-        path="/",
-        domain=None,
-        secure=False,
-        httponly=False,
-        samesite=None,
-    ):
+        key: str,
+        value: str = "",
+        max_age: int | float | datetime.timedelta | None = None,
+        expires: str | datetime.datetime | None = None,
+        path: str | None = "/",
+        domain: str | None = None,
+        secure: bool = False,
+        httponly: bool = False,
+        samesite: str | None = None,
+    ) -> None:
         """
         Set a cookie.
 
@@ -256,18 +256,26 @@ class ResponseBase:
                 raise ValueError('samesite must be "lax", "none", or "strict".')
             self.cookies[key]["samesite"] = samesite
 
-    def set_signed_cookie(self, key, value, salt="", **kwargs):
+    def set_signed_cookie(
+        self, key: str, value: str, salt: str = "", **kwargs: Any
+    ) -> None:
         """Set a cookie signed with the SECRET_KEY."""
 
         signed_value = sign_cookie_value(key, value, salt)
         return self.set_cookie(key, signed_value, **kwargs)
 
-    def delete_cookie(self, key, path="/", domain=None, samesite=None):
+    def delete_cookie(
+        self,
+        key: str,
+        path: str = "/",
+        domain: str | None = None,
+        samesite: str | None = None,
+    ) -> None:
         # Browsers can ignore the Set-Cookie header if the cookie doesn't use
         # the secure flag and:
         # - the cookie name starts with "__Host-" or "__Secure-", or
         # - the samesite is "none".
-        secure = key.startswith(("__Secure-", "__Host-")) or (
+        secure = key.startswith(("__Secure-", "__Host-")) or bool(
             samesite and samesite.lower() == "none"
         )
         self.set_cookie(
@@ -282,7 +290,7 @@ class ResponseBase:
 
     # Common methods used by subclasses
 
-    def make_bytes(self, value):
+    def make_bytes(self, value: str | bytes) -> bytes:
         """Turn a value into a bytestring encoded in the output charset."""
         # Per PEP 3333, this response body must be bytes. To avoid returning
         # an instance of a subclass, this function returns `bytes(value)`.
@@ -298,12 +306,9 @@ class ResponseBase:
         # Handle non-string types.
         return str(value).encode(self.charset)
 
-    # These methods partially implement the file-like object interface.
-    # See https://docs.python.org/library/io.html#io.IOBase
-
     # The WSGI server must call this method upon completion of the request.
     # See http://blog.dscpl.com.au/2012/10/obligations-for-calling-close-on.html
-    def close(self):
+    def close(self) -> None:
         for closer in self._resource_closers:
             try:
                 closer()
@@ -314,32 +319,6 @@ class ResponseBase:
         self.closed = True
         signals.request_finished.send(sender=self._handler_class)
 
-    def write(self, content):
-        raise OSError(f"This {self.__class__.__name__} instance is not writable")
-
-    def flush(self):
-        pass
-
-    def tell(self):
-        raise OSError(
-            f"This {self.__class__.__name__} instance cannot tell its position"
-        )
-
-    # These methods partially implement a stream-like object interface.
-    # See https://docs.python.org/library/io.html#io.IOBase
-
-    def readable(self):
-        return False
-
-    def seekable(self):
-        return False
-
-    def writable(self):
-        return False
-
-    def writelines(self, lines):
-        raise OSError(f"This {self.__class__.__name__} instance is not writable")
-
 
 class Response(ResponseBase):
     """
@@ -349,86 +328,42 @@ class Response(ResponseBase):
     """
 
     streaming = False
-    non_picklable_attrs = frozenset(
-        [
-            "resolver_match",
-            # Non-picklable attributes added by test clients.
-            "client",
-            "context",
-            "json",
-            "templates",
-        ]
-    )
-
-    def __init__(self, content=b"", **kwargs):
+
+    def __init__(self, content: bytes | str | Iterator[bytes] = b"", **kwargs: Any):
         super().__init__(**kwargs)
         # Content is a bytestring. See the `content` property methods.
         self.content = content
 
-    def __getstate__(self):
-        obj_dict = self.__dict__.copy()
-        for attr in self.non_picklable_attrs:
-            if attr in obj_dict:
-                del obj_dict[attr]
-        return obj_dict
-
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<%(cls)s status_code=%(status_code)d%(content_type)s>" % {  # noqa: UP031
             "cls": self.__class__.__name__,
             "status_code": self.status_code,
             "content_type": self._content_type_for_repr,
         }
 
-    def serialize(self):
-        """Full HTTP message, including headers, as a bytestring."""
-        return self.serialize_headers() + b"\r\n\r\n" + self.content
-
-    __bytes__ = serialize
-
     @property
-    def content(self):
+    def content(self) -> bytes:
         return b"".join(self._container)
 
     @content.setter
-    def content(self, value):
+    def content(self, value: bytes | str | Iterator[bytes]) -> None:
         # Consume iterators upon assignment to allow repeated iteration.
         if hasattr(value, "__iter__") and not isinstance(
             value, bytes | memoryview | str
         ):
             content = b"".join(self.make_bytes(chunk) for chunk in value)
-            if hasattr(value, "close"):
+            if hasattr(value, "close") and callable(getattr(value, "close")):
                 try:
-                    value.close()
+                    value.close()  # type: ignore[union-attr]
                 except Exception:
                     pass
         else:
             content = self.make_bytes(value)
-        # Create a list of properly encoded bytestrings to support write().
         self._container = [content]
 
-    @cached_property
-    def text(self):
-        return self.content.decode(self.charset or "utf-8")
-
-    def __iter__(self):
+    def __iter__(self) -> Iterator[bytes]:
         return iter(self._container)
 
-    def write(self, content):
-        self._container.append(self.make_bytes(content))
-
-    def tell(self):
-        return len(self.content)
-
-    def getvalue(self):
-        return self.content
-
-    def writable(self):
-        return True
-
-    def writelines(self, lines):
-        for line in lines:
-            self.write(line)
-
 
 class StreamingResponse(ResponseBase):
     """
@@ -441,13 +376,13 @@ class StreamingResponse(ResponseBase):
 
     streaming = True
 
-    def __init__(self, streaming_content=(), **kwargs):
+    def __init__(self, streaming_content: Any = (), **kwargs: Any):
         super().__init__(**kwargs)
         # `streaming_content` should be an iterable of bytestrings.
         # See the `streaming_content` property methods.
         self.streaming_content = streaming_content
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<%(cls)s status_code=%(status_code)d%(content_type)s>" % {  # noqa: UP031
             "cls": self.__class__.__qualname__,
             "status_code": self.status_code,
@@ -455,32 +390,29 @@ class StreamingResponse(ResponseBase):
         }
 
     @property
-    def content(self):
+    def content(self) -> bytes:
         raise AttributeError(
             f"This {self.__class__.__name__} instance has no `content` attribute. Use "
             "`streaming_content` instead."
         )
 
     @property
-    def streaming_content(self):
+    def streaming_content(self) -> Iterator[bytes]:
         return map(self.make_bytes, self._iterator)
 
     @streaming_content.setter
-    def streaming_content(self, value):
+    def streaming_content(self, value: Iterator[bytes | str]) -> None:
         self._set_streaming_content(value)
 
-    def _set_streaming_content(self, value):
+    def _set_streaming_content(self, value: Iterator[bytes | str]) -> None:
         # Ensure we can never iterate on "value" more than once.
         self._iterator = iter(value)
         if hasattr(value, "close"):
             self._resource_closers.append(value.close)
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[bytes]:
         return iter(self.streaming_content)
 
-    def getvalue(self):
-        return b"".join(self.streaming_content)
-
 
 class FileResponse(StreamingResponse):
     """
@@ -489,7 +421,9 @@ class FileResponse(StreamingResponse):
 
     block_size = 4096
 
-    def __init__(self, *args, as_attachment=False, filename="", **kwargs):
+    def __init__(
+        self, *args: Any, as_attachment: bool = False, filename: str = "", **kwargs: Any
+    ):
         self.as_attachment = as_attachment
         self.filename = filename
         self._no_explicit_content_type = (
@@ -497,7 +431,7 @@ class FileResponse(StreamingResponse):
         )
         super().__init__(*args, **kwargs)
 
-    def _set_streaming_content(self, value):
+    def _set_streaming_content(self, value: Any) -> None:
         if not hasattr(value, "read"):
             self.file_to_stream = None
             return super()._set_streaming_content(value)
@@ -509,7 +443,7 @@ class FileResponse(StreamingResponse):
         self.set_headers(filelike)
         super()._set_streaming_content(value)
 
-    def set_headers(self, filelike):
+    def set_headers(self, filelike: IO[bytes]) -> None:
         """
         Set some common response headers (Content-Length, Content-Type, and
         Content-Disposition) based on the `filelike` response content.
@@ -523,19 +457,21 @@ class FileResponse(StreamingResponse):
             if seekable:
                 initial_position = filelike.tell()
                 filelike.seek(0, io.SEEK_END)
-                self.headers["Content-Length"] = filelike.tell() - initial_position
+                self.headers["Content-Length"] = str(filelike.tell() - initial_position)
                 filelike.seek(initial_position)
-            elif hasattr(filelike, "getbuffer"):
-                self.headers["Content-Length"] = (
-                    filelike.getbuffer().nbytes - filelike.tell()
+            elif hasattr(filelike, "getbuffer") and callable(
+                getattr(filelike, "getbuffer")
+            ):
+                self.headers["Content-Length"] = str(
+                    filelike.getbuffer().nbytes - filelike.tell()  # type: ignore[union-attr]
                 )
             elif os.path.exists(filename):
-                self.headers["Content-Length"] = (
+                self.headers["Content-Length"] = str(
                     os.path.getsize(filename) - filelike.tell()
                 )
         elif seekable:
-            self.headers["Content-Length"] = sum(
-                iter(lambda: len(filelike.read(self.block_size)), 0)
+            self.headers["Content-Length"] = str(
+                sum(iter(lambda: len(filelike.read(self.block_size)), 0))
             )
             filelike.seek(-int(self.headers["Content-Length"]), io.SEEK_END)
 
@@ -564,20 +500,20 @@ class FileResponse(StreamingResponse):
             self.headers["Content-Disposition"] = content_disposition
 
 
-class ResponseRedirect(Response):
+class RedirectResponse(Response):
     """HTTP redirect response"""
 
     status_code = 302
 
-    def __init__(self, redirect_to, **kwargs):
+    def __init__(self, redirect_to: str, **kwargs: Any):
         super().__init__(**kwargs)
-        self.headers["Location"] = iri_to_uri(redirect_to)
+        self.headers["Location"] = iri_to_uri(redirect_to) or ""
 
     @property
-    def url(self):
+    def url(self) -> str:
         return self.headers["Location"]
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             '<%(cls)s status_code=%(status_code)d%(content_type)s, url="%(url)s">'  # noqa: UP031
             % {
@@ -589,17 +525,17 @@ class ResponseRedirect(Response):
         )
 
 
-class ResponseNotModified(Response):
+class NotModifiedResponse(Response):
     """HTTP 304 response"""
 
     status_code = 304
 
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
         del self.headers["content-type"]
 
     @Response.content.setter
-    def content(self, value):
+    def content(self, value: bytes | str | Iterator[bytes]) -> None:
         if value:
             raise AttributeError(
                 "You cannot set content to a 304 (Not Modified) response"
@@ -607,34 +543,16 @@ class ResponseNotModified(Response):
         self._container = []
 
 
-class ResponseBadRequest(Response):
-    """HTTP 400 response"""
-
-    status_code = 400
-
-
-class ResponseNotFound(Response):
-    """HTTP 404 response"""
-
-    status_code = 404
-
-
-class ResponseForbidden(Response):
-    """HTTP 403 response"""
-
-    status_code = 403
-
-
-class ResponseNotAllowed(Response):
+class NotAllowedResponse(Response):
     """HTTP 405 response"""
 
     status_code = 405
 
-    def __init__(self, permitted_methods, *args, **kwargs):
+    def __init__(self, permitted_methods: list[str], *args: Any, **kwargs: Any):
         super().__init__(*args, **kwargs)
         self.headers["Allow"] = ", ".join(permitted_methods)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return "<%(cls)s [%(methods)s] status_code=%(status_code)d%(content_type)s>" % {  # noqa: UP031
             "cls": self.__class__.__name__,
             "status_code": self.status_code,
@@ -643,22 +561,6 @@ class ResponseNotAllowed(Response):
         }
 
 
-class ResponseGone(Response):
-    """HTTP 410 response"""
-
-    status_code = 410
-
-
-class ResponseServerError(Response):
-    """HTTP 500 response"""
-
-    status_code = 500
-
-
-class Http404(Exception):
-    pass
-
-
 class JsonResponse(Response):
     """
     An HTTP response class that consumes data to be serialized to JSON.
@@ -675,11 +577,11 @@ class JsonResponse(Response):
 
     def __init__(
         self,
-        data,
-        encoder=PlainJSONEncoder,
-        safe=True,
-        json_dumps_params=None,
-        **kwargs,
+        data: Any,
+        encoder: type[json.JSONEncoder] = PlainJSONEncoder,
+        safe: bool = True,
+        json_dumps_params: dict[str, Any] | None = None,
+        **kwargs: Any,
     ):
         if safe and not isinstance(data, dict):
             raise TypeError(

plain/internal/__init__.py

@@ -1,4 +1,11 @@
-def internalcode(obj):
+from __future__ import annotations
+
+from typing import TypeVar
+
+T = TypeVar("T")
+
+
+def internalcode(obj: T) -> T:
     """
     A decorator that simply marks a class or function as internal.