plain 0.32.0__py3-none-any.whl → 0.33.0__py3-none-any.whl

plain/README.md

@@ -1 +1,66 @@
 # Plain
+
+**Plain is a web framework for building products with Python.**
+
+The core `plain` package provides the backbone of a Python web application (similar to [Flask](https://flask.palletsprojects.com/en/stable/)), while the additional first-party packages can power a more fully-featured database-backed app (similar to [Django](https://www.djangoproject.com/)).
+
+All Plain packages are designed to work together and use [PEP 420](https://peps.python.org/pep-0420/) to share the `plain` namespace.
+
+To quickly get started with Plain, visit [plainframework.com/start/](https://plainframework.com/start/).
+
+## Core Modules
+
+The `plain` package includes everything you need to start handling web requests with Python:
+
+- [assets](assets/README.md) - Serve static files and assets.
+- [cli](cli/README.md) - The `plain` CLI, powered by Click.
+- [csrf](csrf/README.md) - Cross-Site Request Forgery protection.
+- [forms](forms/README.md) - HTML forms and form validation.
+- [http](http/README.md) - HTTP request and response handling.
+- [logs](logs/README.md) - Logging configuration and utilities.
+- [preflight](preflight/README.md) - Preflight checks for your app.
+- [runtime](runtime/README.md) - Runtime settings and configuration.
+- [templates](templates/README.md) - Jinja2 templates and rendering.
+- [test](test/README.md) - Test utilities and fixtures.
+- [urls](urls/README.md) - URL routing and request dispatching.
+- [views](views/README.md) - Class-based views and request handlers.
+
+## Foundational Packages
+
+- [plain.models](/plain-models/README.md) - Define and interact with your database models.
+- [plain.cache](/plain-cache/README.md) - A database-driven general purpose cache.
+- [plain.mail](/plain-mail/README.md) - Send emails with SMTP or custom backends.
+- [plain.sessions](/plain-sessions/README.md) - User sessions and cookies.
+- [plain.worker](/plain-worker/README.md) - Backgrounb jobs stored in the database.
+- [plain.api](/plain-api/README.md) - Build APIs with Plain views.
+
+## Auth Packages
+
+- [plain.auth](/plain-auth/README.md) - User authentication and authorization.
+- [plain.oauth](/plain-oauth/README.md) - OAuth authentication and API access.
+- [plain.passwords](/plain-passwords/README.md) - Password-based login and registration.
+- [plain.loginlink](/plain-loginlink/README.md) - Login links for passwordless authentication.
+
+## Admin Packages
+
+- [plain.admin](/plain-admin/README.md) - An admin interface for back-office tasks.
+- [plain.flags](/plain-flags/README.md) - Feature flags.
+- [plain.support](/plain-support/README.md) - Customer support forms.
+- [plain.redirection](/plain-redirection/README.md) - Redirects managed in the database.
+- [plain.pageviews](/plain-pageviews/README.md) - Basic self-hosted page view tracking and reporting.
+
+## Dev Packages
+
+- [plain.dev](/plain-dev/README.md) - A single command for local development.
+- [plain.pytest](/plain-pytest/README.md) - Pytest fixtures and helpers.
+- [plain.code](/plain-code/README.md) - Code formatting and linting.
+- [plain.tunnel](/plain-tunnel/README.md) - Expose your local server to the internet.
+
+## Frontend Packages
+
+- [plain.tailwind](/plain-tailwind/README.md) - Tailwind CSS integration without Node.js.
+- [plain.htmx](/plain-htmx/README.md) - HTMX integrated into views and templates.
+- [plain.elements](/plain-elements/README.md) - Server-side HTML components.
+- [plain.pages](/plain-pages/README.md) - Static pages with Markdown and Jinja2.
+- [plain.esbuild](/plain-esbuild/README.md) - Simple JavaScript bundling and minification.
+- [plain.vendor](/plain-vendor/README.md) - Vendor JavaScript and CSS libraries.

plain/assets/README.md

@@ -1,38 +1,37 @@
 # Assets
 
-Serve static assets (CSS, JS, images, etc.) directly from your app.
-
+**Serve static assets (CSS, JS, images, etc.) directly or from a CDN.**
 
 ## Usage
 
 To serve assets, put them in `app/assets` or `app/{package}/assets`.
 
-Then include the `plain.assets.urls` in your `urls.py`:
+Then include the `AssetsRouter` in your own router, typically under the `assets/` path.
 
 ```python
 # app/urls.py
-from plain.urls import include, path
-import plain.assets.urls
+from plain.assets.urls import AssetsRouter
+from plain.urls import include, Router
 
 
-urlpatterns = [
-    path("assets/", include(plain.assets.urls)),
-    # ...
-]
+class AppRouter(Router):
+    namespace = ""
+    urls = [
+        include("assets/", AssetsRouter),
+        # your other routes here...
+    ]
 ```
 
-Now in your template you can use the `asset()` function to get the URL:
+Now in your template you can use the `asset()` function to get the URL, which will output the fully compiled and fingerprinted URL.
 
 ```html
 <link rel="stylesheet" href="{{ asset('css/style.css') }}">
 ```
 
-
 ## Local development
 
 When you're working with `settings.DEBUG = True`, the assets will be served directly from their original location. You don't need to run `plain build` or configure anything else.
 
-
 ## Production deployment
 
 In production, one of your deployment steps should be to compile the assets.
@@ -41,11 +40,10 @@ In production, one of your deployment steps should be to compile the assets.
 plain build
 ```
 
-By default, this generates "fingerprinted" and compressed versions of the assets, which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
+By default, this [generates "fingerprinted" and compressed versions of the assets](fingerprints.py#get_file_fingerprint), which are then served by your app. This means that a file like `main.css` will result in two new files, like `main.d0db67b.css` and `main.d0db67b.css.gz`.
 
 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.
 
-
 ## FAQs
 
 ### How do you reference assets in Python code?
@@ -67,10 +65,16 @@ mv .plain/assets/compiled /path/to/your/static
 
 ### How do I upload the assets to a CDN?
 
-The steps for this will vary, but the general idea is to compile them, and then upload the compiled assets.
+The steps for this will vary, but the general idea is to compile them, and then upload the compiled assets from their [compiled location](compile.py#get_compiled_path).
 
 ```bash
+# Compile the assets
 plain build
+
+# List the newly compiled files
+ls .plain/assets/compiled
+
+# Upload the files to your CDN
 ./example-upload-to-cdn-script
 ```
 
@@ -81,14 +85,10 @@ Use the `ASSETS_BASE_URL` setting to tell the `{{ asset() }}` template function
 ASSETS_BASE_URL = "https://cdn.example.com/"
 ```
 
-
 ### Why aren't the originals copied to the compiled directory?
 
 The default behavior is to fingerprint assets, which is an exact copy of the original file but with a different filename. The originals aren't copied over because you should generally always use this fingerprinted path (that automatically uses longer-lived caching).
 
 If you need the originals for any reason, you can use `plain build --keep-original`, though this will typically be combined with `--no-fingerprint` otherwise the fingerprinted files will still get priority in `{{ asset() }}` template calls.
 
-
-### What about source maps or imported css files?
-
-TODO
+Note that by default, the `ASSETS_REDIRECT_ORIGINAL` setting is `True`, which will redirect requests for the original file to the fingerprinted file.

plain/assets/compile.py

@@ -1,14 +1,11 @@
 import gzip
-import hashlib
 import os
 import shutil
 
 from plain.runtime import settings
 
 from .finders import iter_assets
-from .fingerprints import AssetsFingerprintsManifest
-
-FINGERPRINT_LENGTH = 7
+from .fingerprints import AssetsFingerprintsManifest, get_file_fingerprint
 
 SKIP_COMPRESS_EXTENSIONS = (
     # Images
@@ -46,12 +43,17 @@ SKIP_COMPRESS_EXTENSIONS = (
 def get_compiled_path():
     """
     Get the path at runtime to the compiled assets directory.
+
     There's no reason currently for this to be a user-facing setting.
     """
     return settings.PLAIN_TEMP_PATH / "assets" / "compiled"
 
 
 def compile_assets(*, target_dir, keep_original, fingerprint, compress):
+    """
+    Compile all assets to the target directory and save a JSON manifest
+    mapping the original filenames to the compiled filenames.
+    """
     manifest = AssetsFingerprintsManifest()
 
     for asset in iter_assets():
@@ -68,8 +70,7 @@ def compile_assets(*, target_dir, keep_original, fingerprint, compress):
 
         yield url_path, resolved_path, compiled_paths
 
-    if manifest:
-        manifest.save()
+    manifest.save()
 
 
 def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
@@ -98,11 +99,7 @@ def compile_asset(*, asset, target_dir, keep_original, fingerprint, compress):
         # Fingerprint it with an md5 hash
         # (maybe need a setting with fnmatch patterns for files to NOT fingerprint?
         # that would allow pre-fingerprinted files to be used as-is, and keep source maps etc in tact)
-        with open(asset.absolute_path, "rb") as f:
-            content = f.read()
-            fingerprint_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()[
-                :FINGERPRINT_LENGTH
-            ]
+        fingerprint_hash = get_file_fingerprint(asset.absolute_path)
 
         fingerprinted_basename = f"{base}.{fingerprint_hash}{extension}"
         fingerprinted_path = os.path.join(target_dir, fingerprinted_basename)

plain/assets/finders.py

@@ -9,6 +9,11 @@ SKIP_ASSETS = (".DS_Store", ".gitignore")
 
 
 def iter_assets():
+    """
+    Iterate all valid asset files found in the installed
+    packages and the app itself.
+    """
+
     class Asset:
         def __init__(self, *, url_path, absolute_path):
             self.url_path = url_path
@@ -32,6 +37,10 @@ def iter_assets():
 
 
 def iter_asset_dirs():
+    """
+    Iterate all directories containing assets, from installed
+    packages and from app/assets.
+    """
     # Iterate the installed package assets, in order
     for pkg in packages_registry.get_package_configs():
         asset_dir = os.path.join(pkg.path, "assets")

plain/assets/fingerprints.py

@@ -1,10 +1,17 @@
+import hashlib
 import json
 from functools import cache
 
 from plain.runtime import settings
 
+FINGERPRINT_LENGTH = 7
+
 
 class AssetsFingerprintsManifest(dict):
+    """
+    A manifest of original filenames to fingerprinted filenames.
+    """
+
     def __init__(self):
         self.path = settings.PLAIN_TEMP_PATH / "assets" / "fingerprints.json"
 
@@ -36,3 +43,16 @@ def get_fingerprinted_url_path(url_path):
     manifest = _get_manifest()
     if url_path in manifest:
         return manifest[url_path]
+
+
+def get_file_fingerprint(file_path):
+    """
+    Get the fingerprint hash for a file.
+    """
+    with open(file_path, "rb") as f:
+        content = f.read()
+        fingerprint_hash = hashlib.md5(content, usedforsecurity=False).hexdigest()[
+            :FINGERPRINT_LENGTH
+        ]
+
+    return fingerprint_hash

plain/assets/urls.py

@@ -6,6 +6,12 @@ from .views import AssetView
 
 
 class AssetsRouter(Router):
+    """
+    The router for serving static assets.
+
+    Include this router in your app router if you are serving assets yourself.
+    """
+
     namespace = "assets"
     urls = [
         path("<path:path>", AssetView, name="asset"),
@@ -13,6 +19,9 @@ class AssetsRouter(Router):
 
 
 def get_asset_url(url_path):
+    """
+    Get the full URL to a given asset path.
+    """
     if settings.DEBUG:
         # In debug, we only ever use the original URL path.
         resolved_url_path = url_path

plain/assets/views.py

@@ -16,9 +16,9 @@ from plain.runtime import settings
 from plain.urls import reverse
 from plain.views import View
 
-from .compile import FINGERPRINT_LENGTH, get_compiled_path
+from .compile import get_compiled_path
 from .finders import iter_assets
-from .fingerprints import get_fingerprinted_url_path
+from .fingerprints import FINGERPRINT_LENGTH, get_fingerprinted_url_path
 
 
 class AssetView(View):
@@ -28,8 +28,12 @@ class AssetView(View):
     This class could be subclassed to further tweak the responses or behavior.
     """
 
+    def __init__(self, asset_path=None):
+        # Allow a path to be passed in AssetView.as_view(path="...")
+        self.asset_path = asset_path
+
     def get_url_path(self):
-        return self.url_kwargs["path"]
+        return self.asset_path or self.url_kwargs["path"]
 
     def get(self):
         url_path = self.get_url_path()

plain/cli/README.md

@@ -1,101 +1,84 @@
 # CLI
 
-The `plain` CLI loads commands from Plain itself, and any `INSTALLED_PACKAGES`.
+**The `plain` CLI and how to add your own commands to it.**
 
-Commands are written using [Click]((https://click.palletsprojects.com/en/8.1.x/))
+Commands are written using [Click](https://click.palletsprojects.com/en/8.1.x/)
 (one of Plain's few dependencies),
-which has been one of those most popular CLI frameworks in Python for a long time now.
+which has been one of those most popular CLI frameworks in Python for a long time.
 
 ## Built-in commands
 
-### `plain shell`
-
-Open a Python shell with the Plain loaded.
-
-To auto-load models or run other code at shell launch,
-create an `app/shell.py` and it will be imported automatically.
-
-```python
-# app/shell.py
-from organizations.models import Organization
-
-__all__ = [
-    "Organization",
-]
-```
-
 ### `plain build`
 
 Compile static assets (used in the deploy/production process).
 
-Automatically runs `plain tailwind build` if [plain-tailwind](https://plainframework.com/docs/plain-tailwind/) is installed.
+Automatically runs `plain tailwind build` if [plain.tailwind](/plain-tailwind/) is installed.
 
-### `plain run`
+### `plain create`
 
-Run a Python script in the context of your app.
+Create a new local package.
 
 ### `plain preflight`
 
 Run preflight checks to ensure your app is ready to run.
 
-### `plain create`
+### `plain run`
 
-Create a new local package.
+Run a Python script in the context of your app.
 
 ### `plain setting`
 
 View the runtime value of a named setting.
 
-## Adding commands
+### `plain shell`
 
-### Add an `app/cli.py`
+Open a Python shell with the Plain loaded.
 
-You can add "root" commands to your app by defining a `cli` function in `app/cli.py`.
+To auto-load models or run other code at shell launch,
+create an `app/shell.py` and it will be imported automatically.
 
 ```python
-import click
-
+# app/shell.py
+from app.organizations.models import Organization
 
-@click.group()
-def cli():
-    pass
+__all__ = [
+    "Organization",
+]
+```
 
+### `plain urls`
 
-@cli.command()
-def custom_command():
-    click.echo("An app command!")
-```
+List all the URL patterns in your app.
 
-Then you can run the command with `plain`.
+### `plain utils generate-secret-key`
 
-```bash
-$ plain custom-command
-An app command!
-```
+Generate a new secret key for your app, to be used in `settings.SECRET_KEY`.
 
-### Add CLI commands to your local packages
+## Adding commands
 
-Any package in `INSTALLED_PACKAGES` can define CLI commands by creating a `cli.py` in the root of the package.
-In `cli.py`, create a command or group of commands named `cli`.
+The `register_cli` decorator can be used to add your own commands to the `plain` CLI.
 
 ```python
 import click
+from plain.cli import register_cli
 
 
+@register_cli("example-subgroup-name")
 @click.group()
 def cli():
+    """Custom example commands"""
     pass
 
-
 @cli.command()
-def hello():
-    click.echo("Hello, world!")
+def example_command():
+    click.echo("An example command!")
 ```
 
-Plain will use the name of the package in the CLI,
-then any commands you defined.
+Then you can run the command with `plain`.
 
 ```bash
-$ plain <pkg> hello
-Hello, world!
+$ plain example-subgroup-name example-command
+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.

plain/cli/core.py

@@ -1,3 +1,5 @@
+import ast
+import importlib.util
 import os
 import shutil
 import subprocess
@@ -26,10 +28,207 @@ def plain_cli():
     pass
 
 
-# @plain_cli.command
-# def docs():
-#     """Open the Forge documentation in your browser"""
-#     subprocess.run(["open", "https://www.forgepackages.com/docs/?ref=cli"])
+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 == "internal")
+            ]
+            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_cli.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:
+        click.echo(
+            "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"
+        )
+
+        docs = set()
+        sources = set()
+
+        # Get everything for Plain core
+        for path in Path(__file__).parent.parent.glob("**/*.md"):
+            docs.add(path)
+        for source in Path(__file__).parent.parent.glob("**/*.py"):
+            sources.add(source)
+
+        # Find every *.md file in the other plain packages and installed apps
+        for package_config in packages_registry.get_package_configs():
+            if package_config.name.startswith("app."):
+                # Ignore app packages for now
+                continue
+
+            for path in Path(package_config.path).glob("**/*.md"):
+                docs.add(path)
+
+            for source in Path(package_config.path).glob("**/*.py"):
+                sources.add(source)
+
+        docs = sorted(docs)
+        sources = sorted(sources)
+
+        for doc in docs:
+            try:
+                display_path = doc.relative_to(Path.cwd())
+            except ValueError:
+                display_path = doc.absolute()
+            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 sources:
+            if symbolicated := symbolicate(source):
+                try:
+                    display_path = source.relative_to(Path.cwd())
+                except ValueError:
+                    display_path = source.absolute()
+                click.secho(f"<Source: {display_path}>", fg="yellow")
+                click.echo(symbolicated)
+                click.secho(f"</Source: {display_path}>", fg="yellow")
+                click.echo()
+
+        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()))
 
 
 @plain_cli.command()