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

plain/internal/files/uploadhandler.py

@@ -2,15 +2,24 @@
 Base file upload handler classes, and the built-in concrete subclasses
 """
 
+from __future__ import annotations
+
 import os
+from abc import ABC, abstractmethod
 from io import BytesIO
+from typing import TYPE_CHECKING
 
 from plain.internal.files.uploadedfile import (
     InMemoryUploadedFile,
     TemporaryUploadedFile,
+    UploadedFile,
 )
 from plain.runtime import settings
-from plain.utils.module_loading import import_string
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from plain.http import Request
 
 __all__ = [
     "UploadFileException",
@@ -19,7 +28,6 @@ __all__ = [
     "FileUploadHandler",
     "TemporaryFileUploadHandler",
     "MemoryFileUploadHandler",
-    "load_handler",
     "StopFutureHandlers",
 ]
 
@@ -37,7 +45,7 @@ class StopUpload(UploadFileException):
     This exception is raised when an upload must abort.
     """
 
-    def __init__(self, connection_reset=False):
+    def __init__(self, connection_reset: bool = False) -> None:
         """
         If ``connection_reset`` is ``True``, Plain knows will halt the upload
         without consuming the rest of the upload. This will cause the browser to
@@ -45,7 +53,7 @@ class StopUpload(UploadFileException):
         """
         self.connection_reset = connection_reset
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.connection_reset:
             return "StopUpload: Halt current upload."
         else:
@@ -69,14 +77,14 @@ class StopFutureHandlers(UploadFileException):
     pass
 
 
-class FileUploadHandler:
+class FileUploadHandler(ABC):
     """
     Base class for streaming upload handlers.
     """
 
     chunk_size = 64 * 2**10  # : The default chunk size is 64 KB.
 
-    def __init__(self, request=None):
+    def __init__(self, request: Request) -> None:
         self.file_name = None
         self.content_type = None
         self.content_length = None
@@ -85,8 +93,11 @@ class FileUploadHandler:
         self.request = request
 
     def handle_raw_input(
-        self, input_data, meta, content_length, boundary, encoding=None
-    ):
+        self,
+        input_data: Any,
+        boundary: bytes,
+        encoding: str | None = None,
+    ) -> None:
         """
         Handle the raw input from the client.
 
@@ -94,25 +105,25 @@ class FileUploadHandler:
 
             :input_data:
                 An object that supports reading via .read().
-            :meta:
-                ``request.meta``.
-            :content_length:
-                The (integer) value of the Content-Length header from the
-                client.
-            :boundary: The boundary from the Content-Type header. Be sure to
+            :boundary:
+                The boundary from the Content-Type header. Be sure to
                 prepend two '--'.
+            :encoding:
+                The encoding of the request data.
+
+        Note: Access self.request for content_length, environ, or other request data.
         """
         pass
 
     def new_file(
         self,
-        field_name,
-        file_name,
-        content_type,
-        content_length,
-        charset=None,
-        content_type_extra=None,
-    ):
+        field_name: str,
+        file_name: str,
+        content_type: str,
+        content_length: int | None,
+        charset: str | None = None,
+        content_type_extra: dict[str, str] | None = None,
+    ) -> None:
         """
         Signal that a new file has been started.
 
@@ -126,34 +137,32 @@ class FileUploadHandler:
         self.charset = charset
         self.content_type_extra = content_type_extra
 
-    def receive_data_chunk(self, raw_data, start):
+    @abstractmethod
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> bytes | None:
         """
         Receive data from the streamed upload parser. ``start`` is the position
         in the file of the chunk.
         """
-        raise NotImplementedError(
-            "subclasses of FileUploadHandler must provide a receive_data_chunk() method"
-        )
+        ...
 
-    def file_complete(self, file_size):
+    @abstractmethod
+    def file_complete(self, file_size: int) -> UploadedFile | None:
         """
         Signal that a file has completed. File size corresponds to the actual
         size accumulated by all the chunks.
 
         Subclasses should return a valid ``UploadedFile`` object.
         """
-        raise NotImplementedError(
-            "subclasses of FileUploadHandler must provide a file_complete() method"
-        )
+        ...
 
-    def upload_complete(self):
+    def upload_complete(self) -> None:
         """
         Signal that the upload is complete. Subclasses should perform cleanup
         that is necessary for this handler.
         """
         pass
 
-    def upload_interrupted(self):
+    def upload_interrupted(self) -> None:
         """
         Signal that the upload was interrupted. Subclasses should perform
         cleanup that is necessary for this handler.
@@ -166,24 +175,29 @@ class TemporaryFileUploadHandler(FileUploadHandler):
     Upload handler that streams data into a temporary file.
     """
 
-    def new_file(self, *args, **kwargs):
+    def new_file(self, *args: Any, **kwargs: Any) -> None:
         """
         Create the file object to append to as data is coming in.
         """
         super().new_file(*args, **kwargs)
+        assert self.file_name is not None, "file_name should be set by parent new_file"
+        assert self.content_type is not None, (
+            "content_type should be set by parent new_file"
+        )
         self.file = TemporaryUploadedFile(
             self.file_name, self.content_type, 0, self.charset, self.content_type_extra
         )
 
-    def receive_data_chunk(self, raw_data, start):
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> None:
         self.file.write(raw_data)
+        return None
 
-    def file_complete(self, file_size):
+    def file_complete(self, file_size: int) -> TemporaryUploadedFile:
         self.file.seek(0)
         self.file.size = file_size
         return self.file
 
-    def upload_interrupted(self):
+    def upload_interrupted(self) -> None:
         if hasattr(self, "file"):
             temp_location = self.file.temporary_file_path()
             try:
@@ -199,35 +213,43 @@ class MemoryFileUploadHandler(FileUploadHandler):
     """
 
     def handle_raw_input(
-        self, input_data, meta, content_length, boundary, encoding=None
-    ):
+        self,
+        input_data: Any,
+        boundary: bytes,
+        encoding: str | None = None,
+    ) -> None:
         """
         Use the content_length to signal whether or not this handler should be
         used.
         """
         # Check the content-length header to see if we should
         # If the post is too large, we cannot use the Memory handler.
-        self.activated = content_length <= settings.FILE_UPLOAD_MAX_MEMORY_SIZE
+        self.activated = (
+            self.request.content_length <= settings.FILE_UPLOAD_MAX_MEMORY_SIZE
+        )
 
-    def new_file(self, *args, **kwargs):
+    def new_file(self, *args: Any, **kwargs: Any) -> None:
         super().new_file(*args, **kwargs)
         if self.activated:
             self.file = BytesIO()
             raise StopFutureHandlers()
 
-    def receive_data_chunk(self, raw_data, start):
+    def receive_data_chunk(self, raw_data: bytes, start: int) -> bytes | None:
         """Add the data to the BytesIO file."""
         if self.activated:
             self.file.write(raw_data)
+            return None
         else:
             return raw_data
 
-    def file_complete(self, file_size):
+    def file_complete(self, file_size: int) -> InMemoryUploadedFile | None:
         """Return a file object if this handler is activated."""
         if not self.activated:
-            return
+            return None
 
         self.file.seek(0)
+        assert self.file_name is not None, "file_name should be set by new_file"
+        assert self.content_type is not None, "content_type should be set by new_file"
         return InMemoryUploadedFile(
             file=self.file,
             field_name=self.field_name,
@@ -237,19 +259,3 @@ class MemoryFileUploadHandler(FileUploadHandler):
             charset=self.charset,
             content_type_extra=self.content_type_extra,
         )
-
-
-def load_handler(path, *args, **kwargs):
-    """
-    Given a path to a handler, return an instance of that handler.
-
-    E.g.::
-        >>> from plain.http import HttpRequest
-        >>> request = HttpRequest()
-        >>> load_handler(
-        ...     'plain.internal.files.uploadhandler.TemporaryFileUploadHandler',
-        ...     request,
-        ... )
-        <TemporaryFileUploadHandler object at 0x...>
-    """
-    return import_string(path)(*args, **kwargs)

plain/internal/files/utils.py

@@ -1,13 +1,22 @@
+from __future__ import annotations
+
 import os
 import pathlib
+from typing import TYPE_CHECKING
+
+from plain.http import SuspiciousFileOperationError400
 
-from plain.exceptions import SuspiciousFileOperation
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+    from typing import IO, Any
 
 
-def validate_file_name(name, allow_relative_path=False):
+def validate_file_name(name: str, allow_relative_path: bool = False) -> str:
     # Remove potentially dangerous names
     if os.path.basename(name) in {"", ".", ".."}:
-        raise SuspiciousFileOperation(f"Could not derive file name from '{name}'")
+        raise SuspiciousFileOperationError400(
+            f"Could not derive file name from '{name}'"
+        )
 
     if allow_relative_path:
         # Use PurePosixPath() because this branch is checked only in
@@ -15,11 +24,13 @@ def validate_file_name(name, allow_relative_path=False):
         # Unix style (with forward slashes).
         path = pathlib.PurePosixPath(name)
         if path.is_absolute() or ".." in path.parts:
-            raise SuspiciousFileOperation(
+            raise SuspiciousFileOperationError400(
                 f"Detected path traversal attempt in '{name}'"
             )
     elif name != os.path.basename(name):
-        raise SuspiciousFileOperation(f"File name '{name}' includes path elements")
+        raise SuspiciousFileOperationError400(
+            f"File name '{name}' includes path elements"
+        )
 
     return name
 
@@ -34,6 +45,9 @@ class FileProxyMixin:
                 self.file = file
     """
 
+    # Expected to be set by subclasses
+    file: IO[Any]
+
     encoding = property(lambda self: self.file.encoding)
     fileno = property(lambda self: self.file.fileno)
     flush = property(lambda self: self.file.flush)
@@ -50,29 +64,29 @@ class FileProxyMixin:
     writelines = property(lambda self: self.file.writelines)
 
     @property
-    def closed(self):
+    def closed(self) -> bool:
         return not self.file or self.file.closed
 
-    def readable(self):
+    def readable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "readable"):
             return self.file.readable()
         return True
 
-    def writable(self):
+    def writable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "writable"):
             return self.file.writable()
         return "w" in getattr(self.file, "mode", "")
 
-    def seekable(self):
+    def seekable(self) -> bool:
         if self.closed:
             return False
         if hasattr(self.file, "seekable"):
             return self.file.seekable()
         return True
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Any]:
         return iter(self.file)

plain/internal/handlers/base.py

@@ -1,18 +1,23 @@
-import logging
+from __future__ import annotations
+
 import types
+from typing import TYPE_CHECKING
 
 from opentelemetry import baggage, trace
 from opentelemetry.semconv.attributes import http_attributes, url_attributes
 
 from plain.exceptions import ImproperlyConfigured
-from plain.logs.utils import log_response
 from plain.runtime import settings
 from plain.urls import get_resolver
 from plain.utils.module_loading import import_string
 
 from .exception import convert_exception_to_response
 
-logger = logging.getLogger("plain.request")
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import Request, Response, ResponseBase
+    from plain.urls import ResolverMatch
 
 
 # These middleware classes are always used by Plain.
@@ -34,9 +39,9 @@ tracer = trace.get_tracer("plain")
 
 
 class BaseHandler:
-    _middleware_chain = None
+    _middleware_chain: Callable[[Request], ResponseBase] | None = None
 
-    def load_middleware(self):
+    def load_middleware(self) -> None:
         """
         Populate middleware lists from settings.MIDDLEWARE.
 
@@ -57,18 +62,21 @@ class BaseHandler:
                     f"Middleware factory {middleware_path} returned None."
                 )
 
-            handler = convert_exception_to_response(mw_instance)
+            handler = convert_exception_to_response(mw_instance.process_request)
 
         # We only assign to this when initialization is complete as it is used
         # as a flag for initialization being complete.
         self._middleware_chain = handler
 
-    def get_response(self, request):
-        """Return a Response object for the given HttpRequest."""
+    def get_response(self, request: Request) -> ResponseBase:
+        """Return a Response object for the given Request."""
+        assert self._middleware_chain is not None, (
+            "load_middleware() must be called before get_response()"
+        )
 
