plain 0.69.0__py3-none-any.whl → 0.70.0__py3-none-any.whl

plain/internal/handlers/exception.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import logging
 from functools import wraps
+from typing import TYPE_CHECKING
 
 from plain import signals
 from plain.exceptions import (
@@ -17,8 +20,15 @@ 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 HttpRequest, Response
+
 
-def convert_exception_to_response(get_response):
+def convert_exception_to_response(
+    get_response: Callable[[HttpRequest], Response],
+) -> Callable[[HttpRequest], Response]:
     """
     Wrap the given get_response callable in exception-to-response conversion.
 
@@ -33,7 +43,7 @@ def convert_exception_to_response(get_response):
     """
 
     @wraps(get_response)
-    def inner(request):
+    def inner(request: HttpRequest) -> Response:
         try:
             response = get_response(request)
         except Exception as exc:
@@ -43,7 +53,7 @@ def convert_exception_to_response(get_response):
     return inner
 
 
-def response_for_exception(request, exc):
+def response_for_exception(request: HttpRequest, exc: Exception) -> Response:
     if isinstance(exc, Http404):
         response = get_exception_response(
             request=request, status_code=404, exception=None
@@ -120,7 +130,9 @@ def response_for_exception(request, exc):
     return response
 
 
-def get_exception_response(*, request, status_code, exception):
+def get_exception_response(
+    *, request: HttpRequest, status_code: int, exception: Exception | None
+) -> Response:
     try:
         view_class = get_error_view(status_code=status_code, exception=exception)
         return view_class(request)
@@ -135,7 +147,9 @@ def get_exception_response(*, request, status_code, exception):
         return ResponseServerError()
 
 
-def get_error_view(*, status_code, exception):
+def get_error_view(
+    *, status_code: int, exception: Exception | None
+) -> Callable[[HttpRequest], Response]:
     views_by_status = settings.HTTP_ERROR_VIEWS
     if status_code in views_by_status:
         view = views_by_status[status_code]

plain/internal/handlers/wsgi.py

@@ -1,13 +1,21 @@
+from __future__ import annotations
+
 import uuid
 from functools import cached_property
 from io import IOBase
+from typing import TYPE_CHECKING
 from urllib.parse import quote
 
 from plain import signals
 from plain.http import HttpRequest, QueryDict, parse_cookie
 from plain.internal.handlers import base
+from plain.utils.datastructures import MultiValueDict
 from plain.utils.regex_helper import _lazy_re_compile
 
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable
+    from typing import Any
+
 _slashes_re = _lazy_re_compile(rb"/+")
 
 
@@ -19,13 +27,13 @@ class LimitedStream(IOBase):
     See https://github.com/pallets/werkzeug/blob/dbf78f67/src/werkzeug/wsgi.py#L828
     """
 
-    def __init__(self, stream, limit):
+    def __init__(self, stream: Any, limit: int) -> None:
         self._read = stream.read
         self._readline = stream.readline
         self._pos = 0
         self.limit = limit
 
-    def read(self, size=-1, /):
+    def read(self, size: int = -1, /) -> bytes:
         _pos = self._pos
         limit = self.limit
         if _pos >= limit:
@@ -38,7 +46,7 @@ class LimitedStream(IOBase):
         self._pos += len(data)
         return data
 
-    def readline(self, size=-1, /):
+    def readline(self, size: int = -1, /) -> bytes:
         _pos = self._pos
         limit = self.limit
         if _pos >= limit:
@@ -56,7 +64,7 @@ class WSGIRequest(HttpRequest):
     non_picklable_attrs = HttpRequest.non_picklable_attrs | frozenset(["environ"])
     meta_non_picklable_attrs = frozenset(["wsgi.errors", "wsgi.input"])
 
-    def __init__(self, environ):
+    def __init__(self, environ: dict[str, Any]) -> None:
         # A unique ID we can use to trace this request
         self.unique_id = str(uuid.uuid4())
 
@@ -86,37 +94,37 @@ class WSGIRequest(HttpRequest):
         self._read_started = False
         self.resolver_match = None
 
-    def __getstate__(self):
+    def __getstate__(self) -> dict[str, Any]:
         state = super().__getstate__()
         for attr in self.meta_non_picklable_attrs:
             if attr in state["meta"]:
                 del state["meta"][attr]
         return state
 
-    def _get_scheme(self):
+    def _get_scheme(self) -> str | None:
         return self.environ.get("wsgi.url_scheme")
 
     @cached_property
-    def query_params(self):
+    def query_params(self) -> QueryDict:
         # The WSGI spec says 'QUERY_STRING' may be absent.
         raw_query_string = get_bytes_from_wsgi(self.environ, "QUERY_STRING", "")
         return QueryDict(raw_query_string, encoding=self._encoding)
 
-    def _get_data(self):
+    def _get_data(self) -> QueryDict:
         if not hasattr(self, "_data"):
             self._load_data_and_files()
         return self._data
 
-    def _set_data(self, data):
+    def _set_data(self, data: QueryDict) -> None:
         self._data = data
 
     @cached_property
-    def cookies(self):
+    def cookies(self) -> dict[str, str]:
         raw_cookie = get_str_from_wsgi(self.environ, "HTTP_COOKIE", "")
         return parse_cookie(raw_cookie)
 
     @property
-    def files(self):
+    def files(self) -> MultiValueDict:
         if not hasattr(self, "_files"):
             self._load_data_and_files()
         return self._files
@@ -125,11 +133,15 @@ class WSGIRequest(HttpRequest):
 
 
 class WSGIHandler(base.BaseHandler):
-    def __init__(self, *args, **kwargs):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
         super().__init__(*args, **kwargs)
         self.load_middleware()
 
-    def __call__(self, environ, start_response):
+    def __call__(
+        self,
+        environ: dict[str, Any],
+        start_response: Callable[[str, list[tuple[str, str]]], Any],
+    ) -> Iterable[bytes]:
         signals.request_started.send(sender=self.__class__, environ=environ)
         request = WSGIRequest(environ)
         response = self.get_response(request)
@@ -155,11 +167,11 @@ class WSGIHandler(base.BaseHandler):
         return response
 
 
-def get_path_info(environ):
+def get_path_info(environ: dict[str, Any]) -> str:
     """Return the HTTP request's PATH_INFO as a string."""
     path_info = get_bytes_from_wsgi(environ, "PATH_INFO", "/")
 
-    def repercent_broken_unicode(path):
+    def repercent_broken_unicode(path: bytes) -> bytes:
         """
         As per RFC 3987 Section 3.2, step three of converting a URI into an IRI,
         repercent-encode any octet produced that is not part of a strictly legal
@@ -179,7 +191,7 @@ def get_path_info(environ):
     return repercent_broken_unicode(path_info).decode()
 
 
-def get_script_name(environ):
+def get_script_name(environ: dict[str, Any]) -> str:
     """
     Return the equivalent of the HTTP request's SCRIPT_NAME environment
     variable. If Apache mod_rewrite is used, return what would have been
@@ -208,7 +220,7 @@ def get_script_name(environ):
     return script_name.decode()
 
 
-def get_bytes_from_wsgi(environ, key, default):
+def get_bytes_from_wsgi(environ: dict[str, Any], key: str, default: str) -> bytes:
     """
     Get a value from the WSGI environ dictionary as bytes.
 
@@ -221,7 +233,7 @@ def get_bytes_from_wsgi(environ, key, default):
     return value.encode("iso-8859-1")
 
 
-def get_str_from_wsgi(environ, key, default):
+def get_str_from_wsgi(environ: dict[str, Any], key: str, default: str) -> str:
     """
     Get a value from the WSGI environ dictionary as str.
 

plain/internal/middleware/headers.py

@@ -1,11 +1,20 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from plain.runtime import settings
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import HttpRequest, Response
+
 
 class DefaultHeadersMiddleware:
-    def __init__(self, get_response):
+    def __init__(self, get_response: Callable[[HttpRequest], Response]) -> None:
         self.get_response = get_response
 
-    def __call__(self, request):
+    def __call__(self, request: HttpRequest) -> Response:
         response = self.get_response(request)
 
         for header, value in settings.DEFAULT_RESPONSE_HEADERS.items():

plain/internal/middleware/hosts.py

@@ -1,10 +1,18 @@
+from __future__ import annotations
+
 import ipaddress
 import logging
+from typing import TYPE_CHECKING
 
 from plain.http import HttpRequest, ResponseBadRequest
 from plain.runtime import settings
 from plain.utils.regex_helper import _lazy_re_compile
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import Response
+
 logger = logging.getLogger(__name__)
 
 host_validation_re = _lazy_re_compile(
@@ -21,10 +29,10 @@ class HostValidationMiddleware:
     host is not allowed.
     """
 
-    def __init__(self, get_response):
+    def __init__(self, get_response: Callable[[HttpRequest], Response]) -> None:
         self.get_response = get_response
 
-    def __call__(self, request):
+    def __call__(self, request: HttpRequest) -> Response:
         if not is_host_valid(request):
             host = request.host
             msg = f"Invalid HTTP_HOST header: {host!r}."

plain/internal/middleware/https.py

@@ -1,15 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from plain.http import ResponseRedirect
 from plain.runtime import settings
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import HttpRequest, Response
+
 
 class HttpsRedirectMiddleware:
-    def __init__(self, get_response):
+    def __init__(self, get_response: Callable[[HttpRequest], Response]) -> None:
         self.get_response = get_response
 
         # Settings for HTTPS
         self.https_redirect_enabled = settings.HTTPS_REDIRECT_ENABLED
 
-    def __call__(self, request):
+    def __call__(self, request: HttpRequest) -> Response:
         """
         Perform a blanket HTTP→HTTPS redirect when enabled.
         """
@@ -19,8 +28,9 @@ class HttpsRedirectMiddleware:
 
         return self.get_response(request)
 
-    def maybe_https_redirect(self, request):
+    def maybe_https_redirect(self, request: HttpRequest) -> Response | None:
         if self.https_redirect_enabled and not request.is_https():
             return ResponseRedirect(
                 f"https://{request.host}{request.get_full_path()}", status_code=301
             )
+        return None

plain/internal/middleware/slash.py

@@ -1,14 +1,24 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
 from plain.http import ResponseRedirect
 from plain.runtime import settings
 from plain.urls import Resolver404, get_resolver
 from plain.utils.http import escape_leading_slashes
 
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from plain.http import HttpRequest, Response
+    from plain.urls import ResolverMatch
+
 
 class RedirectSlashMiddleware:
-    def __init__(self, get_response):
+    def __init__(self, get_response: Callable[[HttpRequest], Response]) -> None:
         self.get_response = get_response
 
-    def __call__(self, request):
+    def __call__(self, request: HttpRequest) -> Response:
         """
         Rewrite the URL based on settings.APPEND_SLASH
         """
@@ -29,7 +39,7 @@ class RedirectSlashMiddleware:
         return response
 
     @staticmethod
-    def _is_valid_path(path):
+    def _is_valid_path(path: str) -> ResolverMatch | bool:
         """
         Return the ResolverMatch if the given path resolves against the default URL
         resolver, False otherwise. This is a convenience method to make working
@@ -40,7 +50,7 @@ class RedirectSlashMiddleware:
         except Resolver404:
             return False
 
-    def should_redirect_with_slash(self, request):
+    def should_redirect_with_slash(self, request: HttpRequest) -> ResolverMatch | bool:
         """
         Return True if settings.APPEND_SLASH is True and appending a slash to
         the request path turns an invalid path into a valid one.
@@ -50,7 +60,7 @@ class RedirectSlashMiddleware:
                 return self._is_valid_path(f"{request.path_info}/")
         return False
 
-    def get_full_path_with_slash(self, request):
+    def get_full_path_with_slash(self, request: HttpRequest) -> str:
         """
         Return the full path of the request with a trailing slash appended.
 

plain/json.py

@@ -2,6 +2,7 @@ import datetime
 import decimal
 import json
 import uuid
+from typing import Any
 
 from plain.utils.duration import duration_iso_string
 from plain.utils.functional import Promise
@@ -14,7 +15,7 @@ class PlainJSONEncoder(json.JSONEncoder):
     UUIDs.
     """
 
-    def default(self, o):
+    def default(self, o: Any) -> Any:
         # See "Date Time String Format" in the ECMA-262 specification.
         if isinstance(o, datetime.datetime):
             r = o.isoformat()

plain/logs/configure.py

@@ -3,7 +3,9 @@ import logging
 from .formatters import JSONFormatter, KeyValueFormatter
 
 
-def configure_logging(*, plain_log_level, app_log_level, app_log_format):
+def configure_logging(
+    *, plain_log_level: int | str, app_log_level: int | str, app_log_format: str
+) -> None:
     # Create and configure the plain logger (uses standard Logger, not AppLogger)
     plain_logger = logging.Logger("plain")
     plain_logger.setLevel(plain_log_level)

plain/logs/debug.py

@@ -1,26 +1,37 @@
+from __future__ import annotations
+
 import logging
 import threading
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from types import TracebackType
 
 
 class DebugMode:
     """Context manager to temporarily set DEBUG level on a logger with reference counting."""
 
-    def __init__(self, logger):
+    def __init__(self, logger: logging.Logger):
         self.logger = logger
         self.original_level = None
         self._ref_count = 0
         self._lock = threading.Lock()
 
-    def __enter__(self):
+    def __enter__(self) -> DebugMode:
         """Store original level and set to DEBUG."""
         self.start()
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         """Restore original level."""
         self.end()
 
-    def start(self):
+    def start(self) -> None:
         """Enable DEBUG logging level."""
         with self._lock:
             if self._ref_count == 0:
@@ -28,7 +39,7 @@ class DebugMode:
                 self.logger.setLevel(logging.DEBUG)
             self._ref_count += 1
 
-    def end(self):
+    def end(self) -> None:
         """Restore original logging level."""
         with self._lock:
             self._ref_count = max(0, self._ref_count - 1)

plain/logs/formatters.py

@@ -1,11 +1,14 @@
+from __future__ import annotations
+
 import json
 import logging
+from typing import Any
 
 
 class KeyValueFormatter(logging.Formatter):
     """Formatter that outputs key-value pairs from Plain's context system."""
 
-    def format(self, record):
+    def format(self, record: logging.LogRecord) -> str:
         # Build key-value pairs from context
         kv_pairs = []
 
@@ -22,7 +25,7 @@ class KeyValueFormatter(logging.Formatter):
         return super().format(record)
 
     @staticmethod
-    def _format_value(value):
+    def _format_value(value: Any) -> str:
         """Format a value for key-value output."""
         if isinstance(value, str):
             s = value
@@ -46,7 +49,7 @@ class KeyValueFormatter(logging.Formatter):
 class JSONFormatter(logging.Formatter):
     """Formatter that outputs JSON from Plain's context system, with optional format string."""
 
-    def format(self, record):
+    def format(self, record: logging.LogRecord) -> str:
         # Build the JSON object from Plain's context data
         log_obj = {
             "timestamp": self.formatTime(record),

plain/logs/loggers.py

@@ -1,5 +1,9 @@
+from __future__ import annotations
+
 import logging
+from collections.abc import Generator
 from contextlib import contextmanager
+from typing import Any
 
 from .debug import DebugMode
 
@@ -7,13 +11,13 @@ from .debug import DebugMode
 class AppLogger(logging.Logger):
     """Enhanced logger that supports kwargs-style logging and context management."""
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         super().__init__(name)
         self.context = {}  # Public, mutable context dict
         self.debug_mode = DebugMode(self)
 
     @contextmanager
-    def include_context(self, **kwargs):
+    def include_context(self, **kwargs: Any) -> Generator[None, None, None]:
         """Context manager for temporary context."""
         # Store original context
         original_context = self.context.copy()
@@ -27,21 +31,21 @@ class AppLogger(logging.Logger):
             # Restore original context
             self.context = original_context
 
-    def force_debug(self):
+    def force_debug(self) -> DebugMode:
         """Return context manager for temporarily enabling DEBUG level logging."""
         return self.debug_mode
 
     # Override logging methods with explicit parameters for IDE support
     def debug(
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         if self.isEnabledFor(logging.DEBUG):
             self._log(
                 logging.DEBUG,
@@ -56,14 +60,14 @@ class AppLogger(logging.Logger):
 
     def info(
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         if self.isEnabledFor(logging.INFO):
             self._log(
                 logging.INFO,
@@ -78,14 +82,14 @@ class AppLogger(logging.Logger):
 
     def warning(
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         if self.isEnabledFor(logging.WARNING):
             self._log(
                 logging.WARNING,
@@ -100,14 +104,14 @@ class AppLogger(logging.Logger):
 
     def error(
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         if self.isEnabledFor(logging.ERROR):
             self._log(
                 logging.ERROR,
@@ -122,14 +126,14 @@ class AppLogger(logging.Logger):
 
     def critical(
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         if self.isEnabledFor(logging.CRITICAL):
             self._log(
                 logging.CRITICAL,
@@ -144,15 +148,15 @@ class AppLogger(logging.Logger):
 
     def _log(
         self,
-        level,
-        msg,
-        args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        level: int,
+        msg: object,
+        args: tuple[object, ...],
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        **context: Any,
+    ) -> None:
         """Low-level logging routine which creates a LogRecord and then calls all handlers."""
         # Check if extra already has a 'context' key
         if extra and "context" in extra: