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

plain/test/encoding.py

@@ -1,12 +1,15 @@
+from __future__ import annotations
+
 import mimetypes
 import os
+from typing import Any
 
 from plain.runtime import settings
 from plain.utils.encoding import force_bytes
 from plain.utils.itercompat import is_iterable
 
 
-def encode_multipart(boundary, data):
+def encode_multipart(boundary: str, data: dict[str, Any]) -> bytes:
     """
     Encode multipart POST data from a dictionary of form values.
 
@@ -14,13 +17,13 @@ def encode_multipart(boundary, data):
     as content. If the value is a file, the contents of the file will be sent
     as an application/octet-stream; otherwise, str(value) will be sent.
     """
-    lines = []
+    lines: list[bytes] = []
 
-    def to_bytes(s):
+    def to_bytes(s: str) -> bytes:
         return force_bytes(s, settings.DEFAULT_CHARSET)
 
     # Not by any means perfect, but good enough for our purposes.
-    def is_file(thing):
+    def is_file(thing: Any) -> bool:
         return hasattr(thing, "read") and callable(thing.read)
 
     # Each bit of the multipart form data could be either a form value or a
@@ -68,8 +71,8 @@ def encode_multipart(boundary, data):
     return b"\r\n".join(lines)
 
 
-def encode_file(boundary, key, file):
-    def to_bytes(s):
+def encode_file(boundary: str, key: str, file: Any) -> list[bytes]:
+    def to_bytes(s: str) -> bytes:
         return force_bytes(s, settings.DEFAULT_CHARSET)
 
     # file.name might not be a string. For example, it's an int for

plain/test/exceptions.py

@@ -1,7 +1,15 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from plain.http import Response
+
+
 class RedirectCycleError(Exception):
     """The test client has been asked to follow a redirect loop."""
 
-    def __init__(self, message, last_response):
+    def __init__(self, message: str, last_response: Response) -> None:
         super().__init__(message)
         self.last_response = last_response
-        self.redirect_chain = last_response.redirect_chain
+        self.redirect_chain: list[tuple[str, int]] = last_response.redirect_chain  # type: ignore[attr-defined]

plain/urls/converters.py

@@ -1,34 +1,37 @@
+from __future__ import annotations
+
 import functools
 import uuid
+from typing import Any
 
 
 class IntConverter:
     regex = "[0-9]+"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> int:
         return int(value)
 
-    def to_url(self, value):
+    def to_url(self, value: int) -> str:
         return str(value)
 
 
 class StringConverter:
     regex = "[^/]+"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> str:
         return value
 
-    def to_url(self, value):
+    def to_url(self, value: str) -> str:
         return value
 
 
 class UUIDConverter:
     regex = "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
 
-    def to_python(self, value):
+    def to_python(self, value: str) -> uuid.UUID:
         return uuid.UUID(value)
 
-    def to_url(self, value):
+    def to_url(self, value: uuid.UUID) -> str:
         return str(value)
 
 
@@ -49,18 +52,18 @@ DEFAULT_CONVERTERS = {
 }
 
 
-REGISTERED_CONVERTERS = {}
+REGISTERED_CONVERTERS: dict[str, Any] = {}
 
 
-def register_converter(converter, type_name):
+def register_converter(converter: type, type_name: str) -> None:
     REGISTERED_CONVERTERS[type_name] = converter()
     get_converters.cache_clear()
 
 
 @functools.cache
-def get_converters():
+def get_converters() -> dict[str, Any]:
     return {**DEFAULT_CONVERTERS, **REGISTERED_CONVERTERS}
 
 
-def get_converter(raw_converter):
+def get_converter(raw_converter: str) -> Any:
     return get_converters()[raw_converter]

plain/urls/patterns.py

@@ -1,5 +1,8 @@
+from __future__ import annotations
+
 import re
 import string
+from typing import Any
 
 from plain.exceptions import ImproperlyConfigured
 from plain.internal import internalcode
@@ -12,7 +15,7 @@ from .converters import get_converter
 
 @internalcode
 class CheckURLMixin:
-    def describe(self):
+    def describe(self) -> str:
         """
         Format the URL pattern for display in warning messages.
         """
@@ -21,7 +24,7 @@ class CheckURLMixin:
             description += f" [name='{self.name}']"
         return description
 
-    def _check_pattern_startswith_slash(self):
+    def _check_pattern_startswith_slash(self) -> list[PreflightResult]:
         """
         Check that the pattern does not begin with a forward slash.
         """
@@ -44,14 +47,14 @@ class CheckURLMixin:
 
 
 class RegexPattern(CheckURLMixin):
-    def __init__(self, regex, name=None, is_endpoint=False):
+    def __init__(self, regex: str, name: str | None = None, is_endpoint: bool = False):
         self._regex = regex
         self._is_endpoint = is_endpoint
         self.name = name