-        span_attributes = {
+        span_attributes: dict[str, str] = {
             "plain.request.id": request.unique_id,
-            http_attributes.HTTP_REQUEST_METHOD: request.method,
+            http_attributes.HTTP_REQUEST_METHOD: request.method or "",
             url_attributes.URL_PATH: request.path_info,
             url_attributes.URL_SCHEME: request.scheme,
         }
@@ -81,10 +89,13 @@ class BaseHandler:
             pass
 
         # Add query string if present
-        if query_string := request.meta.get("QUERY_STRING"):
-            span_attributes[url_attributes.URL_QUERY] = query_string
+        if request.query_string:
+            span_attributes[url_attributes.URL_QUERY] = request.query_string
 
         span_context = baggage.set_baggage("http.request.cookies", request.cookies)
+        span_context = baggage.set_baggage(
+            "http.request.headers", request.headers, span_context
+        )
 
         with tracer.start_as_current_span(
             f"{request.method} {request.path_info}",
@@ -105,17 +116,12 @@ class BaseHandler:
                 else trace.StatusCode.ERROR
             )
 
-            if response.status_code >= 400:
-                log_response(
-                    "%s: %s",
-                    response.reason_phrase,
-                    request.path,
-                    response=response,
-                    request=request,
-                )
+            if response.exception:
+                span.record_exception(response.exception)
+
             return response
 
-    def _get_response(self, request):
+    def _get_response(self, request: Request) -> ResponseBase:
         """
         Resolve and call the view, then apply view, exception, and
         template_response middleware. This method is everything that happens
@@ -132,7 +138,7 @@ class BaseHandler:
 
         return response
 
-    def resolve_request(self, request):
+    def resolve_request(self, request: Request) -> ResolverMatch:
         """
         Retrieve/set the urlrouter for the request. Return the view resolved,
         with its args and kwargs.
@@ -154,7 +160,12 @@ class BaseHandler:
         request.resolver_match = resolver_match
         return resolver_match
 
-    def check_response(self, response, callback, name=None):
+    def check_response(
+        self,
+        response: Response | None,
+        callback: Callable[..., Response],
+        name: str | None = None,
+    ) -> None:
         """
         Raise an error if the view returned None or an uncalled coroutine.
         """

plain/internal/handlers/exception.py

@@ -1,29 +1,38 @@
+from __future__ import annotations
+
 import logging
 from functools import wraps
-
-from plain import signals
-from plain.exceptions import (
-    BadRequest,
-    PermissionDenied,
-    RequestDataTooBig,
-    SuspiciousOperation,
-    TooManyFieldsSent,
-    TooManyFilesSent,
+from typing import TYPE_CHECKING
+
+from plain.forms.exceptions import FormFieldMissingError
+from plain.http import (
+    BadRequestError400,
+    ForbiddenError403,
+    NotFoundError404,
+    Response,
+    SuspiciousOperationError400,
 )
-from plain.http import Http404, ResponseServerError
 from plain.http.multipartparser import MultiPartParserError
-from plain.logs.utils import log_response
 from plain.runtime import settings
-from plain.utils.module_loading import import_string
 from plain.views.errors import ErrorView
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import Request, Response, ResponseBase
+
 
-def convert_exception_to_response(get_response):
+request_logger = logging.getLogger("plain.request")
+
+
+def convert_exception_to_response(
+    get_response: Callable[[Request], ResponseBase],
+) -> Callable[[Request], ResponseBase]:
     """
     Wrap the given get_response callable in exception-to-response conversion.
 
-    All exceptions will be converted. All known 4xx exceptions (Http404,
-    PermissionDenied, MultiPartParserError, SuspiciousOperation) will be
+    All exceptions will be converted. All known 4xx exceptions (NotFoundError404,
+    ForbiddenError403, MultiPartParserError, SuspiciousOperationError400) will be
     converted to the appropriate response, and all other exceptions will be
     converted to 500 responses.
 
@@ -33,7 +42,7 @@ def convert_exception_to_response(get_response):
     """
 
     @wraps(get_response)
-    def inner(request):
+    def inner(request: Request) -> ResponseBase:
         try:
             response = get_response(request)
         except Exception as exc:
@@ -43,106 +52,100 @@ def convert_exception_to_response(get_response):
     return inner
 
 
-def response_for_exception(request, exc):
-    if isinstance(exc, Http404):
+def response_for_exception(request: Request, exc: Exception) -> Response:
+    if isinstance(exc, NotFoundError404):
         response = get_exception_response(
             request=request, status_code=404, exception=None
         )
 
-    elif isinstance(exc, PermissionDenied):
+    elif isinstance(exc, ForbiddenError403):
         response = get_exception_response(
             request=request, status_code=403, exception=exc
         )
-        log_response(
+        request_logger.warning(
             "Forbidden (Permission denied): %s",
             request.path,
-            response=response,
-            request=request,
-            exception=exc,
+            extra={"status_code": response.status_code, "request": request},
+            exc_info=exc,
         )
 
     elif isinstance(exc, MultiPartParserError):
         response = get_exception_response(
             request=request, status_code=400, exception=None
         )
-        log_response(
+        request_logger.warning(
             "Bad request (Unable to parse request body): %s",
             request.path,
-            response=response,
-            request=request,
-            exception=exc,
+            extra={"status_code": response.status_code, "request": request},
+            exc_info=exc,
         )
 
-    elif isinstance(exc, BadRequest):
+    elif isinstance(exc, BadRequestError400):
         response = get_exception_response(
             request=request, status_code=400, exception=exc
         )
-        log_response(
+        request_logger.warning(
             "%s: %s",
             str(exc),
             request.path,
-            response=response,
-            request=request,
-            exception=exc,
+            extra={"status_code": response.status_code, "request": request},
+            exc_info=exc,
         )
-    elif isinstance(exc, SuspiciousOperation):
-        if isinstance(exc, RequestDataTooBig | TooManyFieldsSent | TooManyFilesSent):
-            # POST data can't be accessed again, otherwise the original
-            # exception would be raised.
-            request._mark_post_parse_error()
-
+    elif isinstance(exc, SuspiciousOperationError400):
         # The request logger receives events for any problematic request
-        # The security logger receives events for all SuspiciousOperations
+        # The security logger receives events for all SuspiciousOperationError400s
         security_logger = logging.getLogger(f"plain.security.{exc.__class__.__name__}")
         security_logger.error(
             str(exc),
-            exc_info=exc,
             extra={"status_code": 400, "request": request},
+            exc_info=exc,
+        )
+        response = get_exception_response(
+            request=request, status_code=400, exception=None
         )
+
+    elif isinstance(exc, FormFieldMissingError):
         response = get_exception_response(
             request=request, status_code=400, exception=None
         )
+        request_logger.warning(
+            "Bad request (missing form field '%s'): %s",
+            exc.field_name,
+            request.path,
+            extra={"status_code": 400, "request": request},
+        )
 
     else:
-        signals.got_request_exception.send(sender=None, request=request)
         response = get_exception_response(
             request=request, status_code=500, exception=None
         )
-        log_response(
+        request_logger.error(
             "%s: %s",
             response.reason_phrase,
             request.path,
-            response=response,
-            request=request,
-            exception=exc,
+            extra={"status_code": response.status_code, "request": request},
+            exc_info=exc,
         )
 
     return response
 
 
-def get_exception_response(*, request, status_code, exception):
+def get_exception_response(
+    *, request: Request, status_code: int, exception: Exception | None
+) -> Response:
     try:
-        view_class = get_error_view(status_code=status_code, exception=exception)
-        return view_class(request)
-    except Exception:
-        signals.got_request_exception.send(sender=None, request=request)
-
+        view_class = ErrorView.as_view(status_code=status_code, exception=exception)
+        response = view_class(request)
+        if response.status_code >= 500 and exception is not None:
+            # Attach the exception to the response for logging/observability
+            response.exception = exception
+        return response
+    except Exception as e:
         # In development mode, re-raise the exception to get a full stack trace
         if settings.DEBUG:
             raise
 
         # If we can't load the view, return a 500 response
-        return ResponseServerError()
-
-
-def get_error_view(*, status_code, exception):
-    views_by_status = settings.HTTP_ERROR_VIEWS
-    if status_code in views_by_status:
-        view = views_by_status[status_code]
-        if isinstance(view, str):
-            # Import the view if it's a string
-            view = import_string(view)
-        return view.as_view()
-
-    # Create a standard view for any other status code
-    return ErrorView.as_view(status_code=status_code, exception=exception)
+        response = Response(status_code=500)
+        response.exception = e
+        return response