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

plain/logs/utils.py

@@ -1,17 +1,24 @@
+from __future__ import annotations
+
 import logging
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from plain.http.request import HttpRequest
+    from plain.http.response import ResponseBase
 
 request_logger = logging.getLogger("plain.request")
 
 
 def log_response(
-    message,
-    *args,
-    response=None,
-    request=None,
-    logger=request_logger,
-    level=None,
-    exception=None,
-):
+    message: str,
+    *args: Any,
+    response: ResponseBase | None = None,
+    request: HttpRequest | None = None,
+    logger: logging.Logger = request_logger,
+    level: str | None = None,
+    exception: BaseException | None = None,
+) -> None:
     """
     Log errors based on Response status.
 
@@ -19,6 +26,9 @@ def log_response(
     is given as a keyword argument). The Response status_code and the
     request are passed to the logger's extra parameter.
     """
+    if response is None:
+        return
+
     # Check if the response has already been logged. Multiple requests to log
     # the same response can be received in some cases, e.g., when the
     # response is the result of an exception and is logged when the exception
@@ -43,4 +53,4 @@ def log_response(
         },
         exc_info=exception,
     )
-    response._has_been_logged = True
+    response._has_been_logged = True  # type: ignore[attr-defined]

plain/packages/config.py

@@ -1,9 +1,16 @@
+from __future__ import annotations
+
 import os
 from functools import cached_property
 from importlib import import_module
+from types import ModuleType
+from typing import TYPE_CHECKING
 
 from plain.exceptions import ImproperlyConfigured
 
+if TYPE_CHECKING:
+    from plain.packages.registry import PackagesRegistry
+
 CONFIG_MODULE_NAME = "config"
 
 
@@ -12,13 +19,13 @@ class PackageConfig:
 
     package_label: str
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         # Full Python path to the application e.g. 'plain.admin.admin'.
         self.name = name
 
         # Reference to the Packages registry that holds this PackageConfig. Set by the
         # registry when it registers the PackageConfig instance.
-        self.packages_registry = None
+        self.packages: PackagesRegistry | None = None
 
         if not hasattr(self, "package_label"):
             # Last component of the Python path to the application e.g. 'admin'.
@@ -30,14 +37,14 @@ class PackageConfig:
                 f"The app label '{self.package_label}' is not a valid Python identifier."
             )
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<{self.__class__.__name__}: {self.package_label}>"
 
     @cached_property
-    def path(self):
+    def path(self) -> str:
         # Filesystem path to the application directory e.g.
         # '/path/to/admin'.
-        def _path_from_module(module):
+        def _path_from_module(module: ModuleType) -> str:
             """Attempt to determine app's filesystem path from its module."""
             # See #21874 for extended discussion of the behavior of this method in
             # various cases.
@@ -68,7 +75,8 @@ class PackageConfig:
         module = import_module(self.name)
         return _path_from_module(module)
 
-    def ready(self):
+    def ready(self) -> None:
         """
         Override this method in subclasses to run code when Plain starts.
         """
+        return None

plain/packages/registry.py

@@ -1,13 +1,20 @@
+from __future__ import annotations
+
 import sys
 import threading
 from collections import Counter
+from collections.abc import Iterable
 from importlib import import_module
 from importlib.util import find_spec
+from typing import TYPE_CHECKING
 
 from plain.exceptions import ImproperlyConfigured, PackageRegistryNotReady
 
 from .config import PackageConfig
 
+if TYPE_CHECKING:
+    pass
+
 CONFIG_MODULE_NAME = "config"
 
 
@@ -18,7 +25,7 @@ class PackagesRegistry:
     It also keeps track of models, e.g. to provide reverse relations.
     """
 
-    def __init__(self, installed_packages=()):
+    def __init__(self, installed_packages: Iterable[str | PackageConfig] | None = ()):
         # installed_packages is set to None when creating the main registry
         # because it cannot be populated at that point. Other registries must
         # provide a list of installed packages and are populated immediately.
@@ -28,7 +35,7 @@ class PackagesRegistry:
             raise RuntimeError("You must supply an installed_packages argument.")
 
         # Mapping of labels to PackageConfig instances for installed packages.
-        self.package_configs = {}
+        self.package_configs: dict[str, PackageConfig] = {}
 
         # Whether the registry is populated.
         self.packages_ready = self.ready = False
@@ -41,7 +48,9 @@ class PackagesRegistry:
         if installed_packages is not None:
             self.populate(installed_packages)
 
-    def populate(self, installed_packages=None):
+    def populate(
+        self, installed_packages: Iterable[str | PackageConfig] | None = None
+    ) -> None:
         """
         Load application configurations and models.
 