-        self.converters = {}
+        self.converters: dict[str, Any] = {}
         self.regex = self._compile(str(regex))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[Any, ...], dict[str, Any]] | None:
         match = (
             self.regex.fullmatch(path)
             if self._is_endpoint and self.regex.pattern.endswith("$")
@@ -67,14 +70,14 @@ class RegexPattern(CheckURLMixin):
             return path[match.end() :], args, kwargs
         return None
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = []
         warnings.extend(self._check_pattern_startswith_slash())
         if not self._is_endpoint:
             warnings.extend(self._check_include_trailing_dollar())
         return warnings
 
-    def _check_include_trailing_dollar(self):
+    def _check_include_trailing_dollar(self) -> list[PreflightResult]:
         regex_pattern = self.regex.pattern
         if regex_pattern.endswith("$") and not regex_pattern.endswith(r"\$"):
             return [
@@ -87,7 +90,7 @@ class RegexPattern(CheckURLMixin):
         else:
             return []
 
-    def _compile(self, regex):
+    def _compile(self, regex: str) -> re.Pattern[str]:
         """Compile and return the given regular expression."""
         try:
             return re.compile(regex)
@@ -96,7 +99,7 @@ class RegexPattern(CheckURLMixin):
                 f'"{regex}" is not a valid regular expression: {e}'
             ) from e
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._regex)
 
 
@@ -105,7 +108,9 @@ _PATH_PARAMETER_COMPONENT_RE = _lazy_re_compile(
 )
 
 
-def _route_to_regex(route, is_endpoint=False):
+def _route_to_regex(
+    route: str, is_endpoint: bool = False
+) -> tuple[str, dict[str, Any]]:
     """
     Convert a path pattern into a regular expression. Return the regular
     expression and a dictionary mapping the capture names to the converters.
@@ -151,14 +156,14 @@ def _route_to_regex(route, is_endpoint=False):
 
 
 class RoutePattern(CheckURLMixin):
-    def __init__(self, route, name=None, is_endpoint=False):
+    def __init__(self, route: str, name: str | None = None, is_endpoint: bool = False):
         self._route = route
         self._is_endpoint = is_endpoint
         self.name = name
         self.converters = _route_to_regex(str(route), is_endpoint)[1]
         self.regex = self._compile(str(route))
 
-    def match(self, path):
+    def match(self, path: str) -> tuple[str, tuple[()], dict[str, Any]] | None:
         match = self.regex.search(path)
         if match:
             # RoutePattern doesn't allow non-named groups so args are ignored.
@@ -172,7 +177,7 @@ class RoutePattern(CheckURLMixin):
             return path[match.end() :], (), kwargs
         return None
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_startswith_slash()
         route = self._route
         if "(?P<" in route or route.startswith("^") or route.endswith("$"):
@@ -187,28 +192,34 @@ class RoutePattern(CheckURLMixin):
             )
         return warnings
 
-    def _compile(self, route):
+    def _compile(self, route: str) -> re.Pattern[str]:
         return re.compile(_route_to_regex(route, self._is_endpoint)[0])
 
-    def __str__(self):
+    def __str__(self) -> str:
         return str(self._route)
 
 
 class URLPattern:
-    def __init__(self, *, pattern, view, name=None):
+    def __init__(
+        self,
+        *,
+        pattern: RegexPattern | RoutePattern,
+        view: Any,
+        name: str | None = None,
+    ):
         self.pattern = pattern
         self.view = view
         self.name = name
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {self.pattern.describe()}>"
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         warnings = self._check_pattern_name()
         warnings.extend(self.pattern.preflight())
         return warnings
 
-    def _check_pattern_name(self):
+    def _check_pattern_name(self) -> list[PreflightResult]:
         """
         Check that the pattern name does not contain a colon.
         """
@@ -223,7 +234,7 @@ class URLPattern:
         else:
             return []
 
-    def resolve(self, path):
+    def resolve(self, path: str) -> Any:
         match = self.pattern.match(path)
         if match:
             new_path, args, captured_kwargs = match
@@ -236,3 +247,4 @@ class URLPattern:
                 url_name=self.pattern.name,
                 route=str(self.pattern),
             )
+        return None

plain/urls/resolvers.py

@@ -6,9 +6,12 @@ a string) and returns a ResolverMatch object which provides access to all
 attributes of the resolved URL match.
 """
 
+from __future__ import annotations
+
 import functools
 import re
 from threading import local
+from typing import TYPE_CHECKING, Any
 from urllib.parse import quote
 
 from plain.runtime import settings
@@ -18,19 +21,24 @@ from plain.utils.module_loading import import_string
 from plain.utils.regex_helper import normalize
 
 from .exceptions import NoReverseMatch, Resolver404
