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

plain/runtime/user_settings.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import importlib
 import json
 import os
@@ -26,13 +28,13 @@ class Settings:
     Lazy initialization is implemented to defer loading until settings are first accessed.
     """
 
-    def __init__(self, settings_module=None):
+    def __init__(self, settings_module: str | None = None):
         self._settings_module = settings_module
         self._settings = {}
         self._errors = []  # Collect configuration errors
         self.configured = False
 
-    def _setup(self):
+    def _setup(self) -> None:
         if self.configured:
             return
         else:
@@ -71,7 +73,7 @@ class Settings:
         # Check for any collected errors
         self._raise_errors_if_any()
 
-    def _load_module_settings(self, module):
+    def _load_module_settings(self, module: types.ModuleType) -> None:
         annotations = getattr(module, "__annotations__", {})
         settings = dir(module)
 
@@ -100,7 +102,7 @@ class Settings:
                     required=True,
                 )
 
-    def _load_default_settings(self, settings_module):
+    def _load_default_settings(self, settings_module: types.ModuleType) -> None:
         for entry in getattr(settings_module, "INSTALLED_PACKAGES", []):
             if isinstance(entry, PackageConfig):
                 app_settings = entry.module.default_settings
@@ -111,7 +113,7 @@ class Settings:
 
             self._load_module_settings(app_settings)
 
-    def _load_env_settings(self):
+    def _load_env_settings(self) -> None:
         env_settings = {
             k[len(ENV_SETTINGS_PREFIX) :]: v
             for k, v in os.environ.items()
@@ -128,7 +130,7 @@ class Settings:
                 except ImproperlyConfigured as e:
                     self._errors.append(str(e))
 
-    def _load_explicit_settings(self, settings_module):
+    def _load_explicit_settings(self, settings_module: types.ModuleType) -> None:
         for setting in dir(settings_module):
             if setting.isupper():
                 setting_value = getattr(settings_module, setting)
@@ -172,19 +174,19 @@ class Settings:
                 os.environ["TZ"] = self.TIME_ZONE
                 time.tzset()
 
-    def _check_required_settings(self):
+    def _check_required_settings(self) -> None:
         missing = [k for k, v in self._settings.items() if v.required and not v.is_set]
         if missing:
             self._errors.append(f"Missing required setting(s): {', '.join(missing)}.")
 
-    def _raise_errors_if_any(self):
+    def _raise_errors_if_any(self) -> None:
         if self._errors:
             errors = ["- " + e for e in self._errors]
             raise ImproperlyConfigured(
                 "Settings configuration errors:\n" + "\n".join(errors)
             )
 
-    def __getattr__(self, name):
+    def __getattr__(self, name: str) -> typing.Any:
         # Avoid recursion by directly returning internal attributes
         if not name.isupper():
             return object.__getattribute__(self, name)
@@ -196,7 +198,7 @@ class Settings:
         else:
             raise AttributeError(f"'Settings' object has no attribute '{name}'")
 
-    def __setattr__(self, name, value):
+    def __setattr__(self, name: str, value: typing.Any) -> None:
         # Handle internal attributes without recursion
         if not name.isupper():
             object.__setattr__(self, name, value)
@@ -207,13 +209,15 @@ class Settings:
             else:
                 object.__setattr__(self, name, value)
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         if not self.configured:
             return "<Settings [Unevaluated]>"
         return f'<Settings "{self._settings_module}">'
 
 
-def _parse_env_value(value, annotation, setting_name):
+def _parse_env_value(
+    value: str, annotation: type | None, setting_name: str
+) -> typing.Any:
     if not annotation:
         raise ImproperlyConfigured(
             f"{setting_name}: Type hint required to set from environment."
@@ -238,7 +242,12 @@ class SettingDefinition:
     """Store detailed information about settings."""
 
     def __init__(
-        self, name, default_value=None, annotation=None, module=None, required=False
+        self,
+        name: str,
+        default_value: typing.Any = None,
+        annotation: type | None = None,
+        module: types.ModuleType | None = None,
+        required: bool = False,
     ):
         self.name = name
         self.default_value = default_value
@@ -249,13 +258,13 @@ class SettingDefinition:
         self.source = "default"  # 'default', 'env', 'explicit', or 'runtime'
         self.is_set = False  # Indicates if the value was set explicitly
 
-    def set_value(self, value, source):
+    def set_value(self, value: typing.Any, source: str) -> None:
         self.check_type(value)
         self.value = value
         self.source = source
         self.is_set = True
 
-    def check_type(self, obj):
+    def check_type(self, obj: typing.Any) -> None:
         if not self.annotation:
             return
 
@@ -265,7 +274,7 @@ class SettingDefinition:
             )
 
     @staticmethod
-    def _is_instance_of_type(value, type_hint) -> bool:
+    def _is_instance_of_type(value: typing.Any, type_hint: typing.Any) -> bool:
         # Simple types
         if isinstance(type_hint, type):
             return isinstance(value, type_hint)
@@ -300,5 +309,5 @@ class SettingDefinition:
 
         raise ValueError(f"Unsupported type hint: {type_hint}")
 
-    def __str__(self):
+    def __str__(self) -> str:
         return f"SettingDefinition(name={self.name}, value={self.value}, source={self.source})"

plain/runtime/utils.py

@@ -2,7 +2,7 @@ import tomllib
 from pathlib import Path
 
 
-def get_app_info_from_pyproject():
+def get_app_info_from_pyproject() -> tuple[str, str]:
     """Get the project name and version from the nearest pyproject.toml file."""
     current_path = Path.cwd()
 

plain/signals/dispatch/dispatcher.py

@@ -1,13 +1,20 @@
+from __future__ import annotations
+
 import logging
 import threading
 import weakref
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
 
 from plain.utils.inspect import func_accepts_kwargs
 
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
 logger = logging.getLogger("plain.signals.dispatch")
 
 
-def _make_id(target):
+def _make_id(target: Any) -> int | tuple[int, int]:
     if hasattr(target, "__func__"):
         return (id(target.__self__), id(target.__func__))
     return id(target)
@@ -29,7 +36,7 @@ class Signal:
             { receiverkey (id) : weakref(receiver) }
     """
 
-    def __init__(self, use_caching=False):
+    def __init__(self, use_caching: bool = False):
         """
         Create a new signal.
         """
@@ -44,7 +51,13 @@ class Signal:
         self.sender_receivers_cache = weakref.WeakKeyDictionary() if use_caching else {}
         self._dead_receivers = False
 
-    def connect(self, receiver, sender=None, weak=True, dispatch_uid=None):
+    def connect(
+        self,
+        receiver: Callable[..., Any],
+        sender: Any = None,
+        weak: bool = True,
+        dispatch_uid: Any = None,
+    ) -> None:
         """
         Connect receiver to sender for signal.
 
@@ -111,7 +124,12 @@ class Signal:
                 self.receivers.append((lookup_key, receiver))
             self.sender_receivers_cache.clear()
 
-    def disconnect(self, receiver=None, sender=None, dispatch_uid=None):
+    def disconnect(
+        self,
+        receiver: Callable[..., Any] | None = None,
+        sender: Any = None,
+        dispatch_uid: Any = None,
+    ) -> bool:
         """
         Disconnect receiver from sender for signal.
 
@@ -147,11 +165,11 @@ class Signal:
             self.sender_receivers_cache.clear()
         return disconnected
 
-    def has_listeners(self, sender=None):
+    def has_listeners(self, sender: Any = None) -> bool:
         sync_receivers = self._live_receivers(sender)
         return bool(sync_receivers)
 
-    def send(self, sender, **named):
+    def send(self, sender: Any, **named: Any) -> list[tuple[Callable[..., Any], Any]]:
         """
         Send signal from sender to all connected receivers.
 
@@ -185,15 +203,17 @@ class Signal:
             responses.append((receiver, response))
         return responses
 
-    def _log_robust_failure(self, receiver, err):
+    def _log_robust_failure(self, receiver: Callable[..., Any], err: Exception) -> None:
         logger.error(
             "Error calling %s in Signal.send_robust() (%s)",
-            receiver.__qualname__,
+            getattr(receiver, "__qualname__", repr(receiver)),
             err,
             exc_info=err,
         )
 
-    def send_robust(self, sender, **named):
+    def send_robust(
+        self, sender: Any, **named: Any
+    ) -> list[tuple[Callable[..., Any], Any]]:
         """
         Send signal from sender to all connected receivers catching errors.
 
@@ -236,7 +256,7 @@ class Signal:
                 responses.append((receiver, response))
         return responses
 
-    def _clear_dead_receivers(self):
+    def _clear_dead_receivers(self) -> None:
         # Note: caller is assumed to hold self.lock.
         if self._dead_receivers:
             self._dead_receivers = False
@@ -246,7 +266,7 @@ class Signal:
                 if not (isinstance(r[1], weakref.ReferenceType) and r[1]() is None)
             ]
 
-    def _live_receivers(self, sender):
+    def _live_receivers(self, sender: Any) -> list[Callable[..., Any]]:
         """
         Filter sequence of receivers to get resolved, live receivers.
 
@@ -285,7 +305,7 @@ class Signal:
                 non_weak_sync_receivers.append(receiver)
         return non_weak_sync_receivers
 
-    def _remove_receiver(self, receiver=None):
+    def _remove_receiver(self, receiver: Any = None) -> None:
         # Mark that the self.receivers list has dead weakrefs. If so, we will
         # clean those up in connect, disconnect and _live_receivers while
         # holding self.lock. Note that doing the cleanup here isn't a good
@@ -295,7 +315,9 @@ class Signal:
         self._dead_receivers = True
 
 
-def receiver(signal, **kwargs):
+def receiver(
+    signal: Signal | Sequence[Signal], **kwargs: Any
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """
     A decorator for connecting receivers to signals. Used by passing in the
     signal (or list of signals) and keyword arguments to connect::
@@ -309,12 +331,12 @@ def receiver(signal, **kwargs):
             ...
     """
 
-    def _decorator(func):
-        if isinstance(signal, list | tuple):
+    def _decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        if isinstance(signal, Signal):
+            signal.connect(func, **kwargs)
+        else:
             for s in signal:
                 s.connect(func, **kwargs)
-        else:
-            signal.connect(func, **kwargs)
         return func
 
     return _decorator

plain/signing.py

@@ -33,12 +33,15 @@ There are 65 url-safe characters: the 64 used by url-safe base64 and the ':'.
 These functions make use of all of them.
 """
 
+from __future__ import annotations
+
 import base64
 import datetime
 import hmac
 import json
 import time
 import zlib
+from typing import Any
 
 from plain.runtime import settings
 from plain.utils.crypto import salted_hmac
@@ -61,7 +64,7 @@ class SignatureExpired(BadSignature):
     pass
 
 
-def b62_encode(s):
+def b62_encode(s: int) -> str:
     if s == 0:
         return "0"
     sign = "-" if s < 0 else ""
@@ -73,7 +76,7 @@ def b62_encode(s):
     return sign + encoded
 
 
-def b62_decode(s):
+def b62_decode(s: str) -> int:
     if s == "0":
         return 0
     sign = 1
@@ -86,16 +89,16 @@ def b62_decode(s):
     return sign * decoded
 
 
-def b64_encode(s):
+def b64_encode(s: bytes) -> bytes:
     return base64.urlsafe_b64encode(s).strip(b"=")
 
 
-def b64_decode(s):
+def b64_decode(s: bytes) -> bytes:
     pad = b"=" * (-len(s) % 4)
     return base64.urlsafe_b64decode(s + pad)
 
 
-def base64_hmac(salt, value, key, algorithm="sha1"):
+def base64_hmac(salt: str, value: str, key: str, algorithm: str = "sha1") -> str:
     return b64_encode(
         salted_hmac(salt, value, key, algorithm=algorithm).digest()
     ).decode()
@@ -107,16 +110,20 @@ class JSONSerializer:
     signing.loads.
     """
 
-    def dumps(self, obj):
+    def dumps(self, obj: Any) -> bytes:
         return json.dumps(obj, separators=(",", ":")).encode("latin-1")
 
-    def loads(self, data):
+    def loads(self, data: bytes) -> Any:
         return json.loads(data.decode("latin-1"))
 
 
 def dumps(
-    obj, key=None, salt="plain.signing", serializer=JSONSerializer, compress=False
-):
+    obj: Any,
+    key: str | None = None,
+    salt: str = "plain.signing",
+    serializer: type[JSONSerializer] = JSONSerializer,
+    compress: bool = False,
+) -> str:
     """
     Return URL-safe, hmac signed base64 compressed JSON string. If key is
     None, use settings.SECRET_KEY instead. The hmac algorithm is the default
