plain 0.76.0__tar.gz → 0.78.0__tar.gz

{plain-0.76.0 → plain-0.78.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.76.0
+Version: 0.78.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE
@@ -9,6 +9,7 @@ Requires-Dist: click>=8.0.0
 Requires-Dist: jinja2>=3.1.2
 Requires-Dist: opentelemetry-api>=1.34.1
 Requires-Dist: opentelemetry-semantic-conventions>=0.55b1
+Requires-Dist: watchfiles>=0.18.0
 Description-Content-Type: text/markdown
 
 # Plain

{plain-0.76.0 → plain-0.78.0}/plain/CHANGELOG.md

@@ -1,5 +1,51 @@
 # plain changelog
 
+## [0.78.0](https://github.com/dropseed/plain/releases/plain@0.78.0) (2025-10-17)
+
+### What's changed
+
+- Chores have been refactored to use abstract base classes instead of decorated functions ([c4466d3c60](https://github.com/dropseed/plain/commit/c4466d3c60))
+- Added `SHELL_IMPORT` setting to customize what gets automatically imported in `plain shell` ([9055f59c08](https://github.com/dropseed/plain/commit/9055f59c08))
+- Views that return `None` now raise `Http404` instead of returning `ResponseNotFound` ([5bb60016eb](https://github.com/dropseed/plain/commit/5bb60016eb))
+- The `plain chores list` command output formatting now matches the `plain jobs list` format ([4b6881a49e](https://github.com/dropseed/plain/commit/4b6881a49e))
+
+### Upgrade instructions
+
+- Update any chores from decorated functions to class-based chores:
+
+    ```python
+    # Before:
+    @register_chore("group")
+    def chore_name():
+        """Description"""
+        return "Done!"
+
+    # After:
+    from plain.chores import Chore, register_chore
+
+    @register_chore
+    class ChoreName(Chore):
+        """Description"""
+
+        def run(self):
+            return "Done!"
+    ```
+
+- Import `Chore` base class from `plain.chores` when creating new chores
+
+## [0.77.0](https://github.com/dropseed/plain/releases/plain@0.77.0) (2025-10-13)
+
+### What's changed
+
+- The `plain server --reload` now uses `watchfiles` for improved cross-platform file watching ([92e95c5032](https://github.com/dropseed/plain/commit/92e95c5032))
+- Server reloader now watches `.env*` files for changes and triggers automatic reload ([92e95c5032](https://github.com/dropseed/plain/commit/92e95c5032))
+- HTML template additions and deletions now trigger automatic server reload when using `--reload` ([f2f31c288b](https://github.com/dropseed/plain/commit/f2f31c288b))
+- Internal server worker type renamed from "gthread" to "thread" for clarity ([6470748e91](https://github.com/dropseed/plain/commit/6470748e91))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.76.0](https://github.com/dropseed/plain/releases/plain@0.76.0) (2025-10-12)
 
 ### What's changed

{plain-0.76.0 → plain-0.78.0}/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
@@ -44,27 +44,29 @@ There are several ways you can run chores depending on your needs:
 
 ## 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-0.78.0/plain/chores/__init__.py

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

plain-0.78.0/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

plain-0.78.0/plain/chores/registry.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from plain.packages import packages_registry
+
+from .core import Chore
+
+
+class ChoresRegistry:
+    def __init__(self) -> None:
+        self._chores: dict[str, type[Chore]] = {}
+
+    def register_chore(self, chore_class: type[Chore]) -> None:
+        """
+        Register a chore class.
+
+        Args:
+            chore_class: A Chore subclass to register
+        """
+        name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        self._chores[name] = chore_class
+
+    def import_modules(self) -> None:
+        """
+        Import modules from installed packages and app to trigger registration.
+        """
+        packages_registry.autodiscover_modules("chores", include_app=True)
+
+    def get_chores(self) -> list[type[Chore]]:
+        """
+        Get all registered chore classes.
+        """
+        return list(self._chores.values())
+
+
+chores_registry = ChoresRegistry()
+
+
+def register_chore(cls: type[Chore]) -> type[Chore]:
+    """
+    Decorator to register a chore class.
+
+    Usage:
+        @register_chore
+        class ClearExpired(Chore):
+            def run(self):
+                return "Done!"
+    """
+    chores_registry.register_chore(cls)
+    return cls

{plain-0.76.0 → plain-0.78.0}/plain/cli/README.md

@@ -4,6 +4,7 @@
 
 - [Overview](#overview)
 - [Adding commands](#adding-commands)
+- [Shell](#shell)
 
 ## Overview
 
@@ -39,3 +40,28 @@ An example command!
 ```
 
 Technically you can register a CLI from anywhere, but typically you will do it in either `app/cli.py` or a package's `<pkg>/cli.py`, as those modules will be autoloaded by Plain.
+
+## Shell
+
+The `plain shell` command starts an interactive Python shell with your Plain app already loaded.
+
+### SHELL_IMPORT
+
+You can customize what gets imported automatically when the shell starts by setting `SHELL_IMPORT` to a module path in your settings:
+
+```python
+# app/settings.py
+SHELL_IMPORT = "app.shell"
+```
+
+Then create that module with the objects you want available:
+
+```python
+# app/shell.py
+from app.projects.models import Project
+from app.users.models import User
+
+__all__ = ["Project", "User"]
+```
+
+Now when you run `plain shell`, those objects will be automatically imported and available.

{plain-0.76.0 → plain-0.78.0}/plain/cli/chores.py

@@ -13,11 +13,10 @@ def chores() -> None:
 
 
 @chores.command("list")
-@click.option("--group", default=None, type=str, help="Group to run", multiple=True)
 @click.option(
     "--name", default=None, type=str, help="Name of the chore to run", multiple=True
 )
-def list_chores(group: tuple[str, ...], name: tuple[str, ...]) -> None:
+def list_chores(name: tuple[str, ...]) -> None:
     """
     List all registered chores.
     """
@@ -25,32 +24,33 @@ def list_chores(group: tuple[str, ...], name: tuple[str, ...]) -> None:
 
     chores_registry.import_modules()
 
-    if group or name:
-        chores = [
-            chore
-            for chore in chores_registry.get_chores()
-            if (chore.group in group or not group) and (chore.name in name or not name)
+    chore_classes = chores_registry.get_chores()
+
+    if name:
+        chore_classes = [
+            chore_class
+            for chore_class in chore_classes
+            if f"{chore_class.__module__}.{chore_class.__qualname__}" in name
         ]
-    else:
-        chores = chores_registry.get_chores()
 
-    for chore in chores:
-        click.secho(f"{chore}", bold=True, nl=False)
-        if chore.description:
-            click.echo(f": {chore.description}")
+    for chore_class in chore_classes:
+        chore_name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        click.secho(f"{chore_name}", bold=True, nl=False)
+        description = chore_class.__doc__.strip() if chore_class.__doc__ else ""
+        if description:
+            click.secho(f": {description}", dim=True)
         else:
             click.echo("")
 
 
 @chores.command("run")
-@click.option("--group", default=None, type=str, help="Group to run", multiple=True)
 @click.option(
     "--name", default=None, type=str, help="Name of the chore to run", multiple=True
 )
 @click.option(
     "--dry-run", is_flag=True, help="Show what would be done without executing"
 )
-def run_chores(group: tuple[str, ...], name: tuple[str, ...], dry_run: bool) -> None:
+def run_chores(name: tuple[str, ...], dry_run: bool) -> None:
     """
     Run the specified chores.
     """
@@ -58,28 +58,30 @@ def run_chores(group: tuple[str, ...], name: tuple[str, ...], dry_run: bool) ->
 
     chores_registry.import_modules()
 
-    if group or name:
-        chores = [
-            chore
-            for chore in chores_registry.get_chores()
-            if (chore.group in group or not group) and (chore.name in name or not name)
+    chore_classes = chores_registry.get_chores()
+
+    if name:
+        chore_classes = [
+            chore_class
+            for chore_class in chore_classes
+            if f"{chore_class.__module__}.{chore_class.__qualname__}" in name
         ]
-    else:
-        chores = chores_registry.get_chores()
 
     chores_failed = []
 
-    for chore in chores:
-        click.echo(f"{chore.name}:", nl=False)
+    for chore_class in chore_classes:
+        chore_name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        click.echo(f"{chore_name}:", nl=False)
         if dry_run:
             click.secho(" (dry run)", fg="yellow", nl=False)
         else:
             try:
+                chore = chore_class()
                 result = chore.run()
             except Exception:
                 click.secho(" Failed", fg="red")
-                chores_failed.append(chore)
-                logger.exception(f"Error running chore {chore.name}")
+                chores_failed.append(chore_class)
+                logger.exception(f"Error running chore {chore_name}")
                 continue
 
             if result is None:

{plain-0.76.0 → plain-0.78.0}/plain/cli/server.py

@@ -58,12 +58,6 @@ from plain.cli.runtime import without_runtime_setup
     is_flag=True,
     help="Restart workers when code changes (dev only)",
 )
-@click.option(
-    "--reload-extra-file",
-    multiple=True,
-    type=click.Path(exists=True),
-    help="Additional files to watch for reload (can be used multiple times)",
-)
 @click.option(
     "--access-log",
     default="-",
@@ -109,7 +103,6 @@ def server(
     keyfile: str | None,
     log_level: str,
     reload: bool,
-    reload_extra_file: tuple[str, ...],
     access_log: str,
     error_log: str,
     log_format: str,
@@ -130,7 +123,6 @@ def server(
         timeout=timeout,
         max_requests=max_requests,
         reload=reload,
-        reload_extra_files=list(reload_extra_file) if reload_extra_file else [],
         pidfile=pidfile,
         certfile=certfile,
         keyfile=keyfile,

plain-0.78.0/plain/internal/reloader.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import os
+import os.path
+import re
+import sys
+import threading
+from collections.abc import Callable
+
+import watchfiles
+
+COMPILED_EXT_RE = re.compile(r"py[co]$")
+
+
+class Reloader(threading.Thread):
+    """File change reloader using watchfiles for cross-platform native file watching."""
+
+    def __init__(self, callback: Callable[[str], None], watch_html: bool) -> None:
+        super().__init__()
+        self.daemon = True
+        self._callback = callback
+        self._watch_html = watch_html
+
+    def get_watch_paths(self) -> set[str]:
+        """Get all directories to watch for changes."""
+        paths = set()
+
+        # Get directories from loaded Python modules
+        for module in tuple(sys.modules.values()):
+            if not hasattr(module, "__file__") or not module.__file__:
+                continue
+            # Convert .pyc/.pyo to .py and get directory
+            file_path = COMPILED_EXT_RE.sub("py", module.__file__)
+            dir_path = os.path.dirname(os.path.abspath(file_path))
+            if os.path.isdir(dir_path):
+                paths.add(dir_path)
+
+        # Add current working directory for .env files
+        cwd = os.getcwd()
+        if os.path.isdir(cwd):
+            paths.add(cwd)
+
+        return paths
+
+    def run(self) -> None:
+        """Watch for file changes and trigger callback."""
+        watch_paths = self.get_watch_paths()
+
+        for changes in watchfiles.watch(*watch_paths, rust_timeout=1000):
+            for change_type, file_path in changes:
+                should_reload = False
+                filename = os.path.basename(file_path)
+
+                # Python files: reload on modify/add
+                if change_type in (watchfiles.Change.modified, watchfiles.Change.added):
+                    if file_path.endswith(".py"):
+                        should_reload = True
+
+                # .env files: reload on modify/add/delete
+                if change_type in (
+                    watchfiles.Change.modified,
+                    watchfiles.Change.added,
+                    watchfiles.Change.deleted,
+                ):
+                    if filename.startswith(".env"):
+                        should_reload = True
+
+                # HTML files: only reload on add/delete (Jinja auto-reloads modifications)
+                if self._watch_html and change_type in (
+                    watchfiles.Change.added,
+                    watchfiles.Change.deleted,
+                ):
+                    if file_path.endswith(".html"):
+                        should_reload = True
+
+                if should_reload:
+                    self._callback(file_path)

{plain-0.76.0 → plain-0.78.0}/plain/server/README.md

@@ -39,8 +39,7 @@ Common options:
 - `--workers` / `-w` - Number of worker processes (default: 1, or `$WEB_CONCURRENCY` env var)
 - `--threads` - Number of threads per worker (default: 1)
 - `--timeout` / `-t` - Worker timeout in seconds (default: 30)
-- `--reload` - Enable auto-reload on code changes (default: False)
-- `--reload-extra-file` - Additional files to watch for reloading (can be used multiple times)
+- `--reload` - Enable auto-reload on code changes, including `.env*` files (default: False)
 - `--certfile` - Path to SSL certificate file
 - `--keyfile` - Path to SSL key file
 - `--log-level` - Logging level: debug, info, warning, error, critical (default: info)

{plain-0.76.0 → plain-0.78.0}/plain/server/arbiter.py

@@ -490,7 +490,7 @@ class Arbiter:
         # Process Child
         worker.pid = os.getpid()
         try:
-            self.log.info("Plain server worker started pid=%s", worker.pid)
+            self.log.info("Server worker started pid=%s", worker.pid)
             worker.init_process()
             sys.exit(0)
         except SystemExit:
@@ -506,7 +506,7 @@ class Arbiter:
                 sys.exit(self.WORKER_BOOT_ERROR)
             sys.exit(-1)
         finally:
-            self.log.info("Worker exiting (pid: %s)", worker.pid)
+            self.log.info("Server worker exiting (pid: %s)", worker.pid)
             try:
                 worker.tmp.close()
             except Exception:

{plain-0.76.0 → plain-0.78.0}/plain/server/config.py

@@ -10,6 +10,8 @@ import os
 from dataclasses import dataclass
 
 from . import util
+from .workers.sync import SyncWorker
+from .workers.thread import ThreadWorker
 
 
 @dataclass
@@ -27,7 +29,6 @@ class Config:
     timeout: int
     max_requests: int
     reload: bool
-    reload_extra_files: list[str]
     pidfile: str | None
     certfile: str | None
     keyfile: str | None
@@ -41,20 +42,19 @@ class Config:
     def worker_class_str(self) -> str:
         # Auto-select based on threads
         if self.threads > 1:
-            return "gthread"
+            return "thread"
         return "sync"
 
     @property
     def worker_class(self) -> type:
         # Auto-select based on threads
         if self.threads > 1:
-            uri = "plain.server.workers.gthread.ThreadWorker"
+            worker_class = ThreadWorker
         else:
-            uri = "plain.server.workers.sync.SyncWorker"
+            worker_class = SyncWorker
 
-        worker_class = util.load_class(uri)
         if hasattr(worker_class, "setup"):
-            worker_class.setup()  # type: ignore[call-non-callable]  # hasattr check doesn't narrow type
+            worker_class.setup()
         return worker_class
 
     @property

{plain-0.76.0 → plain-0.78.0}/plain/server/util.py

@@ -10,8 +10,6 @@ import email.utils
 import errno
 import fcntl
 import html
-import importlib
-import inspect
 import io
 import os
 import random
@@ -20,14 +18,11 @@ import socket
 import sys
 import textwrap
 import time
-import traceback
 import urllib.parse
 import warnings
 from collections.abc import Callable
 from typing import Any
 
-from .workers import SUPPORTED_WORKERS
-
 # Server and Date aren't technically hop-by-hop
 # headers, but they are in the purview of the
 # origin server which the WSGI spec says we should
@@ -44,55 +39,6 @@ hop_headers = set(
     """.split()
 )
 
-
-def load_class(
-    uri: str | type,
-    default: str = "plain.server.workers.sync.SyncWorker",
-    section: str = "plain.server.workers",
-) -> type:
-    if inspect.isclass(uri):
-        return uri  # type: ignore[return-value]
-
-    components = uri.split(".")  # type: ignore[union-attr]
-    if len(components) == 1:
-        # Handle short names like "sync" or "gthread"
-        if uri.startswith("#"):  # type: ignore[union-attr]
-            uri = uri[1:]  # type: ignore[union-attr]
-
-        if uri in SUPPORTED_WORKERS:
-            components = SUPPORTED_WORKERS[uri].split(".")
-        else:
-            exc_msg = f"Worker type {uri!r} not found in SUPPORTED_WORKERS"
-            raise RuntimeError(exc_msg)
-
-    klass = components.pop(-1)
-
-    try:
-        mod = importlib.import_module(".".join(components))
-    except Exception:
-        exc = traceback.format_exc()
-        msg = "class uri %r invalid or not found: \n\n[%s]"
-        raise RuntimeError(msg % (uri, exc))
-    return getattr(mod, klass)
-
-
-positionals = (
-    inspect.Parameter.POSITIONAL_ONLY,
-    inspect.Parameter.POSITIONAL_OR_KEYWORD,
-)
-
-
-def get_arity(f: Callable[..., Any]) -> int:
-    sig = inspect.signature(f)
-    arity = 0
-
-    for param in sig.parameters.values():
-        if param.kind in positionals:
-            arity += 1
-
-    return arity
-
-
 if sys.platform.startswith("win"):
 
     def _waitfor(
@@ -317,19 +263,6 @@ def has_fileno(obj: Any) -> bool:
     return True
 
 
-def warn(msg: str) -> None:
-    print("!!!", file=sys.stderr)
-
-    lines = msg.splitlines()
-    for i, line in enumerate(lines):
-        if i == 0:
-            line = f"WARNING: {line}"
-        print(f"!!! {line}", file=sys.stderr)
-
-    print("!!!\n", file=sys.stderr)
-    sys.stderr.flush()
-
-
 def make_fail_app(msg: str | bytes) -> Callable[..., Any]:
     msg = to_bytestring(msg)
 

plain-0.78.0/plain/server/workers/__init__.py

@@ -0,0 +1,6 @@
+#
+#
+# This file is part of gunicorn released under the MIT license.
+# See the LICENSE for more information.
+#
+# Vendored and modified for Plain.