-from .patterns import RegexPattern, URLPattern
+from .patterns import RegexPattern, RoutePattern, URLPattern
+
+if TYPE_CHECKING:
+    from plain.preflight import PreflightResult
+
+    from .routers import Router
 
 
 class ResolverMatch:
     def __init__(
         self,
         *,
-        view,
-        args,
-        kwargs,
-        url_name=None,
-        namespaces=None,
-        route=None,
+        view: Any,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        url_name: str | None = None,
+        namespaces: list[str] | None = None,
+        route: str | None = None,
     ):
         self.view = view
         self.args = args
@@ -48,7 +56,7 @@ class ResolverMatch:
         )
 
 
-def get_resolver(router=None):
+def get_resolver(router: str | Router | None = None) -> URLResolver:
     if router is None:
         router = settings.URLS_ROUTER
 
@@ -56,7 +64,7 @@ def get_resolver(router=None):
 
 
 @functools.cache
-def _get_cached_resolver(router):
+def _get_cached_resolver(router: str | Router) -> URLResolver:
     if isinstance(router, str):
         # Do this inside the cached call, primarily for the URLS_ROUTER
         router_class = import_string(router)
@@ -66,7 +74,9 @@ def _get_cached_resolver(router):
 
 
 @functools.cache
-def get_ns_resolver(ns_pattern, resolver, converters):
+def get_ns_resolver(
+    ns_pattern: str, resolver: URLResolver, converters: tuple[tuple[str, Any], ...]
+) -> URLResolver:
     from .routers import Router
 
     # Build a namespaced resolver for the given parent urls_module pattern.
@@ -95,13 +105,13 @@ class URLResolver:
     def __init__(
         self,
         *,
-        pattern,
-        router,
+        pattern: RegexPattern | RoutePattern,
+        router: Router,
     ):
         self.pattern = pattern
         self.router = router
-        self._reverse_dict = {}
-        self._namespace_dict = {}
+        self._reverse_dict: dict[Any, Any] = {}
+        self._namespace_dict: dict[str, tuple[str, URLResolver]] = {}
         self._populated = False
         self._local = local()
 
@@ -110,17 +120,17 @@ class URLResolver:
         self.namespace = self.router.namespace
         self.url_patterns = self.router.urls
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__} {repr(self.router)} ({self.namespace}) {self.pattern.describe()}>"
 
-    def preflight(self):
+    def preflight(self) -> list[PreflightResult]:
         messages = []
         messages.extend(self.pattern.preflight())
         for pattern in self.url_patterns:
             messages.extend(pattern.preflight())
         return messages
 
-    def _populate(self):
+    def _populate(self) -> None:
         # Short-circuit if called recursively in this thread to prevent
         # infinite recursion. Concurrent threads may call this at the same
         # time and will need to continue, so set 'populating' on a
@@ -191,26 +201,26 @@ class URLResolver:
             self._local.populating = False
 
     @property
-    def reverse_dict(self):
+    def reverse_dict(self) -> MultiValueDict:
         if not self._reverse_dict:
             self._populate()
         return self._reverse_dict
 
     @property
-    def namespace_dict(self):
+    def namespace_dict(self) -> dict[str, tuple[str, URLResolver]]:
         if not self._namespace_dict:
             self._populate()
         return self._namespace_dict
 
     @staticmethod
-    def _join_route(route1, route2):
+    def _join_route(route1: str, route2: str) -> str:
         """Join two routes, without the starting ^ in the second route."""
         if not route1:
             return route2
         route2 = route2.removeprefix("^")
         return route1 + route2
 
-    def resolve(self, path):
+    def resolve(self, path: str) -> ResolverMatch:
         path = str(path)  # path may be a reverse_lazy object
         match = self.pattern.match(path)
         if match:
@@ -247,7 +257,7 @@ class URLResolver:
             raise Resolver404({"path": new_path})
         raise Resolver404({"path": path})
 
-    def reverse(self, lookup_view, *args, **kwargs):
+    def reverse(self, lookup_view: Any, *args: Any, **kwargs: Any) -> str:
         if args and kwargs:
             raise ValueError("Don't mix *args and **kwargs in call to reverse()!")
 

plain/urls/utils.py

@@ -1,10 +1,14 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.utils.functional import lazy
 
 from .exceptions import NoReverseMatch
 from .resolvers import get_ns_resolver, get_resolver
 
 
-def reverse(url_name: str, *args, **kwargs):
+def reverse(url_name: str, *args: Any, **kwargs: Any) -> str:
     resolver = get_resolver()
 
     *path, view = url_name.split(":")

plain/utils/cache.py