@@ -139,13 +146,13 @@ def dumps(
 
 
 def loads(
-    s,
-    key=None,
-    salt="plain.signing",
-    serializer=JSONSerializer,
-    max_age=None,
-    fallback_keys=None,
-):
+    s: str,
+    key: str | None = None,
+    salt: str = "plain.signing",
+    serializer: type[JSONSerializer] = JSONSerializer,
+    max_age: int | float | datetime.timedelta | None = None,
+    fallback_keys: list[str] | None = None,
+) -> Any:
     """
     Reverse of dumps(), raise BadSignature if signature fails.
 
@@ -164,12 +171,12 @@ class Signer:
     def __init__(
         self,
         *,
-        key=None,
-        sep=":",
-        salt=None,
-        algorithm="sha256",
-        fallback_keys=None,
-    ):
+        key: str | None = None,
+        sep: str = ":",
+        salt: str | None = None,
+        algorithm: str = "sha256",
+        fallback_keys: list[str] | None = None,
+    ) -> None:
         self.key = key or settings.SECRET_KEY
         self.fallback_keys = (
             fallback_keys
@@ -186,14 +193,14 @@ class Signer:
                 "only A-z0-9-_=)",
             )
 
-    def signature(self, value, key=None):
+    def signature(self, value: str, key: str | None = None) -> str:
         key = key or self.key
         return base64_hmac(self.salt + "signer", value, key, algorithm=self.algorithm)
 
-    def sign(self, value):
+    def sign(self, value: str) -> str:
         return f"{value}{self.sep}{self.signature(value)}"
 
-    def unsign(self, signed_value):
+    def unsign(self, signed_value: str) -> str:
         if self.sep not in signed_value:
             raise BadSignature(f'No "{self.sep}" found in value')
         value, sig = signed_value.rsplit(self.sep, 1)
@@ -204,7 +211,12 @@ class Signer:
                 return value
         raise BadSignature(f'Signature "{sig}" does not match')
 
-    def sign_object(self, obj, serializer=JSONSerializer, compress=False):
+    def sign_object(
+        self,
+        obj: Any,
+        serializer: type[JSONSerializer] = JSONSerializer,
+        compress: bool = False,
+    ) -> str:
         """
         Return URL-safe, hmac signed base64 compressed JSON string.
 
@@ -229,7 +241,12 @@ class Signer:
             base64d = "." + base64d
         return self.sign(base64d)
 
-    def unsign_object(self, signed_obj, serializer=JSONSerializer, **kwargs):
+    def unsign_object(
+        self,
+        signed_obj: str,
+        serializer: type[JSONSerializer] = JSONSerializer,
+        **kwargs: Any,
+    ) -> Any:
         # Signer.unsign() returns str but base64 and zlib compression operate
         # on bytes.
         base64d = self.unsign(signed_obj, **kwargs).encode()
@@ -244,14 +261,16 @@ class Signer:
 
 
 class TimestampSigner(Signer):
-    def timestamp(self):
+    def timestamp(self) -> str:
         return b62_encode(int(time.time()))
 
-    def sign(self, value):
+    def sign(self, value: str) -> str:
         value = f"{value}{self.sep}{self.timestamp()}"
         return super().sign(value)
 
-    def unsign(self, value, max_age=None):
+    def unsign(
+        self, value: str, max_age: int | float | datetime.timedelta | None = None
+    ) -> str:
         """
         Retrieve original value and check it wasn't signed more
         than max_age seconds ago.

plain/templates/jinja/__init__.py

@@ -1,3 +1,8 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
 from plain.packages import packages_registry
 from plain.runtime import settings
 from plain.utils.functional import LazyObject
@@ -7,7 +12,7 @@ from .environments import DefaultEnvironment, get_template_dirs
 
 
 class JinjaEnvironment(LazyObject):
-    def _setup(self):
+    def _setup(self) -> None:
         environment_setting = settings.TEMPLATES_JINJA_ENVIRONMENT
 
         if isinstance(environment_setting, str):
@@ -25,12 +30,12 @@ class JinjaEnvironment(LazyObject):
 environment = JinjaEnvironment()
 
 
-def register_template_extension(extension_class):
+def register_template_extension(extension_class: type) -> type:
     environment.add_extension(extension_class)
     return extension_class
 
 
-def register_template_global(value, name=None):
+def register_template_global(value: Any, name: str | None = None) -> Any:
     """
     Adds a global to the Jinja environment.
 
@@ -54,9 +59,12 @@ def register_template_global(value, name=None):
     return value
 
 
-def register_template_filter(func, name=None):
+def register_template_filter(
+    func: Callable[..., Any], name: str | None = None
+) -> Callable[..., Any]:
     """Adds a filter to the Jinja environment."""
-    environment.filters[name or func.__name__] = func
+    filter_name = name if name is not None else func.__name__  # type: ignore[attr-defined]
+    environment.filters[filter_name] = func
     return func
 
 

plain/templates/jinja/environments.py

@@ -1,5 +1,6 @@
 import functools
 from pathlib import Path
+from typing import Any
 
 from jinja2 import Environment, StrictUndefined
 from jinja2.loaders import FileSystemLoader
@@ -11,7 +12,7 @@ from .filters import default_filters
 from .globals import default_globals
 
 
-def finalize_callable_error(obj):
+def finalize_callable_error(obj: Any) -> Any:
     """Prevent direct rendering of a callable (likely just forgotten ()) by raising a TypeError"""
     if callable(obj):
         raise TypeError(f"{obj} is callable, did you forget parentheses?")
@@ -23,14 +24,14 @@ def finalize_callable_error(obj):
     return obj
 
 
-def get_template_dirs():
+def get_template_dirs() -> tuple[Path, ...]:
     jinja_templates = Path(__file__).parent / "templates"
     app_templates = settings.path.parent / "templates"
     return (jinja_templates, app_templates) + _get_app_template_dirs()
 
 
 @functools.lru_cache
-def _get_app_template_dirs():
+def _get_app_template_dirs() -> tuple[Path, ...]:
     """
     Return an iterable of paths of directories to load app templates from.
 

plain/templates/jinja/extensions.py

@@ -1,3 +1,7 @@
+from __future__ import annotations
+
+from typing import Any
+
 from jinja2 import nodes
 from jinja2.ext import Extension
 
@@ -9,7 +13,7 @@ class InclusionTagExtension(Extension):
     tags: set[str]
     template_name: str
 
-    def parse(self, parser):
+    def parse(self, parser: Any) -> nodes.Node:
         lineno = next(parser.stream).lineno
         args = [
             nodes.DerivedContextReference(),
@@ -28,12 +32,14 @@ class InclusionTagExtension(Extension):
         call = self.call_method("_render", args=args, kwargs=kwargs, lineno=lineno)
         return nodes.CallBlock(call, [], [], []).set_lineno(lineno)
 
-    def _render(self, context, *args, **kwargs):
+    def _render(self, context: dict[str, Any], *args: Any, **kwargs: Any) -> str:
         context = self.get_context(context, *args, **kwargs)
         template = self.environment.get_template(self.template_name)
         return template.render(context)
 
-    def get_context(self, context, *args, **kwargs):
+    def get_context(
+        self, context: dict[str, Any], *args: Any, **kwargs: Any
+    ) -> dict[str, Any]:
         raise NotImplementedError(
             "You need to implement the `get_context` method in your subclass."
         )

plain/templates/jinja/filters.py

@@ -1,12 +1,17 @@
+from __future__ import annotations
+
 import datetime
 from itertools import islice
+from typing import Any
 
 from plain.utils.html import json_script
 from plain.utils.timesince import timesince, timeuntil
 from plain.utils.timezone import localtime
 
 
-def localtime_filter(value, timezone=None):
+def localtime_filter(
+    value: datetime.datetime | None, timezone: Any = None
+) -> datetime.datetime:
     """Converts a datetime to local time in a template."""
     if not value:
         # Without this, we get the current localtime
@@ -15,7 +20,7 @@ def localtime_filter(value, timezone=None):
     return localtime(value, timezone)
 
 
-def pluralize_filter(value, singular="", plural="s"):
+def pluralize_filter(value: Any, singular: str = "", plural: str = "s") -> str:
     """Returns plural suffix based on the value count.
 
     Usage:

plain/templates/jinja/globals.py

@@ -5,7 +5,7 @@ from plain.urls import reverse
 from plain.utils import timezone
 
 
-def asset(url_path):
+def asset(url_path: str) -> str:
     # An explicit callable we can control, but also delay the import of asset.urls->views->templates
     # for circular import reasons
     from plain.assets.urls import get_asset_url