plain 0.77.0__tar.gz → 0.78.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.77.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

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

@@ -1,5 +1,38 @@
 # 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

{plain-0.77.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.77.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.77.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.77.0 → plain-0.78.0}/plain/views/base.py

@@ -12,12 +12,12 @@ from opentelemetry.semconv._incubating.attributes.code_attributes import (
 )
 
 from plain.http import (
+    Http404,
     JsonResponse,
     Request,
     Response,
     ResponseBase,
     ResponseNotAllowed,
-    ResponseNotFound,
 )
 from plain.utils.decorators import classonlymethod
 
@@ -110,8 +110,7 @@ class View:
             return Response(status_code=value)
 
         if value is None:
-            # TODO raise 404 instead?
-            return ResponseNotFound()
+            raise Http404
 
         status_code = 200
 

{plain-0.77.0 → plain-0.78.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.77.0"
+version = "0.78.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"

plain-0.77.0/plain/chores/__init__.py

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

plain-0.77.0/plain/chores/registry.py

@@ -1,67 +0,0 @@
-from __future__ import annotations
-
-from types import FunctionType
-from typing import Any
-
-from plain.packages import packages_registry
-
-
-class Chore:
-    def __init__(self, *, group: str, func: FunctionType):
-        self.group = group
-        self.func = func
-        self.name = f"{group}.{func.__name__}"
-        self.description = func.__doc__.strip() if func.__doc__ else ""
-
-    def __str__(self) -> str:
-        return self.name
-
-    def run(self) -> Any:
-        """
-        Run the chore.
-        """
-        return self.func()
-
-
-class ChoresRegistry:
-    def __init__(self):
-        self._chores: dict[FunctionType, Chore] = {}
-
-    def register_chore(self, chore: Chore) -> None:
-        """
-        Register a chore with the specified name.
-        """
-        self._chores[chore.func] = chore
-
-    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[Chore]:
-        """
-        Get all registered chores.
-        """
-        return list(self._chores.values())
-
-
-chores_registry = ChoresRegistry()
-
-
-def register_chore(group: str) -> Any:
-    """
-    Register a chore with a given group.
-
-    Usage:
-        @register_chore("clear_expired")
-        def clear_expired():
-            pass
-    """
-
-    def wrapper(func: FunctionType) -> FunctionType:
-        chore = Chore(group=group, func=func)
-        chores_registry.register_chore(chore)
-        return func
-
-    return wrapper