@@ -67,6 +76,9 @@ class PackagesRegistry:
             self.loading = True
 
             # Phase 1: initialize app configs and import app modules.
+            if installed_packages is None:
+                return
+
             for entry in installed_packages:
                 if isinstance(entry, PackageConfig):
                     # Some instances of the registry pass in the
@@ -92,9 +104,10 @@ class PackagesRegistry:
                         entry_config = self.register_config(auto_package_config)
 
             # Make sure we have the same number of configs as we have installed packages
-            if len(self.package_configs) != len(installed_packages):
+            installed_packages_list = list(installed_packages)
+            if len(self.package_configs) != len(installed_packages_list):
                 raise ImproperlyConfigured(
-                    f"The number of installed packages ({len(installed_packages)}) does not match the number of "
+                    f"The number of installed packages ({len(installed_packages_list)}) does not match the number of "
                     f"registered configs ({len(self.package_configs)})."
                 )
 
@@ -118,7 +131,7 @@ class PackagesRegistry:
 
             self.ready = True
 
-    def check_packages_ready(self):
+    def check_packages_ready(self) -> None:
         """Raise an exception if all packages haven't been imported yet."""
         if not self.packages_ready:
             from plain.runtime import settings
@@ -129,12 +142,12 @@ class PackagesRegistry:
             settings.INSTALLED_PACKAGES
             raise PackageRegistryNotReady("Packages aren't loaded yet.")
 
-    def get_package_configs(self):
+    def get_package_configs(self) -> Iterable[PackageConfig]:
         """Import applications and return an iterable of app configs."""
         self.check_packages_ready()
         return self.package_configs.values()
 
-    def get_package_config(self, package_label):
+    def get_package_config(self, package_label: str) -> PackageConfig:
         """
         Import applications and returns an app config for the given label.
 
@@ -151,7 +164,7 @@ class PackagesRegistry:
                     break
             raise LookupError(message)
 
-    def get_containing_package_config(self, object_name):
+    def get_containing_package_config(self, object_name: str) -> PackageConfig | None:
         """
         Look for an app config containing a given object.
 
@@ -169,8 +182,9 @@ class PackagesRegistry:
                     candidates.append(package_config)
         if candidates:
             return sorted(candidates, key=lambda ac: -len(ac.name))[0]
+        return None
 
-    def register_config(self, package_config):
+    def register_config(self, package_config: PackageConfig) -> PackageConfig:
         """
         Add a config to the registry.
 
@@ -190,9 +204,10 @@ class PackagesRegistry:
         return package_config
 
     def autodiscover_modules(self, module_name: str, *, include_app: bool) -> None:
-        def _import_if_exists(name):
+        def _import_if_exists(name: str) -> None:
             if find_spec(name):
                 import_module(name)
+            return None
 
         # Load from all packages
         for package_config in self.get_package_configs():
@@ -206,7 +221,7 @@ class PackagesRegistry:
 packages_registry = PackagesRegistry(installed_packages=None)
 
 
-def register_config(package_config_class):
+def register_config(package_config_class: type[PackageConfig]) -> type[PackageConfig]:
     """A decorator to register a PackageConfig subclass."""
     module_name = package_config_class.__module__
 

plain/paginator.py

@@ -1,8 +1,12 @@
+from __future__ import annotations
+
 import collections.abc
 import inspect
 import warnings
+from collections.abc import Iterator
 from functools import cached_property
 from math import ceil
+from typing import Any
 
 from plain.utils.inspect import method_has_no_args
 
@@ -24,18 +28,24 @@ class EmptyPage(InvalidPage):
 
 
 class Paginator:
-    def __init__(self, object_list, per_page, orphans=0, allow_empty_first_page=True):
+    def __init__(
+        self,
+        object_list: Any,
+        per_page: int,
+        orphans: int = 0,
+        allow_empty_first_page: bool = True,
+    ) -> None:
         self.object_list = object_list
         self._check_object_list_is_ordered()
         self.per_page = int(per_page)
         self.orphans = int(orphans)
         self.allow_empty_first_page = allow_empty_first_page
 
-    def __iter__(self):
+    def __iter__(self) -> Iterator[Page]:
         for page_number in self.page_range:
             yield self.page(page_number)
 
-    def validate_number(self, number):
+    def validate_number(self, number: Any) -> int:
         """Validate the given 1-based page number."""
         try:
             if isinstance(number, float) and not number.is_integer():
@@ -49,7 +59,7 @@ class Paginator:
             raise EmptyPage("That page contains no results")
         return number
 
-    def get_page(self, number):
+    def get_page(self, number: Any) -> Page:
         """
         Return a valid page, even if the page argument isn't a number or isn't
         in range.
@@ -62,7 +72,7 @@ class Paginator:
             number = self.num_pages
         return self.page(number)
 
-    def page(self, number):
+    def page(self, number: Any) -> Page:
         """Return a Page object for the given 1-based page number."""
         number = self.validate_number(number)
         bottom = (number - 1) * self.per_page
@@ -71,7 +81,7 @@ class Paginator:
             top = self.count
         return self._get_page(self.object_list[bottom:top], number, self)
 
-    def _get_page(self, *args, **kwargs):
+    def _get_page(self, *args: Any, **kwargs: Any) -> Page:
         """
         Return an instance of a single page.
 
@@ -81,7 +91,7 @@ class Paginator:
         return Page(*args, **kwargs)
 
     @cached_property
-    def count(self):
+    def count(self) -> int:
         """Return the total number of objects, across all pages."""
         c = getattr(self.object_list, "count", None)
         if callable(c) and not inspect.isbuiltin(c) and method_has_no_args(c):
@@ -89,7 +99,7 @@ class Paginator:
         return len(self.object_list)
 
     @cached_property
-    def num_pages(self):
+    def num_pages(self) -> int:
         """Return the total number of pages."""
         if self.count == 0 and not self.allow_empty_first_page:
             return 0
@@ -97,14 +107,14 @@ class Paginator:
         return ceil(hits / self.per_page)
 
     @property
-    def page_range(self):
+    def page_range(self) -> range:
         """
         Return a 1-based range of pages for iterating through within
         a template for loop.
         """
         return range(1, self.num_pages + 1)
 
-    def _check_object_list_is_ordered(self):
+    def _check_object_list_is_ordered(self) -> None:
         """
         Warn if self.object_list is unordered (typically a QuerySet).
         """
@@ -124,18 +134,18 @@ class Paginator:
 
 
 class Page(collections.abc.Sequence):
-    def __init__(self, object_list, number, paginator):
+    def __init__(self, object_list: Any, number: int, paginator: Paginator) -> None:
         self.object_list = object_list
         self.number = number
         self.paginator = paginator
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return f"<Page {self.number} of {self.paginator.num_pages}>"
 
-    def __len__(self):
+    def __len__(self) -> int:
         return len(self.object_list)
 
-    def __getitem__(self, index):
+    def __getitem__(self, index: int | slice) -> Any:
         if not isinstance(index, int | slice):
             raise TypeError(
                 f"Page indices must be integers or slices, not {type(index).__name__}."
@@ -146,22 +156,22 @@ class Page(collections.abc.Sequence):
             self.object_list = list(self.object_list)
         return self.object_list[index]
 
-    def has_next(self):
+    def has_next(self) -> bool:
         return self.number < self.paginator.num_pages
 
-    def has_previous(self):
+    def has_previous(self) -> bool:
         return self.number > 1
 
-    def has_other_pages(self):
+    def has_other_pages(self) -> bool:
         return self.has_previous() or self.has_next()
 
-    def next_page_number(self):
+    def next_page_number(self) -> int:
         return self.paginator.validate_number(self.number + 1)
 
-    def previous_page_number(self):
+    def previous_page_number(self) -> int:
         return self.paginator.validate_number(self.number - 1)
 
-    def start_index(self):
+    def start_index(self) -> int:
         """
         Return the 1-based index of the first object on this page,
         relative to total objects in the paginator.
