plain 0.37.0__tar.gz → 0.39.0__tar.gz

{plain-0.37.0 → plain-0.39.0}/.gitignore

@@ -11,3 +11,5 @@ plain*/tests/.plain
 
 # Ottobot
 .aider*
+
+/llms-full.txt

{plain-0.37.0 → plain-0.39.0}/PKG-INFO

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

{plain-0.37.0 → plain-0.39.0}/plain/assets/README.md

@@ -44,6 +44,22 @@ By default, this [generates "fingerprinted" and compressed versions of the asset
 
 The purpose of fingerprinting the assets is to allow the browser to cache them indefinitely. When the content of the file changes, the fingerprint will change, and the browser will use the newer file. This cuts down on the number of requests that your app has to handle related to assets.
 
+## Using `AssetView` directly
+
+In some situations you may want to use the `AssetView` at a custom URL, for example to serve a `favicon.ico`. You can do this quickly by using the `AssetView.as_view()` class method.
+
+```python
+from plain.assets.views import AssetView
+from plain.urls import path, Router
+
+
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        path("favicon.ico", AssetView.as_view(asset_path="favicon.ico")),
+    ]
+```
+
 ## FAQs
 
 ### How do you reference assets in Python code?

plain-0.39.0/plain/chores/__init__.py

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

plain-0.39.0/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.0/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.37.0 → plain-0.39.0}/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.39.0/plain/cli/docs.py

@@ -0,0 +1,253 @@
+import ast
+import importlib.util
+import sys
+from pathlib import Path
+
+import click
+
+from plain.packages import packages_registry
+
+
+@click.command()
+@click.option("--llm", "llm", is_flag=True)
+@click.option("--open")
+@click.argument("module", default="")
+def docs(module, llm, open):
+    if not module and not llm:
+        click.secho("You must specify a module or use --llm", fg="red")
+        sys.exit(1)
+
+    if llm:
+        paths = [Path(__file__).parent.parent]
+
+        for package_config in packages_registry.get_package_configs():
+            if package_config.name.startswith("app."):
+                # Ignore app packages for now
+                continue
+
+            paths.append(Path(package_config.path))
+
+        source_docs = LLMDocs(paths)
+        source_docs.load()
+        source_docs.print()
+
+        click.secho(
+            "That's everything! Copy this into your AI tool of choice.",
+            err=True,
+            fg="green",
+        )
+
+        return
+
+    if module:
+        # Automatically prefix if we need to
+        if not module.startswith("plain"):
+            module = f"plain.{module}"
+
+        # Get the README.md file for the module
+        spec = importlib.util.find_spec(module)
+        if not spec:
+            click.secho(f"Module {module} not found", fg="red")
+            sys.exit(1)
+
+        module_path = Path(spec.origin).parent
+        readme_path = module_path / "README.md"
+        if not readme_path.exists():
+            click.secho(f"README.md not found for {module}", fg="red")
+            sys.exit(1)
+
+        if open:
+            click.launch(str(readme_path))
+        else:
+
+            def _iterate_markdown(content):
+                """
+                Iterator that does basic markdown for a Click pager.
+
+                Headings are yellow and bright, code blocks are indented.
+                """
+
+                in_code_block = False
+                for line in content.splitlines():
+                    if line.startswith("```"):
+                        in_code_block = not in_code_block
+
+                    if in_code_block:
+                        yield click.style(line, dim=True)
+                    elif line.startswith("# "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("## "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("#### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("##### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("###### "):
+                        yield click.style(line, fg="yellow", bold=True)
+                    elif line.startswith("**") and line.endswith("**"):
+                        yield click.style(line, bold=True)
+                    elif line.startswith("> "):
+                        yield click.style(line, italic=True)
+                    else:
+                        yield line
+
+                    yield "\n"
+
+            click.echo_via_pager(_iterate_markdown(readme_path.read_text()))
+
+
+class LLMDocs:
+    preamble = (
+        "Below is all of the documentation and abbreviated source code for the Plain web framework. "
+        "Your job is to read and understand it, and then act as the Plain Framework Assistant and "
+        "help the developer accomplish whatever they want to do next."
+        "\n\n---\n\n"
+    )
+
+    def __init__(self, paths):
+        self.paths = paths
+
+    def load(self):
+        self.docs = set()
+        self.sources = set()
+
+        for path in self.paths:
+            if path.is_dir():
+                self.docs.update(path.glob("**/*.md"))
+                self.sources.update(path.glob("**/*.py"))
+            elif path.suffix == ".py":
+                self.sources.add(path)
+            elif path.suffix == ".md":
+                self.docs.add(path)
+
+        # Exclude "migrations" code from plain apps, except for plain/models/migrations
+        self.docs = {
+            doc
+            for doc in self.docs
+            if not (
+                "/migrations/" in str(doc)
+                and "/plain/models/migrations/" not in str(doc)
+            )
+        }
+        self.sources = {
+            source
+            for source in self.sources
+            if not (
+                "/migrations/" in str(source)
+                and "/plain/models/migrations/" not in str(source)
+            )
+        }
+
+        self.docs = sorted(self.docs)
+        self.sources = sorted(self.sources)
+
+    def display_path(self, path):
+        if "plain" in path.parts:
+            root_index = path.parts.index("plain")
+        elif "plainx" in path.parts:
+            root_index = path.parts.index("plainx")
+        else:
+            raise ValueError("Path does not contain 'plain' or 'plainx'")
+
+        plain_root = Path(*path.parts[: root_index + 1])
+        return path.relative_to(plain_root.parent)
+
+    def print(self, relative_to=None):
+        click.secho(self.preamble, fg="yellow")
+
+        for doc in self.docs:
+            if relative_to:
+                display_path = doc.relative_to(relative_to)
+            else:
+                display_path = self.display_path(doc)
+            click.secho(f"<Docs: {display_path}>", fg="yellow")
+            click.echo(doc.read_text())
+            click.secho(f"</Docs: {display_path}>", fg="yellow")
+            click.echo()
+
+        for source in self.sources:
+            if symbolicated := self.symbolicate(source):
+                if relative_to:
+                    display_path = source.relative_to(relative_to)
+                else:
+                    display_path = self.display_path(source)
+                click.secho(f"<Source: {display_path}>", fg="yellow")
+                click.echo(symbolicated)
+                click.secho(f"</Source: {display_path}>", fg="yellow")
+                click.echo()
+
+    @staticmethod
+    def symbolicate(file_path: Path):
+        if "internal" in str(file_path).split("/"):
+            return ""
+
+        source = file_path.read_text()
+
+        parsed = ast.parse(source)
+
+        def should_skip(node):
+            if isinstance(node, ast.ClassDef | ast.FunctionDef):
+                if any(
+                    isinstance(d, ast.Name) and d.id == "internalcode"
+                    for d in node.decorator_list
+                ):
+                    return True
+                if node.name.startswith("_"):  # and not node.name.endswith("__"):
+                    return True
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if (
+                        isinstance(target, ast.Name) and target.id.startswith("_")
+                        # and not target.id.endswith("__")
+                    ):
+                        return True
+            return False
+
+        def process_node(node, indent=0):
+            lines = []
+            prefix = "    " * indent
+
+            if should_skip(node):
+                return []
+
+            if isinstance(node, ast.ClassDef):
+                decorators = [
+                    f"{prefix}@{ast.unparse(d)}"
+                    for d in node.decorator_list
+                    if not (isinstance(d, ast.Name) and d.id == "internalcode")
+                ]
+                lines.extend(decorators)
+                bases = [ast.unparse(base) for base in node.bases]
+                lines.append(f"{prefix}class {node.name}({', '.join(bases)})")
+                # if ast.get_docstring(node):
+                #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
+                for child in node.body:
+                    child_lines = process_node(child, indent + 1)
+                    if child_lines:
+                        lines.extend(child_lines)
+                # if not has_body:
+                #     lines.append(f"{prefix}    pass")
+
+            elif isinstance(node, ast.FunctionDef):
+                decorators = [f"{prefix}@{ast.unparse(d)}" for d in node.decorator_list]
+                lines.extend(decorators)
+                args = ast.unparse(node.args)
+                lines.append(f"{prefix}def {node.name}({args})")
+                # if ast.get_docstring(node):
+                #     lines.append(f'{prefix}    """{ast.get_docstring(node)}"""')
+                # lines.append(f"{prefix}    pass")
+
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name):
+                        lines.append(f"{prefix}{target.id} = {ast.unparse(node.value)}")
+
+            return lines
+
+        symbolicated_lines = []
+        for node in parsed.body:
+            symbolicated_lines.extend(process_node(node))
+
+        return "\n".join(symbolicated_lines)

{plain-0.37.0 → plain-0.39.0}/plain/csrf/README.md

@@ -2,13 +2,13 @@
 
 **Cross-Site Request Forgery (CSRF) protection.**
 
-Plain protects against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) through a [middleware](middleware.py) that compares the generated `csrftoken` cookie with the CSRF token from the request (either `_csrftoken` in form data or the `X-CSRFToken` header).
+Plain protects against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) through a [middleware](middleware.py) that compares the generated `csrftoken` cookie with the CSRF token from the request (either `_csrftoken` in form data or the `CSRF-Token` header).
 
 ## Usage
 
 The `CsrfViewMiddleware` is [automatically installed](../internal/handlers/base.py#BUILTIN_BEFORE_MIDDLEWARE), so you don't need to add it to your `settings.MIDDLEWARE`.
 
-When you use HTML forms, you should include the CSRF token in the form data:
+When you use HTML forms, you should include the CSRF token in the form data via a hidden input:
 
 ```html
 <form method="post">

plain-0.39.0/plain/forms/exceptions.py

@@ -0,0 +1,13 @@
+from plain.exceptions import ValidationError
+
+
+class FormFieldMissingError(Exception):
+    def __init__(self, field_name):
+        self.field_name = field_name
+        self.message = f'The "{self.field_name}" field is missing from the form data.'
+
+
+__all__ = [
+    "ValidationError",
+    "FormFieldMissingError",
+]

{plain-0.37.0 → plain-0.39.0}/plain/forms/fields.py

@@ -67,23 +67,16 @@ class Field:
         initial=None,
         error_messages=None,
         validators=(),
-        disabled=False,
     ):
         # required -- Boolean that specifies whether the field is required.
         #             True by default.
-        # widget -- A Widget class, or instance of a Widget class, that should
-        #           be used for this Field when displaying it. Each Field has a
-        #           default Widget that it'll use if you don't specify this. In
-        #           most cases, the default widget is TextInput.
         # initial -- A value to use in this Field's initial display. This value
         #            is *not* used as a fallback if data isn't given.
         # error_messages -- An optional dictionary to override the default
         #                   messages that the field will raise.
         # validators -- List of additional validators to use
-        # disabled -- Boolean that specifies whether the field is disabled, that
-        #             is its widget is shown in the form but not editable.
-        self.required, self.initial = required, initial
-        self.disabled = disabled
+        self.required = required
+        self.initial = initial
 
         messages = {}
         for c in reversed(self.__class__.__mro__):
@@ -136,16 +129,10 @@ class Field:
         For most fields, this will simply be data; FileFields need to handle it
         a bit differently.
         """
-        if self.disabled:
-            return initial
         return data
 
     def has_changed(self, initial, data):
         """Return True if data differs from initial."""
-        # Always return False if the field is disabled since self.bound_data
-        # always uses the initial value in this case.
-        if self.disabled:
-            return False
         try:
             data = self.to_python(data)
             if hasattr(self, "_coerce"):
@@ -174,12 +161,17 @@ class Field:
         return result
 
     def value_from_form_data(self, data, files, html_name):
+        # By default, all fields are expected to be present in HTML form data.
         try:
             return data[html_name]
         except KeyError as e:
-            raise FormFieldMissingError(
-                f'The "{html_name}" field is missing from the form data.'
-            ) from e
+            raise FormFieldMissingError(html_name) from e
+
+    def value_from_json_data(self, data, files, html_name):
+        if self.required and html_name not in data:
+            raise FormFieldMissingError(html_name)
+
+        return data.get(html_name, None)
 
 
 class CharField(Field):
@@ -592,11 +584,14 @@ class FileField(Field):
         return initial
 
     def has_changed(self, initial, data):
-        return not self.disabled and data is not None
+        return data is not None
 
     def value_from_form_data(self, data, files, html_name):
         return files.get(html_name)
 
+    def value_from_json_data(self, data, files, html_name):
+        return files.get(html_name)
+
 
 class ImageField(FileField):
     default_validators = [validators.validate_image_file_extension]
@@ -706,8 +701,6 @@ class BooleanField(Field):
             raise ValidationError(self.error_messages["required"], code="required")
 
     def has_changed(self, initial, data):
-        if self.disabled:
-            return False
         # Sometimes data or initial may be a string equivalent of a boolean
         # so we should run it through to_python first to get a boolean value
         return self.to_python(initial) != self.to_python(data)
@@ -729,6 +722,13 @@ class BooleanField(Field):
             "on": True,
         }.get(value)
 
+    def value_from_json_data(self, data, files, html_name):
+        # Boolean fields must be present in the JSON data
+        try:
+            return data[html_name]
+        except KeyError as e:
+            raise FormFieldMissingError(html_name) from e
+
 
 class NullBooleanField(BooleanField):
     """
@@ -883,8 +883,6 @@ class MultipleChoiceField(ChoiceField):
                 )
 
     def has_changed(self, initial, data):
-        if self.disabled:
-            return False
         if initial is None:
             initial = []
         if data is None:
@@ -944,8 +942,6 @@ class JSONField(CharField):
         super().__init__(**kwargs)
 
     def to_python(self, value):
-        if self.disabled:
-            return value
         if value in self.empty_values:
             return None
         elif isinstance(value, list | dict | int | float | JSONString):
@@ -964,8 +960,6 @@ class JSONField(CharField):
             return converted
 
     def bound_data(self, data, initial):
-        if self.disabled:
-            return initial
         if data is None:
             return None
         try: