plain 0.37.0__tar.gz → 0.38.0__tar.gz

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

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

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

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

{plain-0.37.0 → plain-0.38.0}/plain/forms/forms.py

@@ -3,6 +3,7 @@ Form classes
 """
 
 import copy
+import json
 
 from plain.exceptions import NON_FIELD_ERRORS
 from plain.utils.datastructures import MultiValueDict
@@ -57,15 +58,36 @@ class BaseForm:
 
     def __init__(
         self,
-        data=None,
-        files=None,
+        *,
+        request,
         auto_id="id_%s",
         prefix=None,
         initial=None,
     ):
-        self.is_bound = data is not None or files is not None
-        self.data = MultiValueDict() if data is None else data
-        self.files = MultiValueDict() if files is None else files
+        if request.method in ("POST", "PUT", "PATCH"):
+            if request.headers.get("Content-Type") == "application/json":
+                self.data = json.loads(request.body)
+                self.is_json_request = True
+            elif request.headers.get("Content-Type") in [
+                "application/x-www-form-urlencoded",
+                "multipart/form-data",
+            ]:
+                self.data = request.POST
+                self.is_json_request = False
+            else:
+                raise ValueError(
+                    "Unsupported Content-Type. Supported types are "
+                    "'application/json', 'application/x-www-form-urlencoded', "
+                    "and 'multipart/form-data'."
+                )
+        else:
+            self.data = MultiValueDict()
+            self.is_json_request = False
+
+        self.files = request.FILES
+
+        self.is_bound = bool(self.data or self.files)
+
         self._auto_id = auto_id
         if prefix is not None:
             self.prefix = prefix
@@ -224,16 +246,16 @@ class BaseForm:
             # Allow custom parsing from form data/files at the form level
             return getattr(self, f"parse_{html_name}")()
 
-        return field.value_from_form_data(self.data, self.files, html_name)
+        if self.is_json_request:
+            return field.value_from_json_data(self.data, self.files, html_name)
+        else:
+            return field.value_from_form_data(self.data, self.files, html_name)
 
     def _clean_fields(self):
         for name, bf in self._bound_items():
             field = bf.field
 
-            if field.disabled:
-                value = bf.initial
-            else:
-                value = self._field_data_value(bf.field, bf.html_name)
+            value = self._field_data_value(bf.field, bf.html_name)
 
             try:
                 if isinstance(field, FileField):

{plain-0.37.0 → plain-0.38.0}/plain/logs/README.md

@@ -2,7 +2,7 @@
 
 **Logging configuration and utilities.**
 
-In Python, configuring logging can be surprisingly complex. For most use cases, Plain provides a [default configuration](configure.py) that "just works".
+In Python, configuring logging can be surprisingly complex. For most use cases, Plain provides a [default configuration](./configure.py) that "just works".
 
 By default, both the `plain` and `app` loggers are set to the `INFO` level. You can quickly change this by using the `PLAIN_LOG_LEVEL` and `APP_LOG_LEVEL` environment variables.
 

{plain-0.37.0 → plain-0.38.0}/plain/views/README.md

@@ -12,7 +12,7 @@ from plain.views import View
 
 class ExampleView(View):
     def get(self):
-        return "Hello, world!"
+        return "<html><body>Hello, world!</body></html>"
 ```
 
 ## HTTP methods -> class methods
@@ -51,18 +51,23 @@ but you can override these too.
 
 ## Return types
 
-For simple plain text and JSON responses,
+For simple JSON responses, HTML, or status code responses,
 you don't need to instantiate a `Response` object.
 
 ```python
-class TextView(View):
+class JsonView(View):
     def get(self):
-        return "Hello, world!"
+        return {"message": "Hello, world!"}
 
 
-class JsonView(View):
+class HtmlView(View):
     def get(self):
-        return {"message": "Hello, world!"}
+        return "<html><body>Hello, world!</body></html>"
+
+
+class StatusCodeView(View):
+    def get(self):
+        return 204  # No content
 ```
 
 ## Template views
@@ -84,6 +89,19 @@ class ExampleView(TemplateView):
 
 The `TemplateView` is also the base class for _most_ of the other built-in view classes.
 
+Template views that don't need any custom context can use `TemplateView.as_view()` direcly in the URL route.
+
+```python
+from plain.views import TemplateView
+from plain.urls import path, Router
+
+
+class AppRouter(Router):
+    routes = [
+        path("/example/", TemplateView.as_view(template_name="example.html")),
+    ]
+```
+
 ## Form views
 
 Standard [forms](../forms) can be rendered and processed by a `FormView`.
@@ -255,7 +273,20 @@ class ExampleRedirectView(RedirectView):
     permanent = True
 ```
 
-## CSRF exemption
+Redirect views can also be used in the URL router.
+
+```python
+from plain.views import RedirectView
+from plain.urls import path, Router
+
+
+class AppRouter(Router):
+    routes = [
+        path("/old-location/", RedirectView.as_view(url="/new-location/", permanent=True)),
+    ]
+```
+
+## CSRF exempt views
 
 ```python
 from plain.views import View