@@ -171,7 +181,7 @@ class Page(collections.abc.Sequence):
             return 0
         return (self.paginator.per_page * (self.number - 1)) + 1
 
-    def end_index(self):
+    def end_index(self) -> int:
         """
         Return the 1-based index of the last object on this page,
         relative to total objects found (hits).

plain/preflight/checks.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from abc import ABC, abstractmethod
 
 
@@ -5,6 +7,6 @@ class PreflightCheck(ABC):
     """Base class for all preflight checks."""
 
     @abstractmethod
-    def run(self):
+    def run(self) -> list:
         """Must return a list of Warning/Error results."""
         raise NotImplementedError

plain/preflight/files.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from pathlib import Path
 
 from plain.runtime import settings
@@ -11,7 +13,7 @@ from .results import PreflightResult
 class CheckSettingFileUploadTempDir(PreflightCheck):
     """Validates that the FILE_UPLOAD_TEMP_DIR setting points to an existing directory."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         setting = settings.FILE_UPLOAD_TEMP_DIR
         if setting and not Path(setting).is_dir():
             return [

plain/preflight/registry.py

@@ -1,11 +1,24 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from typing import Any, TypeVar
+
 from plain.runtime import settings
 
+from .results import PreflightResult
 
-class CheckRegistry:
-    def __init__(self):
-        self.checks = {}  # name -> (check_class, deploy)
+T = TypeVar("T")
 
-    def register_check(self, check_class, name, deploy=False):
+
+class CheckRegistry:
+    def __init__(self) -> None:
+        self.checks: dict[
+            str, tuple[type[Any], bool]
+        ] = {}  # name -> (check_class, deploy)
+
+    def register_check(
+        self, check_class: type[Any], name: str, deploy: bool = False
+    ) -> None:
         """Register a check class with a unique name."""
         if name in self.checks:
             raise ValueError(f"Check {name} already registered")
@@ -13,8 +26,8 @@ class CheckRegistry:
 
     def run_checks(
         self,
-        include_deploy_checks=False,
-    ):
+        include_deploy_checks: bool = False,
+    ) -> Generator[tuple[type[Any], str, list[PreflightResult]]]:
         """
         Run all registered checks and yield (check_class, name, results) tuples.
         """
@@ -42,9 +55,11 @@ class CheckRegistry:
             results = check.run()
             yield check_class, name, results
 
-    def get_checks(self, include_deploy_checks=False):
+    def get_checks(
+        self, include_deploy_checks: bool = False
+    ) -> list[tuple[type[Any], str]]:
         """Get list of (check_class, name) tuples."""
-        result = []
+        result: list[tuple[type[Any], str]] = []
         for name, (check_class, deploy) in self.checks.items():
             if deploy and not include_deploy_checks:
                 continue
@@ -55,7 +70,7 @@ class CheckRegistry:
 checks_registry = CheckRegistry()
 
 
-def register_check(name: str, *, deploy: bool = False):
+def register_check(name: str, *, deploy: bool = False) -> Callable[[type[T]], type[T]]:
     """
     Decorator to register a check class.
 
@@ -69,7 +84,7 @@ def register_check(name: str, *, deploy: bool = False):
             pass
     """
 
-    def wrapper(cls):
+    def wrapper(cls: type[T]) -> type[T]:
         checks_registry.register_check(cls, name=name, deploy=deploy)
         return cls
 

plain/preflight/results.py

@@ -1,20 +1,26 @@
+from __future__ import annotations
+
+from typing import Any
+
 from plain.runtime import settings
 
 
 class PreflightResult:
-    def __init__(self, *, fix: str, id: str, obj=None, warning: bool = False):
+    def __init__(
+        self, *, fix: str, id: str, obj: Any = None, warning: bool = False
+    ) -> None:
         self.fix = fix
         self.obj = obj
         self.id = id
         self.warning = warning
 
