plain 0.38.0__tar.gz → 0.39.1__tar.gz

{plain-0.38.0 → plain-0.39.1}/PKG-INFO

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

plain-0.39.1/plain/chores/README.md

@@ -0,0 +1,64 @@
+# Chores
+
+**Routine maintenance tasks.**
+
+Chores are registered functions that can be run at any time to keep an app in a desirable state.
+
+![](https://assets.plainframework.com/docs/plain-chores-run.png)
+
+A good example is the clearing of expired sessions in [`plain.sessions`](/plain-sessions/plain/sessions/chores.py) — since the sessions are stored in the database, occasionally you will want to delete any sessions that are expired and no longer in use.
+
+```python
+# plain/sessions/chores.py
+from plain.chores import register_chore
+from plain.utils import timezone
+
+from .models import Session
+
+
+@register_chore("sessions")
+def clear_expired():
+    """
+    Delete sessions that have expired.
+    """
+    result = Session.objects.filter(expires_at__lt=timezone.now()).delete()
+    return f"{result[0]} expired sessions deleted"
+```
+
+## Running chores
+
+The `plain chores run` command will execute all registered chores. When and how to run this is up to the user, but running them hourly is a safe assumption in most cases (assuming you have any chores — `plain chores list`).
+
+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 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.
+
+```python
+# app/chores.py
+from plain.chores import register_chore
+
+
+@register_chore("app")
+def chore_name():
+    """
+    A chore description can go here
+    """
+    # Do a thing!
+    return "We did it!"
+```
+
+A good chore is:
+
+- Fast
+- Idempotent
+- Recurring
+- Stateless
+
+If chores are written in `app/chores.py` or `{pkg}/chores.py`, then they will be imported automatically and registered.

plain-0.39.1/plain/chores/__init__.py

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

plain-0.39.1/plain/chores/registry.py

@@ -0,0 +1,79 @@
+from importlib import import_module
+from importlib.util import find_spec
+
+from plain.packages import packages_registry
+
+
+class Chore:
+    def __init__(self, *, group, func):
+        self.group = group
+        self.func = func
+        self.name = f"{group}.{func.__name__}"
+        self.description = func.__doc__.strip() if func.__doc__ else ""
+
+    def __str__(self):
+        return self.name
+
+    def run(self):
+        """
+        Run the chore.
+        """
+        return self.func()
+
+
+class ChoresRegistry:
+    def __init__(self):
+        self._chores = {}
+
+    def register_chore(self, chore):
+        """
+        Register a chore with the specified name.
+        """
+        self._chores[chore.func] = chore
+
+    def import_modules(self):
+        """
+        Import modules from installed packages and app to trigger registration.
+        """
+        # Import from installed packages
+        for package_config in packages_registry.get_package_configs():
+            import_name = f"{package_config.name}.chores"
+            try:
+                import_module(import_name)
+            except ModuleNotFoundError:
+                pass
+
+        # Import from app
+        import_name = "app.chores"
+        if find_spec(import_name):
+            try:
+                import_module(import_name)
+            except ModuleNotFoundError:
+                pass
+
+    def get_chores(self):
+        """
+        Get all registered chores.
+        """
+        return list(self._chores.values())
+
+
+chores_registry = ChoresRegistry()
+
+
+def register_chore(group):
+    """
+    Register a chore with a given group.
+
+    Usage:
+        @register_chore("clear_expired")
+        def clear_expired():
+            pass
+    """
+
+    def wrapper(func):
+        chore = Chore(group=group, func=func)
+        chores_registry.register_chore(chore)
+        return func
+
+    return wrapper

plain-0.39.1/plain/cli/chores.py

@@ -0,0 +1,91 @@
+import logging
+import sys
+
+import click
+
+logger = logging.getLogger("plain.chores")
+
+
+@click.group()
+def chores():
+    """Routine maintenance tasks"""
+    pass
+
+
+@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, name):
+    """
+    List all registered chores.
+    """
+    from plain.chores.registry import chores_registry
+
+    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)
+        ]
+    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}")
+        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, name, dry_run):
+    """
+    Run the specified chores.
+    """
+    from plain.chores.registry import chores_registry
+
+    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)
+        ]
+    else:
+        chores = chores_registry.get_chores()
+
+    chores_failed = []
+
+    for chore in chores:
+        click.echo(f"{chore.name}:", nl=False)
+        if dry_run:
+            click.echo(" (dry run)", fg="yellow")
+        else:
+            try:
+                result = chore.run()
+            except Exception:
+                click.secho(" Failed", fg="red")
+                chores_failed.append(chore)
+                logger.exception(f"Error running chore {chore.name}")
+                continue
+
+            if result is None:
+                click.secho(" Done", fg="green")
+            else:
+                click.secho(f" {result}", fg="green")
+
+    if chores_failed:
+        sys.exit(1)

{plain-0.38.0 → plain-0.39.1}/plain/cli/core.py

@@ -7,6 +7,7 @@ import plain.runtime
 from plain.exceptions import ImproperlyConfigured
 
 from .build import build
+from .chores import chores
 from .docs import docs
 from .formatting import PlainContext
 from .preflight import preflight_checks
@@ -26,6 +27,7 @@ def plain_cli():
 plain_cli.add_command(docs)
 plain_cli.add_command(preflight_checks)
 plain_cli.add_command(create)
+plain_cli.add_command(chores)
 plain_cli.add_command(build)
 plain_cli.add_command(utils)
 plain_cli.add_command(urls)

{plain-0.38.0 → plain-0.39.1}/plain/views/base.py

@@ -1,4 +1,5 @@
 import logging
+from http import HTTPMethod
 
 from plain.http import (
     HttpRequest,
@@ -100,14 +101,4 @@ class View:
         return response
 
     def _allowed_methods(self) -> list[str]:
-        known_http_methods = [
-            "get",
-            "post",
-            "put",
-            "patch",
-            "delete",
-            "head",
-            "options",
-            "trace",
-        ]
-        return [m.upper() for m in known_http_methods if hasattr(self, m)]
+        return [m.upper() for m in HTTPMethod if hasattr(self, m.lower())]

{plain-0.38.0 → plain-0.39.1}/pyproject.toml

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