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

plain/http/__init__.py

@@ -1,49 +1,64 @@
-from plain.http.cookie import parse_cookie
-from plain.http.request import (
-    HttpHeaders,
-    HttpRequest,
+from .cookie import parse_cookie
+from .exceptions import (
+    BadRequestError400,
+    ForbiddenError403,
+    NotFoundError404,
+    RequestDataTooBigError400,
+    SuspiciousFileOperationError400,
+    SuspiciousMultipartFormError400,
+    SuspiciousOperationError400,
+    TooManyFieldsSentError400,
+    TooManyFilesSentError400,
+)
+from .middleware import HttpMiddleware
+from .request import (
     QueryDict,
     RawPostDataException,
+    Request,
+    RequestHeaders,
     UnreadablePostError,
 )
-from plain.http.response import (
+from .response import (
     BadHeaderError,
     FileResponse,
-    Http404,
     JsonResponse,
+    NotAllowedResponse,
+    NotModifiedResponse,
+    RedirectResponse,
     Response,
-    ResponseBadRequest,
     ResponseBase,
-    ResponseForbidden,
-    ResponseGone,
-    ResponseNotAllowed,
-    ResponseNotFound,
-    ResponseNotModified,
-    ResponseRedirect,
-    ResponseServerError,
     StreamingResponse,
 )
 
 __all__ = [
+    # Middleware
+    "HttpMiddleware",
+    # Cookies
     "parse_cookie",
-    "HttpHeaders",
-    "HttpRequest",
+    # Request
+    "Request",
+    "RequestHeaders",
     "QueryDict",
     "RawPostDataException",
     "UnreadablePostError",
+    # Response
     "Response",
     "ResponseBase",
     "StreamingResponse",
-    "ResponseRedirect",
-    "ResponseNotModified",
-    "ResponseBadRequest",
-    "ResponseForbidden",
-    "ResponseNotFound",
-    "ResponseNotAllowed",
-    "ResponseGone",
-    "ResponseServerError",
-    "Http404",
-    "BadHeaderError",
+    "RedirectResponse",
+    "NotModifiedResponse",
+    "NotAllowedResponse",
     "JsonResponse",
     "FileResponse",
+    "BadHeaderError",
+    # Exceptions
+    "NotFoundError404",
+    "ForbiddenError403",
+    "BadRequestError400",
+    "SuspiciousOperationError400",
+    "SuspiciousMultipartFormError400",
+    "SuspiciousFileOperationError400",
+    "TooManyFieldsSentError400",
+    "TooManyFilesSentError400",
+    "RequestDataTooBigError400",
 ]

plain/http/cookie.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from http import cookies
 
 from plain.runtime import settings
@@ -5,7 +7,7 @@ from plain.signing import BadSignature, TimestampSigner
 from plain.utils.encoding import force_bytes
 
 
-def parse_cookie(cookie):
+def parse_cookie(cookie: str) -> dict[str, str]:
     """
     Return a dictionary parsed from a `Cookie:` header string.
     """
@@ -24,7 +26,7 @@ def parse_cookie(cookie):
     return cookiedict
 
 
-def _cookie_key(key):
+def _cookie_key(key: str) -> bytes:
     """
     Generate a key for cookie signing that matches the pattern used by
     set_signed_cookie and get_signed_cookie.
@@ -32,19 +34,19 @@ def _cookie_key(key):
     return b"plain.http.cookies" + force_bytes(key)
 
 
-def get_signed_cookie_signer(key, salt=""):
+def get_signed_cookie_signer(key: str, salt: str = "") -> TimestampSigner:
     """
     Create a TimestampSigner for signed cookies with the same configuration
     used by both set_signed_cookie and get_signed_cookie.
     """
     return TimestampSigner(
-        key=_cookie_key(settings.SECRET_KEY),
-        fallback_keys=map(_cookie_key, settings.SECRET_KEY_FALLBACKS),
+        key=_cookie_key(settings.SECRET_KEY).decode(),
+        fallback_keys=[_cookie_key(k).decode() for k in settings.SECRET_KEY_FALLBACKS],
         salt=key + salt,
     )
 
 
-def sign_cookie_value(key, value, salt=""):
+def sign_cookie_value(key: str, value: str, salt: str = "") -> str:
     """
     Sign a cookie value using the standard Plain cookie signing approach.
     """
@@ -52,7 +54,13 @@ def sign_cookie_value(key, value, salt=""):
     return signer.sign(value)
 
 
-def unsign_cookie_value(key, signed_value, salt="", max_age=None, default=None):
+def unsign_cookie_value(
+    key: str,
+    signed_value: str,
+    salt: str = "",
+    max_age: int | None = None,
+    default: str | None = None,
+) -> str | None:
     """
     Unsign a cookie value using the standard Plain cookie signing approach.
     Returns the default value if the signature is invalid or the cookie has expired.

plain/http/exceptions.py

@@ -0,0 +1,65 @@
+"""
+HTTP exceptions that are converted to HTTP responses by the exception handler.
+The suffix indicates the HTTP status code that will be returned.
+"""
+
+
+class NotFoundError404(Exception):
+    """The requested resource was not found (HTTP 404)"""
+
+    pass
+
+
+class ForbiddenError403(Exception):
+    """The user did not have permission to do that (HTTP 403)"""
+
+    pass
+
+
+class BadRequestError400(Exception):
+    """The request is malformed and cannot be processed (HTTP 400)"""
+
+    pass
+
+
+class SuspiciousOperationError400(Exception):
+    """The user did something suspicious (HTTP 400)"""
+
+
+class SuspiciousMultipartFormError400(SuspiciousOperationError400):
+    """Suspect MIME request in multipart form data"""
+
+    pass
+
+
+class SuspiciousFileOperationError400(SuspiciousOperationError400):
+    """A Suspicious filesystem operation was attempted"""
+
+    pass
+
+
+class TooManyFieldsSentError400(SuspiciousOperationError400):
+    """
+    The number of fields in a GET or POST request exceeded
+    settings.DATA_UPLOAD_MAX_NUMBER_FIELDS.
+    """
+
+    pass
+
+
+class TooManyFilesSentError400(SuspiciousOperationError400):
+    """
+    The number of fields in a GET or POST request exceeded
+    settings.DATA_UPLOAD_MAX_NUMBER_FILES.
+    """
+
+    pass
+
+
+class RequestDataTooBigError400(SuspiciousOperationError400):
+    """
+    The size of the request (excluding any file uploads) exceeded
+    settings.DATA_UPLOAD_MAX_MEMORY_SIZE.
+    """
+
+    pass

plain/http/middleware.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from plain.http import Request, Response
+
+
+class HttpMiddleware(ABC):
+    """
+    Abstract base class for HTTP middleware.
+
+    Subclasses must implement process_request() to handle the request/response cycle.
+
+    Example:
+        class MyMiddleware(HttpMiddleware):
+            def process_request(self, request: Request) -> Response:
+                # Pre-processing
+                response = self.get_response(request)
+                # Post-processing
+                return response
+    """
+
+    def __init__(self, get_response: Callable[[Request], Response]):
+        self.get_response = get_response
+
+    @abstractmethod
+    def process_request(self, request: Request) -> Response:
+        """Process the request and return a response. Must be implemented by subclasses."""
+        ...