plain 0.77.0__py3-none-any.whl → 0.78.1__py3-none-any.whl

plain/CHANGELOG.md

@@ -1,5 +1,48 @@
 # plain changelog
 
+## [0.78.1](https://github.com/dropseed/plain/releases/plain@0.78.1) (2025-10-17)
+
+### What's changed
+
+- Fixed job worker logging by using `getLogger` instead of directly instantiating `Logger` for the plain logger ([dd675666b9](https://github.com/dropseed/plain/commit/dd675666b9))
+
+### Upgrade instructions
+
+- No changes required
+
+## [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/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/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

plain/chores/registry.py

@@ -1,37 +1,23 @@
 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()
+from .core import Chore
 
 
 class ChoresRegistry:
-    def __init__(self):
-        self._chores: dict[FunctionType, Chore] = {}
+    def __init__(self) -> None:
+        self._chores: dict[str, type[Chore]] = {}
 
-    def register_chore(self, chore: Chore) -> None:
+    def register_chore(self, chore_class: type[Chore]) -> None:
         """
-        Register a chore with the specified name.
+        Register a chore class.
+
+        Args:
+            chore_class: A Chore subclass to register
         """
-        self._chores[chore.func] = chore
+        name = f"{chore_class.__module__}.{chore_class.__qualname__}"
+        self._chores[name] = chore_class
 
     def import_modules(self) -> None:
         """
@@ -39,9 +25,9 @@ class ChoresRegistry:
         """
         packages_registry.autodiscover_modules("chores", include_app=True)
 
-    def get_chores(self) -> list[Chore]:
+    def get_chores(self) -> list[type[Chore]]:
         """
-        Get all registered chores.
+        Get all registered chore classes.
         """
         return list(self._chores.values())
 
@@ -49,19 +35,15 @@ class ChoresRegistry:
 chores_registry = ChoresRegistry()
 
 
-def register_chore(group: str) -> Any:
+def register_chore(cls: type[Chore]) -> type[Chore]:
     """
-    Register a chore with a given group.
+    Decorator to register a chore class.
 
     Usage:
-        @register_chore("clear_expired")
-        def clear_expired():
-            pass
+        @register_chore
+        class ClearExpired(Chore):
+            def run(self):
+                return "Done!"
     """
-
-    def wrapper(func: FunctionType) -> FunctionType:
-        chore = Chore(group=group, func=func)
-        chores_registry.register_chore(chore)
-        return func
-
-    return wrapper
+    chores_registry.register_chore(cls)
+    return cls

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/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/logs/configure.py

@@ -7,13 +7,12 @@ def configure_logging(
     *, plain_log_level: int | str, app_log_level: int | str, app_log_format: str
 ) -> None:
     # Create and configure the plain logger (uses standard Logger, not AppLogger)
-    plain_logger = logging.Logger("plain")
+    plain_logger = logging.getLogger("plain")
     plain_logger.setLevel(plain_log_level)
     plain_handler = logging.StreamHandler()
     plain_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
     plain_logger.addHandler(plain_handler)
     plain_logger.propagate = False
-    logging.root.manager.loggerDict["plain"] = plain_logger
 
     # Configure the existing app_logger
     from .loggers import app_logger

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.dist-info → plain-0.78.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.77.0
+Version: 0.78.1
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE

{plain-0.77.0.dist-info → plain-0.78.1.dist-info}/RECORD

@@ -1,5 +1,5 @@
 plain/AGENTS.md,sha256=As6EFSWWHJ9lYIxb2LMRqNRteH45SRs7a_VFslzF53M,1046
-plain/CHANGELOG.md,sha256=A05-ohzcEeeRrrxOXNt1FLH8F88kgS-_IjmwsHR1g9Y,26688
+plain/CHANGELOG.md,sha256=KM-gzR9XLYBO7517RspHvAJ4TP3izeeIg5N6KDiAoEU,28258
 plain/README.md,sha256=VvzhXNvf4I6ddmjBP9AExxxFXxs7RwyoxdgFm-W5dsg,4072
 plain/__main__.py,sha256=GK39854Lc_LO_JP8DzY9Y2MIQ4cQEl7SXFJy244-lC8,110
 plain/debug.py,sha256=C2OnFHtRGMrpCiHSt-P2r58JypgQZ62qzDBpV4mhtFM,855
@@ -16,14 +16,15 @@ plain/assets/finders.py,sha256=j9sZ2LAJp55hdJ_e1lFevzwicNEMUtv6rLtQgiIkDgY,1589
 plain/assets/fingerprints.py,sha256=UPJwLmzzqXBp7FPk9XnMkcTps2UW9SnTAv0hGieUnMo,1458
 plain/assets/urls.py,sha256=Qe0ctXYAQjAlLIKuX6JeLVBOFqzJxggR0RSGkRXmX78,1173
 plain/assets/views.py,sha256=Zs_wyguh-WljOgW3DiPfpspTVOKC6z3bRSu01-SDcoU,9877
-plain/chores/README.md,sha256=ashFQ4kc1h81DqFmOXiGcrmzvJQQMg4ZWdUIFDcJah0,2048
-plain/chores/__init__.py,sha256=r9TXtQCH-VbvfnIJ5F8FxgQC35GRWFOfmMZN3q9niLg,67
-plain/chores/registry.py,sha256=kKhN7z0XcgGCMnpx9bVWI1klUUl-yAEfcDaLnsSYs6c,1589
-plain/cli/README.md,sha256=5C7vsH0ISxu7q5H6buC25MBOILkI_rzdySitswpQgJw,1032
+plain/chores/README.md,sha256=7Dv5MCyqPaohQxAk74HRzKiTvt_yR-IOhbu7R5bdz6M,2437
+plain/chores/__init__.py,sha256=wEdt-oAKS1kz7Ln-puhcCt8XGNdfCP4S3wHESaPU8nI,100
+plain/chores/core.py,sha256=BxsCSJDQvMjYsAH4QhEoW9ZUEAUIwJgTYyHovPGSLjk,578
+plain/chores/registry.py,sha256=IRpx3f6Z1qlqcEpHTe6O6JocNmaplLu7BVOqGrafSXU,1221
+plain/cli/README.md,sha256=Wn6o0fVL-SRMztTTHO71P4QzOvntgO-MqjbRrsk3WAw,1661
 plain/cli/__init__.py,sha256=6w9T7K2WrPwh6DcaMb2oNt_CWU6Bc57nUTO2Bt1p38Y,63
 plain/cli/build.py,sha256=Jg5LMbmXHhCXZIYj_Gcjou3yGiEWw8wpbOGGsdk-wZw,3203
 plain/cli/changelog.py,sha256=yCY887PT_D2viLz9f-uyu07Znqiv2-NEyCBqquNIukw,3590
-plain/cli/chores.py,sha256=aaDVTpwBEmyQ4r_YeZ6U7Fw9UOIq5d7okwpq9HdfRbA,2521
+plain/cli/chores.py,sha256=FzQat9ofEZTlCiszGvV3deJwx8G0c-fBhn1mI560Iec,2568
 plain/cli/core.py,sha256=nL-a7zPtEBIa_XV-VOd9lqEUqmQAhlzsdHNwEmxNkWE,4285
 plain/cli/docs.py,sha256=PU3v7Z7qgYFG-bClpuDg4JeWwC8uvLYX3ovkQDMseVs,1146
 plain/cli/formatting.py,sha256=e1doTFalAM11bD_Cvqeu6sTap81JrQcB-4kMjZzAHmY,2737
@@ -83,7 +84,7 @@ plain/internal/middleware/https.py,sha256=mB2fxOisij3HFL-N99Pa3gd3fI7ca49L4fxoQ9
 plain/internal/middleware/slash.py,sha256=VwiMZ__L8gMT0zrpwCAoLEJy2-GhR8Czc6kQnmu8K3w,3195
 plain/logs/README.md,sha256=rzOHfngjizLgXL21g0svC1Cdya2s_gBA_E-IljtHpy8,4069
 plain/logs/__init__.py,sha256=gFVMcNn5D6z0JrvUJgGsOeYj1NKNtEXhw0MvPDtkN6w,58
-plain/logs/configure.py,sha256=JWSTkQ1i1yu4sB-cXzxJwx2Pyax7sUEoOsTN_mj4te0,1363
+plain/logs/configure.py,sha256=z2c_wBHPVRSSkKVBUEwYCUvQi-Kf449n-SysC65tjeo,1306
 plain/logs/debug.py,sha256=x2M4UcVexnn_5G0WCJd5iX6RFAGqEiRjE81dpMOqBBU,1336
 plain/logs/formatters.py,sha256=1yNeA7RGa9Ao1TZRu20idQtPOIg43PZogFR-B5n7VnA,2503
 plain/logs/loggers.py,sha256=FcvfVHbSLarY5IVsEoQcvNxeJkkoBz69a2a39rnyQ-4,5249
@@ -181,15 +182,15 @@ plain/utils/timezone.py,sha256=M_I5yvs9NsHbtNBPJgHErvWw9vatzx4M96tRQs5gS3g,6823
 plain/utils/tree.py,sha256=rj_JpZ2kVD3UExWoKnsRdVCoRjvzkuVOONcHzREjSyw,4766
 plain/views/README.md,sha256=6mcoSQp60n8qgoIMNDQr29WThpi-NCj8EMqxPNwWpiE,7189
 plain/views/__init__.py,sha256=a-N1nkklVohJTtz0yD1MMaS0g66HviEjsKydNVVjvVc,392
-plain/views/base.py,sha256=fk9zAY5BMVBeM45dWL7A9BMTdUi6eTFMeVDd5kBVdv8,4478
+plain/views/base.py,sha256=yWh6S68PsYcH1dvRdibQIanBYkjo2iJ8IAbR2PTWQrk,4419
 plain/views/errors.py,sha256=tHD7MNnZcMyiQ46RMAnX1Ne3Zbbkr1zAiVfJyaaLtSQ,1447
 plain/views/exceptions.py,sha256=-YKH1Jd9Zm_yXiz797PVjJB6VWaPCTXClHIUkG2fq78,198
 plain/views/forms.py,sha256=ESZOXuo6IeYixp1RZvPb94KplkowRiwO2eGJCM6zJI0,2400
 plain/views/objects.py,sha256=5y0PoPPo07dQTTcJ_9kZcx0iI1O7regsooAIK4VqXQ0,5579
 plain/views/redirect.py,sha256=mIpSAFcaEyeLDyv4Fr6g_ektduG4Wfa6s6L-rkdazmM,2154
 plain/views/templates.py,sha256=9LgDMCv4C7JzLiyw8jHF-i4350ukwgixC_9y4faEGu0,1885
-plain-0.77.0.dist-info/METADATA,sha256=EXhUsvn36qZfmmMwZ42LlEhEeKcH0k5YXo2WmoRCXss,4516
-plain-0.77.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain-0.77.0.dist-info/entry_points.txt,sha256=wvMzY-iREvfqRgyLm77htPp4j_8CQslLoZA15_AnNo8,171
-plain-0.77.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.77.0.dist-info/RECORD,,
+plain-0.78.1.dist-info/METADATA,sha256=r3Abxj0lYj5yV39kplR3XPl6Dv-V2Xd5H_d5jWEToVw,4516
+plain-0.78.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain-0.78.1.dist-info/entry_points.txt,sha256=wvMzY-iREvfqRgyLm77htPp4j_8CQslLoZA15_AnNo8,171
+plain-0.78.1.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.78.1.dist-info/RECORD,,