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

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,9 +39,9 @@ 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)
-            if self._ref_count == 0:
+            if self._ref_count == 0 and self.original_level is not None:
                 self.logger.setLevel(self.original_level)

plain/logs/filters.py

@@ -0,0 +1,15 @@
+import logging
+
+
+class DebugInfoFilter(logging.Filter):
+    """Filter that only allows DEBUG and INFO log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno <= logging.INFO
+
+
+class WarningErrorCriticalFilter(logging.Filter):
+    """Filter that only allows WARNING, ERROR, and CRITICAL log records."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        return record.levelno >= logging.WARNING

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),
@@ -57,7 +60,7 @@ class JSONFormatter(logging.Formatter):
 
         # Add Plain's context data to the main JSON object
         if hasattr(record, "context") and isinstance(record.context, dict):
-            log_obj.update(record.context)
+            log_obj.update(record.context)  # type: ignore[arg-type]
 
         # Handle exceptions
         if record.exc_info:

plain/packages/README.md

@@ -1,17 +1,19 @@
 # Packages
 
-**Install Python modules as Plain packages.**
+**Register and configure Python modules as Plain packages.**
 
 - [Overview](#overview)
 - [Creating app packages](#creating-app-packages)
 - [Package settings](#package-settings)
-- [Package `ready()` method](#package-ready-method)
+- [Package configuration](#package-configuration)
+    - [The `ready()` method](#the-ready-method)
+    - [Custom package labels](#custom-package-labels)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-Most Python modules that you use with Plain will need to be installed via `settings.INSTALLED_PACKAGES`. This is what enables template detection, per-package settings, database models, and other features.
-
-A package can either be a local module inside of your `app`, or a third-party package from PyPI.
+Most Python modules you use with Plain need to be listed in `settings.INSTALLED_PACKAGES`. This enables template detection, per-package settings, database models, and other features.
 
 ```python
 # app/settings.py
@@ -26,57 +28,137 @@ INSTALLED_PACKAGES = [
     "plain.elements",
     # Local packages
     "app.users",
+    "app.teams",
 ]
 ```
 
+A package can be a third-party module from PyPI or a local module inside your `app` directory.
+
 ## Creating app packages
 
-It often makes sense to conceptually split your app across multiple local packages. For example, we find it typically works better to have separate `users`, `teams`, and `projects` packages, than a single `core` package that contains all the code for users, teams, and projects together (just as an example). If you find yourself creating a package with a generic name like `core` or `base`, you might want to consider splitting it up into smaller packages.
+You can split your app into multiple local packages. For example, instead of a single `core` package containing everything, you might have separate `users`, `teams`, and `projects` packages. If you find yourself creating a package with a generic name like `core` or `base`, consider splitting it up.
+
+Create a new package by running:
 
-You can quickly create a new package by running `plain create <package_name>`. Make sure to add it to `settings.INSTALLED_PACKAGES` if it uses templates, models, or other Plain-specific features.
+```bash
+plain create <package_name>
+```
+
+Make sure to add it to `settings.INSTALLED_PACKAGES` if it uses templates, models, or other Plain-specific features.
 
 ## Package settings
 
-An installed package can optionally define it's own settings. These could be default settings for how the package behaves, or required settings that must be configured by the developer.
+An installed package can define its own settings. These could be default values for how the package behaves, or required settings that must be configured by the user.
+
+Create a `default_settings.py` file in your package:
 
 ```python
-# <pkg>/default_settings.py
-# A default setting
-EXAMPLE_SETTING: str = "example"
+# teams/default_settings.py
+
+# A default setting (has a value)
+TEAMS_MAX_MEMBERS: int = 10
 
 # A required setting (type annotation with no default value)
-REQUIRED_SETTING: str
+TEAMS_SIGNUP_ENABLED: bool
 ```
 
-Settings can then be accessed at runtime through the `settings` object.
+Access settings at runtime through the `settings` object:
 
 ```python
-# <pkg>/models.py
+# teams/views.py
 from plain.runtime import settings
 
 
-def example_function():
-    print(settings.EXAMPLE_SETTING)
+def team_view(request):
+    if settings.TEAMS_SIGNUP_ENABLED:
+        max_members = settings.TEAMS_MAX_MEMBERS
+        # ...
 ```
 
-It is strongly recommended to "namespace" your settings to your package. So if your package is named "teams", you might want to prefix all your settings with `TEAMS_`.
+Namespace your settings to avoid conflicts. If your package is named `teams`, prefix all settings with `TEAMS_`.
+
+## Package configuration
+
+To customize how your package loads or run setup code when Plain starts, create a [`PackageConfig`](./config.py#PackageConfig) subclass in a `config.py` file:
 
 ```python
-# teams/default_settings.py
-TEAMS_EXAMPLE_SETTING: str = "example"
+# teams/config.py
+from plain.packages import PackageConfig, register_config
+
+
+@register_config
+class TeamsConfig(PackageConfig):
+    pass
 ```
 
-## Package `ready()` method
+The [`@register_config`](./registry.py#register_config) decorator registers your configuration with the [`packages_registry`](./registry.py#packages_registry).
+
+### The `ready()` method
 
-To run setup code when your package is loaded, you can define a package configuration and the `ready()` method.
+Override the `ready()` method to run code when Plain starts. This is useful for connecting signals, initializing caches, or other one-time setup.
 
 ```python
-# <pkg>/config.py
+# teams/config.py
 from plain.packages import PackageConfig, register_config
 
 
 @register_config
 class TeamsConfig(PackageConfig):
     def ready(self):
-        print("Teams package is ready!")
+        # Import signal handlers
+        from . import signals  # noqa: F401
+        print("Teams package ready!")
+```
+
+### Custom package labels
+
+By default, the package label is the last component of the Python path (e.g., `admin` for `plain.admin`). You can override this by setting the `package_label` attribute:
+
+```python
+# teams/config.py
+from plain.packages import PackageConfig, register_config
+
+
+@register_config
+class TeamsConfig(PackageConfig):
+    package_label = "teams"
+```
+
+## FAQs
+
+#### When do I need a `config.py` file?
+
+You only need a `config.py` file if you want to run code in `ready()` or customize the package label. For most packages, Plain automatically creates a default configuration.
+
+#### How do I access the package registry?
+
+You can access the registry directly if you need to inspect installed packages:
+
+```python
+from plain.packages import packages_registry
+
+# Get all registered package configs
+for config in packages_registry.get_package_configs():
+    print(config.name, config.path)
+
+# Get a specific package config by label
+teams_config = packages_registry.get_package_config("teams")
+```
+
+See [`PackagesRegistry`](./registry.py#PackagesRegistry) for all available methods.
+
+#### What order are packages loaded?
+
+Packages are loaded in the order they appear in `INSTALLED_PACKAGES`. The `ready()` methods are called in the same order after all packages have been imported.
+
+#### Can I have duplicate package labels?
+
+No. Each package must have a unique label. If two packages have the same label, Plain raises an `ImproperlyConfigured` error.
+
+## Installation
+
+The `plain.packages` module is included with the `plain` package. No additional installation is required.
+
+```bash
+uv add plain
 ```

plain/packages/config.py

@@ -1,10 +1,17 @@
+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
 
-CONFIG_MODULE_NAME = "config"
+if TYPE_CHECKING:
+    from plain.packages.registry import PackagesRegistry
+
+_CONFIG_MODULE_NAME = "config"
 
 
 class PackageConfig:
@@ -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,6 +1,9 @@
+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
 
@@ -8,7 +11,7 @@ from plain.exceptions import ImproperlyConfigured, PackageRegistryNotReady
 
 from .config import PackageConfig
 
-CONFIG_MODULE_NAME = "config"
+_CONFIG_MODULE_NAME = "config"
 
 
 class PackagesRegistry:
@@ -18,7 +21,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 +31,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 +44,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 +72,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
@@ -74,7 +82,7 @@ class PackagesRegistry:
                     self.register_config(package_config=entry)
                 else:
                     try:
-                        import_module(f"{entry}.{CONFIG_MODULE_NAME}")
+                        import_module(f"{entry}.{_CONFIG_MODULE_NAME}")
                     except ModuleNotFoundError:
                         pass
 
@@ -92,9 +100,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 +127,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 +138,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 +160,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 +178,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 +200,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,13 +217,13 @@ 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__
 
     # If it is in .config like expected, return the parent module name
-    if module_name.endswith(f".{CONFIG_MODULE_NAME}"):
-        module_name = module_name[: -len(CONFIG_MODULE_NAME) - 1]
+    if module_name.endswith(f".{_CONFIG_MODULE_NAME}"):
+        module_name = module_name[: -len(_CONFIG_MODULE_NAME) - 1]
 
     package_config = package_config_class(module_name)
 

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).