plain 0.38.0__py3-none-any.whl → 0.39.1__py3-none-any.whl

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/chores/__init__.py

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

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

@@ -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.38.0.dist-info → plain-0.39.1.dist-info}/RECORD

@@ -14,10 +14,14 @@ plain/assets/finders.py,sha256=2k8QZAbfUbc1LykxbzdazTSB6xNxJZnsZaGhWbSFZZs,1452
 plain/assets/fingerprints.py,sha256=2LPHLUkoITMseLDmemTpBtMRDWCR2H5GAHjC6AN4gz0,1367
 plain/assets/urls.py,sha256=zQUA8bAlh9qVqskPJJrqWd9DjvetOi5jPSqy4vUX0J4,1161
 plain/assets/views.py,sha256=T_0Qh6v9qBerEBYbhToigwOzsij-x1z_R-1zETQcIh0,9447
+plain/chores/README.md,sha256=Da8Nw8ZF7PlAE_iVb0AqJGbLOu0F6HC0cj1K451KBak,1946
+plain/chores/__init__.py,sha256=r9TXtQCH-VbvfnIJ5F8FxgQC35GRWFOfmMZN3q9niLg,67
+plain/chores/registry.py,sha256=V3WjuekRI22LFvJbqSkUXQtiOtuE2ZK8gKV1TRvxRUI,1866
 plain/cli/README.md,sha256=ompPcgzY2Fdpm579ITmCpFIaZIsiXYbfD61mqkq312M,1860
 plain/cli/__init__.py,sha256=6w9T7K2WrPwh6DcaMb2oNt_CWU6Bc57nUTO2Bt1p38Y,63
 plain/cli/build.py,sha256=dKUYBNegvb6QNckR7XZ7CJJtINwZcmDvbUdv2dWwjf8,3226
-plain/cli/core.py,sha256=N7xUO8Ox2xz8wJyWZ0fSyCfqVFmKz9czH9gulRyQuM4,2809
+plain/cli/chores.py,sha256=xXSSFvr8T5jWfLWqe6E8YVMw1BkQxyOHHVuY0x9RH0A,2412
+plain/cli/core.py,sha256=sy5otyN5jNOHkcy1EXISB7iMr1itp0rzmBSnEXYGe2k,2866
 plain/cli/docs.py,sha256=2CpTv5k-TNWf593tPiglvUVXWBGdfPmbGf8vl5AfJwU,8995
 plain/cli/formatting.py,sha256=1hZH13y1qwHcU2K2_Na388nw9uvoeQH8LrWL-O9h8Yc,2207
 plain/cli/preflight.py,sha256=NKyYjcoDjigzfJIDhf7A7degYadaUI05Bw7U9OQ73vs,4170
@@ -134,7 +138,7 @@ plain/utils/timezone.py,sha256=6u0sE-9RVp0_OCe0Y1KiYYQoq5THWLokZFQYY8jf78g,6221
 plain/utils/tree.py,sha256=wdWzmfsgc26YDF2wxhAY3yVxXTixQYqYDKE9mL3L3ZY,4383
 plain/views/README.md,sha256=_jR_8_eccE1Qwc9sbUhD_hpZGGf0r-HY4W-al6kqtGs,6762
 plain/views/__init__.py,sha256=a-N1nkklVohJTtz0yD1MMaS0g66HviEjsKydNVVjvVc,392
-plain/views/base.py,sha256=bFSSZABqANn3DPrUa97p6XxzXh0My-FSJSWjvLoFljQ,3240
+plain/views/base.py,sha256=bF_yBHrBfOdq3OcA_CTGCs7hNI1O6LpDVLM2Pkzyfjs,3062
 plain/views/csrf.py,sha256=7q6l5xzLWhRnMY64aNj0hR6G-3pxI2yhRwG6k_5j00E,144
 plain/views/errors.py,sha256=jbNCJIzowwCsEvqyJ3opMeZpPDqTyhtrbqb0VnAm2HE,1263
 plain/views/exceptions.py,sha256=b4euI49ZUKS9O8AGAcFfiDpstzkRAuuj_uYQXzWNHME,138
@@ -142,8 +146,8 @@ plain/views/forms.py,sha256=ESZOXuo6IeYixp1RZvPb94KplkowRiwO2eGJCM6zJI0,2400
 plain/views/objects.py,sha256=GGbcfg_9fPZ-PiaBwIHG2e__8GfWDR7JQtQ15wTyiHg,5970
 plain/views/redirect.py,sha256=vMXx8430FtyKcT0V0gyY92SkLtyULBX52KhX4eu4gEA,1985
 plain/views/templates.py,sha256=kMcHKkKNvucF91SFGkaq-ugjrCwn4zJBpFV1JkwA544,2027
-plain-0.38.0.dist-info/METADATA,sha256=UXCQr1j9RRhGH4fDnS65T0j-DSZIGHOVjt8XeWq5GT0,4297
-plain-0.38.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-plain-0.38.0.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
-plain-0.38.0.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
-plain-0.38.0.dist-info/RECORD,,
+plain-0.39.1.dist-info/METADATA,sha256=e8tEYf656PoEDJU624eCgDYMAT9_Jc1ewukJa45-_7g,4297
+plain-0.39.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+plain-0.39.1.dist-info/entry_points.txt,sha256=1Ys2lsSeMepD1vz8RSrJopna0RQfUd951vYvCRsvl6A,45
+plain-0.39.1.dist-info/licenses/LICENSE,sha256=m0D5O7QoH9l5Vz_rrX_9r-C8d9UNr_ciK6Qwac7o6yo,3175
+plain-0.39.1.dist-info/RECORD,,