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

plain/README.md

@@ -31,7 +31,7 @@ The `plain` package includes everything you need to start handling web requests
 - [plain.cache](/plain-cache/plain/cache/README.md) - A database-driven general purpose cache.
 - [plain.email](/plain-email/plain/email/README.md) - Send emails with SMTP or custom backends.
 - [plain.sessions](/plain-sessions/plain/sessions/README.md) - User sessions and cookies.
-- [plain.worker](/plain-worker/plain/worker/README.md) - Background jobs stored in the database.
+- [plain.jobs](/plain-jobs/plain/jobs/README.md) - Background jobs stored in the database.
 - [plain.api](/plain-api/plain/api/README.md) - Build APIs with Plain views.
 
 ## Auth Packages

plain/agents/.claude/rules/plain.md

@@ -0,0 +1,88 @@
+# Plain Framework
+
+Plain is a Python web framework.
+
+- Always use `uv run` to execute commands — never use bare `python` or `plain` directly.
+- Plain is a Django fork but has different APIs — never assume Django patterns will work.
+- When unsure about an API or something doesn't work, run `uv run plain docs <package>` first. Add `--symbols` if you need the full API surface.
+- Use the `/plain-install` skill to add new Plain packages.
+- Use the `/plain-upgrade` skill to upgrade Plain packages.
+
+## Documentation
+
+Run `uv run plain docs --list` to see all official packages (installed and uninstalled) with descriptions.
+Run `uv run plain docs <package>` for markdown documentation (installed packages only).
+Run `uv run plain docs <package> --symbols` for the symbolicated API surface.
+For uninstalled packages, the CLI shows the install command and an online docs URL.
+
+Online docs URL pattern: `https://plainframework.com/docs/<pip-name>/<module/path>/README.md`
+Example: `https://plainframework.com/docs/plain-models/plain/models/README.md`
+
+Examples:
+
+- `uv run plain docs models` - Models and database docs
+- `uv run plain docs models --symbols` - Models API surface
+- `uv run plain docs templates` - Jinja2 templates
+- `uv run plain docs assets` - Static assets
+
+### All official packages
+
+- **plain** — Web framework core
+- **plain-admin** — Backend admin interface
+- **plain-api** — Class-based API views
+- **plain-auth** — User authentication and authorization
+- **plain-cache** — Database-backed cache with optional expiration
+- **plain-code** — Preconfigured code formatting and linting
+- **plain-dev** — Local development server with auto-reload
+- **plain-elements** — HTML template components
+- **plain-email** — Send email
+- **plain-esbuild** — Build JavaScript with esbuild
+- **plain-flags** — Feature flags via database models
+- **plain-htmx** — HTMX integration for templates and views
+- **plain-jobs** — Background jobs with a database-driven queue
+- **plain-loginlink** — Link-based authentication
+- **plain-models** — Model data and store it in a database
+- **plain-oauth** — OAuth provider login
+- **plain-observer** — On-page telemetry and observability
+- **plain-pages** — Serve static pages, markdown, and assets
+- **plain-pageviews** — Client-side pageview tracking
+- **plain-passwords** — Password authentication
+- **plain-pytest** — Test with pytest
+- **plain-redirection** — URL redirection with admin and logging
+- **plain-scan** — Test for production best practices
+- **plain-sessions** — Database-backed sessions
+- **plain-start** — Bootstrap a new project from templates
+- **plain-support** — Support forms for your application
+- **plain-tailwind** — Tailwind CSS without JavaScript or npm
+- **plain-toolbar** — Debug toolbar
+- **plain-tunnel** — Remote access to local dev server
+- **plain-vendor** — Vendor CDN scripts and styles
+
+## Shell
+
+`uv run plain shell` opens an interactive Python shell with Plain configured and database access.
+
+Run a 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
+```
+
+## HTTP Requests
+
+Use `uv run plain request` to make test HTTP requests against the dev database.
+
+```
+uv run plain request /path
+uv run plain request /path --user 1
+uv run plain request /path --header "Accept: application/json"
+uv run plain request /path --method POST --data '{"key": "value"}'
+uv run plain request /path --no-body    # Headers only
+uv run plain request /path --no-headers # Body only
+```

plain/agents/.claude/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/agents/.claude/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

plain/assets/compile.py

@@ -1,13 +1,17 @@
+from __future__ import annotations
+
 import gzip
 import os
 import shutil
+from collections.abc import Iterator
+from pathlib import Path
 
 from plain.runtime import PLAIN_TEMP_PATH
 
-from .finders import iter_assets
-from .fingerprints import AssetsFingerprintsManifest, get_file_fingerprint
+from .finders import Asset, _iter_assets
+from .fingerprints import AssetsFingerprintsManifest, _get_file_fingerprint
 
-SKIP_COMPRESS_EXTENSIONS = (
+_SKIP_COMPRESS_EXTENSIONS = (
     # Images
     ".jpg",
     ".jpeg",
@@ -40,7 +44,7 @@ SKIP_COMPRESS_EXTENSIONS = (
 )
 
 
-def get_compiled_path():
+def get_compiled_path() -> Path:
     """
     Get the path at runtime to the compiled assets directory.
 
@@ -49,14 +53,16 @@ def get_compiled_path():
     return PLAIN_TEMP_PATH / "assets" / "compiled"
 
 
-def compile_assets(*, target_dir, keep_original, fingerprint, compress):
+def compile_assets(
+    *, target_dir: str, keep_original: bool, fingerprint: bool, compress: bool
+) -> Iterator[tuple[str, str, list[str]]]:
     """
     Compile all assets to the target directory and save a JSON manifest
     mapping the original filenames to the compiled filenames.
     """
     manifest = AssetsFingerprintsManifest()
 
-    for asset in iter_assets():
+    for asset in _iter_assets():
         url_path = asset.url_path
         resolved_path, compiled_paths = compile_asset(
             asset=asset,
@@ -73,17 +79,24 @@ def compile_assets(*, target_dir, keep_original, fingerprint, compress):
     manifest.save()
 
 
-def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
+def compile_asset(
+    *,
+    asset: Asset,
+    target_dir: str,
+    keep_original: bool,
+    fingerprint: bool,
+    compress: bool,
+) -> tuple[str, list[str]]:
     """
     Compile an asset to multiple output paths.
     """
-    compiled_paths = []
+    compiled_paths: list[str] = []
 
     # The expected destination for the original asset
     target_path = os.path.join(target_dir, asset.url_path)
 
     # Keep track of where the final, resolved asset ends up
-    resolved_url_path = asset.url_path
+    resolved_url_path: str = asset.url_path
 
     # Make sure all the expected directories exist
     os.makedirs(os.path.dirname(target_path), exist_ok=True)
@@ -99,16 +112,16 @@ def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
         # Fingerprint it with an md5 hash
         # (maybe need a setting with fnmatch patterns for files to NOT fingerprint?
         # that would allow pre-fingerprinted files to be used as-is, and keep source maps etc in tact)
-        fingerprint_hash = get_file_fingerprint(asset.absolute_path)
+        fingerprint_hash = _get_file_fingerprint(asset.absolute_path)
 
         fingerprinted_basename = f"{base}.{fingerprint_hash}{extension}"
         fingerprinted_path = os.path.join(target_dir, fingerprinted_basename)
         shutil.copy(asset.absolute_path, fingerprinted_path)
         compiled_paths.append(fingerprinted_path)
 
-        resolved_url_path = os.path.relpath(fingerprinted_path, target_dir)
+        resolved_url_path = str(os.path.relpath(fingerprinted_path, target_dir))
 
-    if compress and extension.lower() not in SKIP_COMPRESS_EXTENSIONS:
+    if compress and extension.lower() not in _SKIP_COMPRESS_EXTENSIONS:
         for path in compiled_paths.copy():
             gzip_path = f"{path}.gz"
             with gzip.GzipFile(gzip_path, "wb") as f:

plain/assets/finders.py

@@ -1,42 +1,48 @@
+from __future__ import annotations
+
 import os
+from collections.abc import Iterator
 
+from plain.internal import internalcode
 from plain.packages import packages_registry
 from plain.runtime import APP_PATH
 
-APP_ASSETS_DIR = APP_PATH / "assets"
+_APP_ASSETS_DIR = APP_PATH / "assets"
+
+_SKIP_ASSETS = (".DS_Store", ".gitignore")
+
 
-SKIP_ASSETS = (".DS_Store", ".gitignore")
+@internalcode
+class Asset:
+    def __init__(self, *, url_path: str, absolute_path: str):
+        self.url_path = url_path
+        self.absolute_path = absolute_path
 
+    def __str__(self) -> str:
+        return self.url_path
 
-def iter_assets():
+
+def _iter_assets() -> Iterator[Asset]:
     """
     Iterate all valid asset files found in the installed
     packages and the app itself.
     """
 
-    class Asset:
-        def __init__(self, *, url_path, absolute_path):
-            self.url_path = url_path
-            self.absolute_path = absolute_path
-
-        def __str__(self):
-            return self.url_path
-
-    def _iter_assets_dir(path):
+    def __iter_assets_dir(path: str) -> Iterator[tuple[str, str]]:
         for root, _, files in os.walk(path):
             for f in files:
-                if f in SKIP_ASSETS:
+                if f in _SKIP_ASSETS:
                     continue
                 abs_path = os.path.join(root, f)
                 url_path = os.path.relpath(abs_path, path)
                 yield url_path, abs_path
 
-    for asset_dir in iter_asset_dirs():
-        for url_path, abs_path in _iter_assets_dir(asset_dir):
+    for asset_dir in _iter_asset_dirs():
+        for url_path, abs_path in __iter_assets_dir(asset_dir):
             yield Asset(url_path=url_path, absolute_path=abs_path)
 
 
-def iter_asset_dirs():
+def _iter_asset_dirs() -> Iterator[str]:
     """
     Iterate all directories containing assets, from installed
     packages and from app/assets.
@@ -48,4 +54,5 @@ def iter_asset_dirs():
             yield asset_dir
 
     # The app/assets take priority over everything
-    yield APP_ASSETS_DIR
+    if _APP_ASSETS_DIR.exists():
+        yield _APP_ASSETS_DIR

plain/assets/fingerprints.py

@@ -2,11 +2,13 @@ import hashlib
 import json
 from functools import cache
 
+from plain.internal import internalcode
 from plain.runtime import PLAIN_TEMP_PATH
 
-FINGERPRINT_LENGTH = 7
+_FINGERPRINT_LENGTH = 7
 
 
+@internalcode
 class AssetsFingerprintsManifest(dict):
     """
     A manifest of original filenames to fingerprinted filenames.
@@ -15,18 +17,18 @@ class AssetsFingerprintsManifest(dict):
     def __init__(self):
         self.path = PLAIN_TEMP_PATH / "assets" / "fingerprints.json"
 
-    def load(self):
+    def load(self) -> None:
         if self.path.exists():
             with open(self.path) as f:
                 self.update(json.load(f))
 
-    def save(self):
+    def save(self) -> None:
         with open(self.path, "w") as f:
             json.dump(self, f, indent=2)
 
 
 @cache
-def _get_manifest():
+def _get_manifest() -> AssetsFingerprintsManifest:
     """
     A cached function for loading the asset fingerprints manifest,
     so we don't have to keep loading it from disk over and over.
@@ -36,23 +38,24 @@ def _get_manifest():
     return manifest
 
 
-def get_fingerprinted_url_path(url_path):
+def get_fingerprinted_url_path(url_path: str) -> str | None:
     """
     Get the final fingerprinted path for an asset URL path.
     """
     manifest = _get_manifest()
     if url_path in manifest:
         return manifest[url_path]
+    return None
 
 
-def get_file_fingerprint(file_path):
+def _get_file_fingerprint(file_path: str) -> str:
     """
     Get the fingerprint hash for a file.
     """
     with open(file_path, "rb") as f:
         content = f.read()
         fingerprint_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()[
-            :FINGERPRINT_LENGTH
+            :_FINGERPRINT_LENGTH
         ]
 
     return fingerprint_hash

plain/assets/urls.py

@@ -18,7 +18,7 @@ class AssetsRouter(Router):
     ]
 
 
-def get_asset_url(url_path):
+def get_asset_url(url_path: str) -> str:
     """
     Get the full URL to a given asset path.
     """

plain/assets/views.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import functools
 import mimetypes
 import os
@@ -6,19 +8,20 @@ from io import BytesIO
 
 from plain.http import (
     FileResponse,
-    Http404,
+    NotFoundError404,
+    NotModifiedResponse,
+    RedirectResponse,
     Response,
-    ResponseNotModified,
-    ResponseRedirect,
     StreamingResponse,
 )
+from plain.http.response import ResponseHeaders
 from plain.runtime import settings
 from plain.urls import reverse
 from plain.views import View
 
 from .compile import get_compiled_path
-from .finders import iter_assets
-from .fingerprints import FINGERPRINT_LENGTH, get_fingerprinted_url_path
+from .finders import _iter_assets
+from .fingerprints import _FINGERPRINT_LENGTH, get_fingerprinted_url_path
 
 
 class AssetView(View):
@@ -28,16 +31,19 @@ class AssetView(View):
     This class could be subclassed to further tweak the responses or behavior.
     """
 
-    def __init__(self, asset_path=None):
+    def __init__(self, asset_path: str | None = None):
         # Allow a path to be passed in AssetView.as_view(path="...")
         self.asset_path = asset_path
 
-    def get_url_path(self):
+    def get_url_path(self) -> str | None:
         return self.asset_path or self.url_kwargs["path"]
 
-    def get(self):
+    def get(self) -> Response | FileResponse | StreamingResponse:
         url_path = self.get_url_path()
 
+        if not url_path:
+            raise NotFoundError404("Asset path not found")
+
         # Make a trailing slash work, but we don't expect it
         url_path = url_path.rstrip("/")
 
@@ -50,7 +56,11 @@ class AssetView(View):
                 if redirect_response := self.get_redirect_response(url_path):
                     return redirect_response
 
+        # check_asset_path validates and raises if path is invalid
+        # After this point, absolute_path is guaranteed to be a valid str
         self.check_asset_path(absolute_path)
+        # Type guard: absolute_path is now str (check_asset_path raises if None/invalid)
+        assert absolute_path is not None
 
         if encoded_path := self.get_encoded_path(absolute_path):
             absolute_path = encoded_path
@@ -71,35 +81,36 @@ class AssetView(View):
         response.headers = self.update_headers(response.headers, absolute_path)
         return response
 
-    def get_asset_path(self, path):
+    def get_asset_path(self, path: str) -> str:
         """Get the path to the compiled asset"""
         compiled_path = os.path.abspath(get_compiled_path())
         asset_path = os.path.join(compiled_path, path)
 
         # Make sure we don't try to escape the compiled assests path
         if not os.path.commonpath([compiled_path, asset_path]) == compiled_path:
-            raise Http404("Asset not found")
+            raise NotFoundError404("Asset not found")
 
         return asset_path
 
-    def get_debug_asset_path(self, path):
+    def get_debug_asset_path(self, path: str) -> str | None:
         """Make a "live" check to find the uncompiled asset in the filesystem"""
-        for asset in iter_assets():
+        for asset in _iter_assets():
             if asset.url_path == path:
                 return asset.absolute_path
+        return None
 
-    def check_asset_path(self, path):
+    def check_asset_path(self, path: str | None) -> None:
         if not path:
-            raise Http404("Asset not found")
+            raise NotFoundError404("Asset not found")
 
         if not os.path.exists(path):
-            raise Http404("Asset not found")
+            raise NotFoundError404("Asset not found")
 
         if os.path.isdir(path):
-            raise Http404("Asset is a directory")
+            raise NotFoundError404("Asset is a directory")
 
     @functools.cache
-    def get_last_modified(self, path):
+    def get_last_modified(self, path: str) -> str | None:
         try:
             mtime = os.path.getmtime(path)
         except OSError:
@@ -107,23 +118,24 @@ class AssetView(View):
 
         if mtime:
             return formatdate(mtime, usegmt=True)
+        return None
 
     @functools.cache
-    def get_etag(self, path):
+    def get_etag(self, path: str) -> str:
         try:
             mtime = os.path.getmtime(path)
         except OSError:
-            mtime = None
+            mtime = 0.0
 
         timestamp = int(mtime)
         size = self.get_size(path)
         return f'"{timestamp:x}-{size:x}"'
 
     @functools.cache
-    def get_size(self, path):
+    def get_size(self, path: str) -> int:
         return os.path.getsize(path)
 
-    def update_headers(self, headers, path):
+    def update_headers(self, headers: ResponseHeaders, path: str) -> ResponseHeaders:
         headers.setdefault("Access-Control-Allow-Origin", "*")
 
         # Always vary on Accept-Encoding
@@ -165,7 +177,7 @@ class AssetView(View):
 
         return headers
 
-    def is_immutable(self, path):
+    def is_immutable(self, path: str) -> bool:
         """
         Determine whether an asset looks like it is immutable.
 
@@ -177,19 +189,19 @@ class AssetView(View):
         extension = None
         while extension != "":
             base, extension = os.path.splitext(base)
-            if len(extension) == FINGERPRINT_LENGTH + 1 and extension[1:].isalnum():
+            if len(extension) == _FINGERPRINT_LENGTH + 1 and extension[1:].isalnum():
                 return True
 
         return False
 
-    def get_encoded_path(self, path):
+    def get_encoded_path(self, path: str) -> str | None:
         """
         If the client supports compression, return the path to the compressed file.
         Otherwise, return the original path.
         """
         accept_encoding = self.request.headers.get("Accept-Encoding")
         if not accept_encoding:
-            return
+            return None
 
         if "br" in accept_encoding:
             br_path = path + ".br"
@@ -200,33 +212,34 @@ class AssetView(View):
             gzip_path = path + ".gz"
             if os.path.exists(gzip_path):
                 return gzip_path
+        return None
 
-    def get_redirect_response(self, path):
+    def get_redirect_response(self, path: str) -> RedirectResponse | None:
         """If the asset is not found, try to redirect to the fingerprinted path"""
         fingerprinted_url_path = get_fingerprinted_url_path(path)
 
         if not fingerprinted_url_path or fingerprinted_url_path == path:
             # Don't need to redirect if there is no fingerprinted path,
             # or we're already looking at it.
-            return
+            return None
 
         from .urls import AssetsRouter
 
         namespace = AssetsRouter.namespace
 
-        return ResponseRedirect(
+        return RedirectResponse(
             redirect_to=reverse(f"{namespace}:asset", fingerprinted_url_path),
             headers={
                 "Cache-Control": "max-age=60",  # Can cache this for a short time, but the fingerprinted path can change
             },
         )
 
-    def get_conditional_response(self, path):
+    def get_conditional_response(self, path: str) -> NotModifiedResponse | None:
         """
         Support conditional requests (HTTP 304 response) based on ETag and Last-Modified headers.
         """
         if self.request.headers.get("If-None-Match") == self.get_etag(path):
-            response = ResponseNotModified()
+            response = NotModifiedResponse()
             response.headers = self.update_headers(response.headers, path)
             return response
 
@@ -238,11 +251,12 @@ class AssetView(View):
                 and last_modified
                 and if_modified_since >= last_modified
             ):
-                response = ResponseNotModified()
+                response = NotModifiedResponse()
                 response.headers = self.update_headers(response.headers, path)
                 return response
+        return None
 
-    def get_range_response(self, path):
+    def get_range_response(self, path: str) -> Response | StreamingResponse | None:
         """
         Support range requests (HTTP 206 response).
         """
@@ -266,7 +280,7 @@ class AssetView(View):
                 status_code=416, headers=[("Content-Range", f"bytes */{file_size}")]
             )
 
-        end = min(end, file_size - 1)
+        end = int(min(end, file_size - 1))
 
         with open(path, "rb") as f:
             f.seek(start)