@@ -15,16 +15,22 @@ An example: i18n middleware would need to distinguish caches by the
 "Accept-language" header.
 """
 
+from __future__ import annotations
+
 import time
 from collections import defaultdict
+from typing import TYPE_CHECKING, Any
 
 from .http import http_date
 from .regex_helper import _lazy_re_compile
 
+if TYPE_CHECKING:
+    from plain.http import Response
+
 cc_delim_re = _lazy_re_compile(r"\s*,\s*")
 
 
-def patch_response_headers(response, cache_timeout):
+def patch_response_headers(response: Response, cache_timeout: int | float) -> None:
     """
     Add HTTP caching headers to the given HttpResponse: Expires and
     Cache-Control.
@@ -38,7 +44,7 @@ def patch_response_headers(response, cache_timeout):
     patch_cache_control(response, max_age=cache_timeout)
 
 
-def add_never_cache_headers(response):
+def add_never_cache_headers(response: Response) -> None:
     """
     Add headers to a response to indicate that a page should never be cached.
     """
@@ -48,7 +54,7 @@ def add_never_cache_headers(response):
     )
 
 
-def patch_cache_control(response, **kwargs):
+def patch_cache_control(response: Response, **kwargs: Any) -> None:
     """
     Patch the Cache-Control header by adding all keyword arguments to it.
     The transformation is as follows:
@@ -61,16 +67,16 @@ def patch_cache_control(response, **kwargs):
       str() to it.
     """
 
-    def dictitem(s):
+    def dictitem(s: str) -> tuple[str, str | bool]:
         t = s.split("=", 1)
         if len(t) > 1:
             return (t[0].lower(), t[1])
         else:
             return (t[0].lower(), True)
 
-    def dictvalue(*t):
+    def dictvalue(*t: str | bool) -> str:
         if t[1] is True:
-            return t[0]
+            return str(t[0])
         else:
             return f"{t[0]}={t[1]}"
 
@@ -117,7 +123,7 @@ def patch_cache_control(response, **kwargs):
     response.headers["Cache-Control"] = cc
 
 
-def patch_vary_headers(response, newheaders):
+def patch_vary_headers(response: Response, newheaders: list[str]) -> None:
     """
     Add (or update) the "Vary" header in the given Response object.
     newheaders is a list of header names that should be in "Vary". If headers
@@ -145,7 +151,7 @@ def patch_vary_headers(response, newheaders):
         response.headers["Vary"] = ", ".join(vary_headers)
 
 
-def _to_tuple(s):
+def _to_tuple(s: str) -> tuple[str, str | bool]:
     t = s.split("=", 1)
     if len(t) == 2:
         return t[0].lower(), t[1]

plain/utils/crypto.py

@@ -2,9 +2,13 @@
 Plain's standard crypto functions and utilities.
 """
 
+from __future__ import annotations
+
 import hashlib
 import hmac
 import secrets
+from collections.abc import Callable
+from typing import Any
 
 from plain.runtime import settings
 from plain.utils.encoding import force_bytes
@@ -16,7 +20,13 @@ class InvalidAlgorithm(ValueError):
     pass
 
 
-def salted_hmac(key_salt, value, secret=None, *, algorithm="sha1"):
+def salted_hmac(
+    key_salt: str | bytes,
+    value: str | bytes,
+    secret: str | bytes | None = None,
+    *,
+    algorithm: str = "sha1",
+) -> hmac.HMAC:
     """
     Return the HMAC of 'value', using a key generated from key_salt and a
     secret (which defaults to settings.SECRET_KEY). Default algorithm is SHA1,
@@ -48,7 +58,7 @@ def salted_hmac(key_salt, value, secret=None, *, algorithm="sha1"):
 RANDOM_STRING_CHARS = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
 
-def get_random_string(length, allowed_chars=RANDOM_STRING_CHARS):
+def get_random_string(length: int, allowed_chars: str = RANDOM_STRING_CHARS) -> str:
     """
     Return a securely generated random string.
 
@@ -62,11 +72,17 @@ def get_random_string(length, allowed_chars=RANDOM_STRING_CHARS):
     return "".join(secrets.choice(allowed_chars) for i in range(length))
 
 
-def pbkdf2(password, salt, iterations, dklen=0, digest=None):
+def pbkdf2(
+    password: str | bytes,
+    salt: str | bytes,
+    iterations: int,
+    dklen: int = 0,
+    digest: Callable[[], Any] | None = None,
+) -> bytes:
     """Return the hash of password using pbkdf2."""
     if digest is None:
         digest = hashlib.sha256
-    dklen = dklen or None
+    dklen_value: int | None = dklen if dklen else None
     password = force_bytes(password)
     salt = force_bytes(salt)
-    return hashlib.pbkdf2_hmac(digest().name, password, salt, iterations, dklen)
+    return hashlib.pbkdf2_hmac(digest().name, password, salt, iterations, dklen_value)