plain 0.66.0__py3-none-any.whl → 0.101.2__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/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)

plain/chores/README.md

@@ -8,7 +8,7 @@
 
 ## Overview
 
-Chores are registered functions that can be run at any time to keep an app in a desirable state.
+Chores are registered classes that can be run at any time to keep an app in a desirable state.
 
 ![](https://assets.plainframework.com/docs/plain-chores-run.png)
 
@@ -16,19 +16,19 @@ A good example is the clearing of expired sessions in [`plain.sessions`](/plain-
 
 ```python
 # plain/sessions/chores.py
-from plain.chores import register_chore
+from plain.chores import Chore, register_chore
 from plain.utils import timezone
 
 from .models import Session
 
 
-@register_chore("sessions")
-def clear_expired():
-    """
-    Delete sessions that have expired.
-    """
-    result = Session.query.filter(expires_at__lt=timezone.now()).delete()
-    return f"{result[0]} expired sessions deleted"
+@register_chore
+class ClearExpired(Chore):
+    """Delete sessions that have expired."""
+
+    def run(self):
+        result = Session.query.filter(expires_at__lt=timezone.now()).delete()
+        return f"{result[0]} expired sessions deleted"
 ```
 
 ## Running chores
@@ -38,33 +38,35 @@ The `plain chores run` command will execute all registered chores. When and how
 There are several ways you can run chores depending on your needs:
 
 - on deploy
-- as a [`plain.worker` scheduled job](/plain-worker/plain/worker/README.md#scheduled-jobs)
+- as a [`plain.jobs` scheduled job](/plain-jobs/plain/jobs/README.md#scheduled-jobs)
 - as a cron job (using any cron-like system where your app is hosted)
 - manually as needed
 
 ## Writing chores
 
-A chore is a function decorated with `@register_chore(chore_group_name)`. It can write a description as a docstring, and it can return a value that will be printed when the chore is run.
+A chore is a class that inherits from [`Chore`](./core.py#Chore) and implements the `run()` method. Register the chore using the [`@register_chore`](./registry.py#register_chore) decorator. The chore name is the class's qualified name (`__qualname__`), and the description comes from the class docstring.
 
 ```python
 # app/chores.py
-from plain.chores import register_chore
+from plain.chores import Chore, register_chore
+
 
+@register_chore
+class ChoreName(Chore):
+    """A chore description can go here."""
 
-@register_chore("app")
-def chore_name():
-    """
-    A chore description can go here
-    """
-    # Do a thing!
-    return "We did it!"
+    def run(self):
+        # Do a thing!
+        return "We did it!"
 ```
 
+### Best practices
+
 A good chore is:
 
-- Fast
-- Idempotent
-- Recurring
-- Stateless
+- **Fast** - Should complete quickly, not block for long periods
+- **Idempotent** - Safe to run multiple times without side effects
+- **Recurring** - Designed to run regularly, not just once
+- **Stateless** - Doesn't rely on external state between runs
 
 If chores are written in `app/chores.py` or `{pkg}/chores.py`, then they will be imported automatically and registered.

plain/chores/__init__.py

@@ -1,3 +1,4 @@
+from .core import Chore
 from .registry import register_chore
 
-__all__ = ["register_chore"]
+__all__ = ["Chore", "register_chore"]

plain/chores/core.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class Chore(ABC):
+    """
+    Abstract base class for chores.
+
+    Subclasses must implement:
+    - run() method
+
+    Example:
+        @register_chore
+        class ClearExpired(Chore):
+            '''Delete sessions that have expired.'''
+
+            def run(self):
+                # ... implementation
+                return "10 sessions deleted"
+    """
+
+    @abstractmethod
+    def run(self) -> Any:
+        """Run the chore. Must be implemented by subclasses."""
+        pass