-    def __eq__(self, other):
+    def __eq__(self, other: object) -> bool:
         return isinstance(other, self.__class__) and all(
             getattr(self, attr) == getattr(other, attr)
             for attr in ["fix", "obj", "id", "warning"]
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.obj is None:
             obj = ""
         elif hasattr(self.obj, "_meta") and hasattr(self.obj._meta, "label"):
@@ -25,5 +31,5 @@ class PreflightResult:
         id_part = f"({self.id}) " if self.id else ""
         return f"{obj}: {id_part}{self.fix}"
 
-    def is_silenced(self):
+    def is_silenced(self) -> bool:
         return self.id and self.id in settings.PREFLIGHT_SILENCED_RESULTS

plain/preflight/security.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 from plain.runtime import settings
 
 from .checks import PreflightCheck
@@ -8,7 +10,7 @@ SECRET_KEY_MIN_LENGTH = 50
 SECRET_KEY_MIN_UNIQUE_CHARACTERS = 5
 
 
-def _check_secret_key(secret_key):
+def _check_secret_key(secret_key: str) -> bool:
     return (
         len(set(secret_key)) >= SECRET_KEY_MIN_UNIQUE_CHARACTERS
         and len(secret_key) >= SECRET_KEY_MIN_LENGTH
@@ -19,7 +21,7 @@ def _check_secret_key(secret_key):
 class CheckSecretKey(PreflightCheck):
     """Validates that SECRET_KEY is long and random enough for security."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         if not _check_secret_key(settings.SECRET_KEY):
             return [
                 PreflightResult(
@@ -36,7 +38,7 @@ class CheckSecretKey(PreflightCheck):
 class CheckSecretKeyFallbacks(PreflightCheck):
     """Validates that SECRET_KEY_FALLBACKS are long and random enough for security."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         errors = []
         for index, key in enumerate(settings.SECRET_KEY_FALLBACKS):
             if not _check_secret_key(key):
@@ -55,7 +57,7 @@ class CheckSecretKeyFallbacks(PreflightCheck):
 class CheckDebug(PreflightCheck):
     """Ensures DEBUG is False in production deployment."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         if settings.DEBUG:
             return [
                 PreflightResult(
@@ -70,7 +72,7 @@ class CheckDebug(PreflightCheck):
 class CheckAllowedHosts(PreflightCheck):
     """Ensures ALLOWED_HOSTS is not empty in production deployment."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         if not settings.ALLOWED_HOSTS:
             return [
                 PreflightResult(

plain/preflight/urls.py

@@ -1,12 +1,15 @@
+from __future__ import annotations
+
 from .checks import PreflightCheck
 from .registry import register_check
+from .results import PreflightResult
 
 
 @register_check("urls.config")
 class CheckUrlConfig(PreflightCheck):
     """Validates the URL configuration for common issues."""
 
-    def run(self):
+    def run(self) -> list[PreflightResult]:
         from plain.urls import get_resolver
 
         resolver = get_resolver()

plain/runtime/__init__.py

@@ -2,6 +2,7 @@ import importlib.metadata
 import sys
 from importlib.metadata import entry_points
 from pathlib import Path
+from typing import Self
 
 from plain.logs.configure import configure_logging
 from plain.packages import packages_registry
@@ -32,7 +33,7 @@ class SetupError(RuntimeError):
     pass
 
 
-def setup():
+def setup() -> None:
     """
     Configure the settings (this happens as a side effect of accessing the
     first setting), configure logging and populate the app registry.
@@ -77,11 +78,11 @@ class SettingsReference(str):
     the value in memory but serializes to a settings.NAME attribute reference.
     """
 
-    def __new__(self, setting_name):
+    def __new__(self, setting_name: str) -> Self:
         value = getattr(settings, setting_name)
         return str.__new__(self, value)
 
-    def __init__(self, setting_name):
+    def __init__(self, setting_name: str):
         self.setting_name = setting_name
 
 

plain/runtime/global_settings.py

@@ -114,7 +114,7 @@ DATA_UPLOAD_MAX_NUMBER_FILES = 100
 FILE_UPLOAD_TEMP_DIR = None
 
 # User-defined overrides for error views by status code
-HTTP_ERROR_VIEWS: dict[int] = {}
+HTTP_ERROR_VIEWS: dict[int, type] = {}
 
 # MARK: Middleware