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

plain/signals/dispatch/dispatcher.py

@@ -1,22 +1,29 @@
+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
 
-logger = logging.getLogger("plain.signals.dispatch")
+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)
 
 
-NONE_ID = _make_id(None)
+_NONE_ID = _make_id(None)
 
 # A marker for caching
-NO_RECEIVERS = object()
+_NO_RECEIVERS = object()
 
 
 class Signal:
@@ -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.
 
@@ -175,7 +193,7 @@ class Signal:
         """
         if (
             not self.receivers
-            or self.sender_receivers_cache.get(sender) is NO_RECEIVERS
+            or self.sender_receivers_cache.get(sender) is _NO_RECEIVERS
         ):
             return []
         responses = []
@@ -185,15 +203,17 @@ class Signal:
             responses.append((receiver, response))
         return responses
 
-    def _log_robust_failure(self, receiver, err):
-        logger.error(
+    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.
 
@@ -218,7 +238,7 @@ class Signal:
         """
         if (
             not self.receivers
-            or self.sender_receivers_cache.get(sender) is NO_RECEIVERS
+            or self.sender_receivers_cache.get(sender) is _NO_RECEIVERS
         ):
             return []
 
@@ -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.
 
@@ -256,9 +276,9 @@ class Signal:
         receivers = None
         if self.use_caching and not self._dead_receivers:
             receivers = self.sender_receivers_cache.get(sender)
-            # We could end up here with NO_RECEIVERS even if we do check this case in
+            # We could end up here with _NO_RECEIVERS even if we do check this case in
             # .send() prior to calling _live_receivers() due to concurrent .send() call.
-            if receivers is NO_RECEIVERS:
+            if receivers is _NO_RECEIVERS:
                 return []
         if receivers is None:
             with self.lock:
@@ -266,11 +286,11 @@ class Signal:
                 senderkey = _make_id(sender)
                 receivers = []
                 for (_receiverkey, r_senderkey), receiver in self.receivers:
-                    if r_senderkey == NONE_ID or r_senderkey == senderkey:
+                    if r_senderkey == _NONE_ID or r_senderkey == senderkey:
                         receivers.append(receiver)
                 if self.use_caching:
                     if not receivers:
-                        self.sender_receivers_cache[sender] = NO_RECEIVERS
+                        self.sender_receivers_cache[sender] = _NO_RECEIVERS
                     else:
                         # Note, we must cache the weakref versions.
                         self.sender_receivers_cache[sender] = 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()
@@ -243,27 +260,106 @@ class Signer:
         return serializer().loads(data)
 
 
-class TimestampSigner(Signer):
-    def timestamp(self):
+class TimestampSigner:
+    """A signer that includes a timestamp for max_age validation.
+
+    Uses composition rather than inheritance since the interface
+    intentionally differs from Signer (unsign accepts max_age parameter).
+    """
+
+    def __init__(
+        self,
+        *,
+        key: str | None = None,
+        sep: str = ":",
+        salt: str | None = None,
+        algorithm: str = "sha256",
+        fallback_keys: list[str] | None = None,
+    ) -> None:
+        # Compute default salt here to preserve backwards compatibility.
+        # When TimestampSigner inherited from Signer, the default salt was
+        # "plain.signing.TimestampSigner". Now that we use composition,
+        # we must set it explicitly rather than letting Signer compute its own.
+        if salt is None:
+            salt = f"{self.__class__.__module__}.{self.__class__.__name__}"
+        self._signer = Signer(
+            key=key,
+            sep=sep,
+            salt=salt,
+            algorithm=algorithm,
+            fallback_keys=fallback_keys,
+        )
+
+    @property
+    def sep(self) -> str:
+        return self._signer.sep
+
+    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)
+        return self._signer.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.
         """
-        result = super().unsign(value)
+        result = self._signer.unsign(value)
         value, timestamp = result.rsplit(self.sep, 1)
-        timestamp = b62_decode(timestamp)
+        ts = b62_decode(timestamp)
         if max_age is not None:
             if isinstance(max_age, datetime.timedelta):
                 max_age = max_age.total_seconds()
             # Check timestamp is not older than max_age
-            age = time.time() - timestamp
+            age = time.time() - ts
             if age > max_age:
                 raise SignatureExpired(f"Signature age {age} > {max_age} seconds")
         return value
+
+    def sign_object(
+        self,
+        obj: Any,
+        serializer: type[JSONSerializer] = JSONSerializer,
+        compress: bool = False,
+    ) -> str:
+        """
+        Return URL-safe, hmac signed base64 compressed JSON string.
+
+        If compress is True (not the default), check if compressing using zlib
+        can save some space. Prepend a '.' to signify compression. This is
+        included in the signature, to protect against zip bombs.
+
+        The serializer is expected to return a bytestring.
+        """
+        data = serializer().dumps(obj)
+        is_compressed = False
+
+        if compress:
+            compressed = zlib.compress(data)
+            if len(compressed) < (len(data) - 1):
+                data = compressed
+                is_compressed = True
+        base64d = b64_encode(data).decode()
+        if is_compressed:
+            base64d = "." + base64d
+        return self.sign(base64d)
+
+    def unsign_object(
+        self,
+        signed_obj: str,
+        serializer: type[JSONSerializer] = JSONSerializer,
+        max_age: int | float | datetime.timedelta | None = None,
+    ) -> Any:
+        """Unsign and decode an object, optionally checking max_age."""
+        base64d = self.unsign(signed_obj, max_age=max_age).encode()
+        decompress = base64d[:1] == b"."
+        if decompress:
+            base64d = base64d[1:]
+        data = b64_decode(base64d)
+        if decompress:
+            data = zlib.decompress(data)
+        return serializer().loads(data)

plain/skills/README.md

@@ -0,0 +1,36 @@
+# plain.skills
+
+**Agent skills for working with Plain projects.**
+
+These skills provide context and workflows for common tasks when using [Claude Code](https://docs.anthropic.com/en/docs/claude-code) or [Codex](https://codex.openai.com/).
+
+## Available skills
+
+| Skill           | Description                                                    |
+| --------------- | -------------------------------------------------------------- |
+| `plain-docs`    | Retrieves detailed documentation for Plain packages            |
+| `plain-install` | Installs Plain packages and guides through setup steps         |
+| `plain-upgrade` | Upgrades Plain packages and applies required migration changes |
+| `plain-shell`   | Runs Python with Plain configured and database access          |
+| `plain-request` | Makes test HTTP requests against the development database      |
+
+## Installation
+
+To install skills to your project's `.claude/` or `.codex/` directory:
+
+```bash
+uv run plain agent install
+```
+
+This command:
+
+- Copies skill definitions so your agent can use them
+- Sets up a `SessionStart` hook that runs `plain agent context` at the start of every session
+
+Run it again after upgrading Plain to get updated skills.
+
+## Commands
+
+- `plain agent install` - Install skills and set up hooks
+- `plain agent skills` - List available skills from installed packages
+- `plain agent context` - Output framework context (used by the SessionStart hook)

plain/skills/plain-docs/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: plain-docs
+description: Retrieves detailed documentation for Plain packages. Use when looking up package APIs or feature details.
+---
+
+# Getting Documentation
+
+## List Available Packages
+
+```
+uv run plain docs --list
+```
+
+## Get Package Documentation
+
+```
+uv run plain docs <package> --source
+```
+
+Examples:
+
+- `uv run plain docs models --source` - Models and database
+- `uv run plain docs templates --source` - Jinja2 templates
+- `uv run plain docs assets --source` - Static assets
+- `uv run plain docs tailwind --source` - Tailwind CSS integration

plain/skills/plain-install/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: plain-install
+description: Installs Plain packages and guides through setup steps. Use when adding new packages to a project.
+---
+
+# Install Plain Packages
+
+## 1. Install the package(s)
+
+```
+uv run plain install <package-name> [additional-packages...]
+```
+
+## 2. Complete setup for each package
+
+1. Run `uv run plain docs <package>` and read the installation instructions
+2. If the docs indicate it's a dev tool, move it: `uv remove <package> && uv add <package> --dev`
+3. Complete any code modifications from the installation instructions
+
+## Guidelines
+
+- DO NOT commit any changes
+- Report back with:
+    - Whether setup completed successfully
+    - Any manual steps the user needs to complete
+    - Any issues or errors encountered

plain/skills/plain-request/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: plain-request
+description: Makes HTTP requests to test URLs, check endpoints, fetch pages, or debug routes. Use when asked to look at a URL, hit an endpoint, test a route, or make GET/POST requests.
+---
+
+# Making HTTP Requests
+
+Use `uv run plain request` to make test requests against the dev database.
+
+## Basic Usage
+
+```
+uv run plain request /path
+```
+
+## With Authentication
+
+```
+uv run plain request /path --user 1
+```
+
+## With Custom Headers
+
+```
+uv run plain request /path --header "Accept: application/json"
+```
+
+## POST/PUT/PATCH with Data
+
+```
+uv run plain request /path --method POST --data '{"key": "value"}'
+```
+
+## Limiting Output
+
+```
+uv run plain request /path --no-body    # Headers only
+uv run plain request /path --no-headers # Body only
+```

plain/skills/plain-shell/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: plain-shell
+description: Runs Python with Plain configured and database access. Use for scripts, one-off commands, or interactive sessions.
+---
+
+# Running Python with Plain
+
+## Interactive Shell
+
+```
+uv run plain shell
+```
+
+## One-off Command
+
+```
+uv run plain shell -c "from app.users.models import User; print(User.query.count())"
+```
+
+## Run a Script
+
+```
+uv run plain run script.py
+```

plain/skills/plain-upgrade/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: plain-upgrade
+description: Upgrades Plain packages and applies required migration changes. Use when updating to newer package versions.
+---
+
+# Upgrade Plain Packages
+
+## 1. Run the upgrade
+
+```
+uv run plain upgrade [package-names...]
+```
+
+This will show which packages were upgraded (e.g., `plain-models: 0.1.0 -> 0.2.0`).
+
+## 2. Apply code changes for each upgraded package
+
+For each package that was upgraded:
+
+1. Run `uv run plain changelog <package> --from <old-version> --to <new-version>`
+2. Read the "Upgrade instructions" section
+3. If it says "No changes required", skip to next package
+4. Apply any required code changes
+
+## 3. Validate
+
+1. Run `uv run plain fix` to fix formatting
+2. Run `uv run plain preflight` to validate configuration
+
+## Guidelines
+
+- Process ALL packages before testing
+- DO NOT commit any changes
+- Keep code changes minimal and focused
+- Report any issues or conflicts encountered