plain 0.55.0__tar.gz → 0.56.1__tar.gz

{plain-0.55.0 → plain-0.56.1}/PKG-INFO

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

{plain-0.55.0 → plain-0.56.1}/plain/CHANGELOG.md

@@ -1,5 +1,28 @@
 # plain changelog
 
+## [0.56.1](https://github.com/dropseed/plain/releases/plain@0.56.1) (2025-07-30)
+
+### What's changed
+
+- Improved `plain install` command instructions to be more explicit about completing code modifications ([83292225db](https://github.com/dropseed/plain/commit/83292225db))
+
+### Upgrade instructions
+
+- No changes required
+
+## [0.56.0](https://github.com/dropseed/plain/releases/plain@0.56.0) (2025-07-25)
+
+### What's changed
+
+- Added `plain install` command to install Plain packages with agent-assisted setup ([bf1873e](https://github.com/dropseed/plain/commit/bf1873eb81))
+- Added `--print` option to agent commands (`plain install` and `plain upgrade`) to print prompts without running the agent ([9721331](https://github.com/dropseed/plain/commit/9721331e40))
+- The `plain docs` command now automatically converts hyphens to dots in package names (e.g., `plain-models` → `plain.models`) ([1e3edc1](https://github.com/dropseed/plain/commit/1e3edc10f7))
+- Moved `plain-upgrade` functionality into plain core, eliminating the need for a separate package ([473f9bb](https://github.com/dropseed/plain/commit/473f9bb718))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.55.0](https://github.com/dropseed/plain/releases/plain@0.55.0) (2025-07-22)
 
 ### What's changed

{plain-0.55.0 → plain-0.56.1}/plain/assets/README.md

@@ -2,7 +2,13 @@
 
 **Serve static assets (CSS, JS, images, etc.) directly or from a CDN.**
 
-## Usage
+- [Overview](#overview)
+- [Local development](#local-development)
+- [Production deployment](#production-deployment)
+- [Using `AssetView` directly](#using-assetview-directly)
+- [FAQs](#faqs)
+
+## Overview
 
 To serve assets, put them in `app/assets` or `app/{package}/assets`.
 
@@ -62,7 +68,7 @@ class AppRouter(Router):
 
 ## FAQs
 
-### How do you reference assets in Python code?
+#### How do you reference assets in Python code?
 
 There is a [`get_asset_url`](./urls.py#get_asset_url) function that you can use to get the URL of an asset in Python code. This is useful if you need to reference an asset in a non-template context, such as in a redirect or an API response.
 
@@ -72,7 +78,7 @@ from plain.assets.urls import get_asset_url
 url = get_asset_url("css/style.css")
 ```
 
-### What if I need the files in a different location?
+#### What if I need the files in a different location?
 
 The generated/copied files are stored in `{repo}/.plain/assets/compiled`. If you need them to be somewhere else, try simply moving them after compilation.
 
@@ -81,7 +87,7 @@ plain build
 mv .plain/assets/compiled /path/to/your/static
 ```
 
-### How do I upload the assets to a CDN?
+#### 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 from their [compiled location](compile.py#get_compiled_path).
 
@@ -103,7 +109,7 @@ Use the [`ASSETS_BASE_URL`](../runtime/global_settings.py#ASSETS_BASE_URL) setti
 ASSETS_BASE_URL = "https://cdn.example.com/"
 ```
 
-### Why aren't the originals copied to the compiled directory?
+#### 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).
 

{plain-0.55.0 → plain-0.56.1}/plain/chores/README.md

@@ -2,6 +2,12 @@
 
 **Routine maintenance tasks.**
 
+- [Overview](#overview)
+- [Running chores](#running-chores)
+- [Writing chores](#writing-chores)
+
+## Overview
+
 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)

plain-0.56.1/plain/cli/README.md

@@ -0,0 +1,41 @@
+# CLI
+
+**The `plain` CLI and how to add your own commands to it.**
+
+- [Overview](#overview)
+- [Adding commands](#adding-commands)
+
+## Overview
+
+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.
+
+## Adding commands
+
+The [`register_cli`](./registry.py#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 example_command():
+    click.echo("An example command!")
+```
+
+Then you can run the command with `plain`.
+
+```bash
+$ 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-0.56.1/plain/cli/agent.py

@@ -0,0 +1,44 @@
+import shlex
+import subprocess
+
+import click
+
+
+def prompt_agent(
+    prompt: str, agent_command: str | None = None, print_only: bool = False
+) -> bool:
+    """
+    Run an agent command with the given prompt, or display the prompt for manual copying.
+
+    Args:
+        prompt: The prompt to send to the agent
+        agent_command: Optional command to run (e.g., "claude code"). If not provided,
+                      will check the PLAIN_AGENT_COMMAND environment variable.
+        print_only: If True, always print the prompt instead of running the agent
+
+    Returns:
+        True if the agent command succeeded (or no agent command was provided),
+        False if the agent command failed.
+    """
+    if print_only or not agent_command:
+        click.echo(prompt)
+        if not print_only:
+            click.secho(
+                "\nCopy the prompt above to a coding agent. To run an agent automatically, use --agent-command or set the PLAIN_AGENT_COMMAND environment variable.",
+                dim=True,
+                italic=True,
+                err=True,
+            )
+        return True
+    else:
+        cmd = shlex.split(agent_command)
+        cmd.append(prompt)
+        result = subprocess.run(cmd, check=False)
+        if result.returncode != 0:
+            click.secho(
+                f"Agent command failed with exit code {result.returncode}",
+                fg="red",
+                err=True,
+            )
+            return False
+        return True

{plain-0.55.0 → plain-0.56.1}/plain/cli/core.py

@@ -12,11 +12,13 @@ from .chores import chores
 from .docs import docs
 from .formatting import PlainContext
 from .help import help_cmd
+from .install import install
 from .preflight import preflight_checks
 from .registry import cli_registry
 from .scaffold import create
 from .settings import setting
 from .shell import run, shell
+from .upgrade import upgrade
 from .urls import urls
 from .utils import utils
 
@@ -37,6 +39,8 @@ plain_cli.add_command(changelog)
 plain_cli.add_command(setting)
 plain_cli.add_command(shell)
 plain_cli.add_command(run)
+plain_cli.add_command(install)
+plain_cli.add_command(upgrade)
 plain_cli.add_command(help_cmd)
 
 

{plain-0.55.0 → plain-0.56.1}/plain/cli/docs.py

@@ -40,6 +40,9 @@ def docs(module, llm, open):
         return
 
     if module:
+        # Convert hyphens to dots (e.g., plain-models -> plain.models)
+        module = module.replace("-", ".")
+
         # Automatically prefix if we need to
         if not module.startswith("plain"):
             module = f"plain.{module}"

plain-0.56.1/plain/cli/install.py

@@ -0,0 +1,82 @@
+import subprocess
+import sys
+
+import click
+
+from .agent import prompt_agent
+
+
+@click.command()
+@click.argument("packages", nargs=-1, required=True)
+@click.option(
+    "--agent-command",
+    envvar="PLAIN_AGENT_COMMAND",
+    help="Run command with generated prompt",
+)
+@click.option(
+    "--print",
+    "print_only",
+    is_flag=True,
+    help="Print the prompt without running the agent",
+)
+def install(
+    packages: tuple[str, ...],
+    agent_command: str | None = None,
+    print_only: bool = False,
+) -> None:
+    """Install Plain packages with the help of an agent."""
+    # Validate all package names
+    invalid_packages = [pkg for pkg in packages if not pkg.startswith("plain")]
+    if invalid_packages:
+        raise click.UsageError(
+            f"The following packages do not start with 'plain': {', '.join(invalid_packages)}\n"
+            "This command is only for Plain framework packages."
+        )
+
+    # Install all packages first
+    if len(packages) == 1:
+        click.secho(f"Installing {packages[0]}...", bold=True, err=True)
+    else:
+        click.secho(f"Installing {len(packages)} packages...", bold=True, err=True)
+        for pkg in packages:
+            click.secho(f"  - {pkg}", err=True)
+        click.echo(err=True)
+
+    install_cmd = ["uv", "add"] + list(packages)
+    result = subprocess.run(install_cmd, check=False, stderr=sys.stderr)
+
+    if result.returncode != 0:
+        raise click.ClickException("Failed to install packages")
+
+    click.echo(err=True)
+    if len(packages) == 1:
+        click.secho(f"✓ {packages[0]} installed successfully", fg="green", err=True)
+    else:
+        click.secho(
+            f"✓ {len(packages)} packages installed successfully", fg="green", err=True
+        )
+    click.echo(err=True)
+
+    # Build the prompt for the agent to complete setup
+    lines = [
+        f"Complete the setup for the following Plain packages that were just installed: {', '.join(packages)}",
+        "",
+        "## Instructions",
+        "",
+        "For each package:",
+        "1. Run `uv run plain docs <package>` and read the installation instructions",
+        "2. If the docs point out that it is a --dev tool, move it to the dev dependencies in pyproject.toml: `uv remove <package> && uv add <package> --dev`",
+        "3. Go through the installation instructions and complete any code modifications that are needed",
+        "",
+        "DO NOT commit any changes",
+        "",
+        "Report back with:",
+        "- Whether the setup completed successfully",
+        "- Any manual steps that the user will need to complete",
+        "- Any issues or errors encountered",
+    ]
+
+    prompt = "\n".join(lines)
+    success = prompt_agent(prompt, agent_command, print_only)
+    if not success:
+        raise click.Abort()

plain-0.56.1/plain/cli/upgrade.py

@@ -0,0 +1,168 @@
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+import click
+
+from .agent import prompt_agent
+
+LOCK_FILE = Path("uv.lock")
+
+
+@click.command()
+@click.argument("packages", nargs=-1)
+@click.option(
+    "--diff", is_flag=True, help="Read versions from unstaged uv.lock changes"
+)
+@click.option(
+    "--agent-command",
+    envvar="PLAIN_AGENT_COMMAND",
+    help="Run command with generated prompt",
+)
+@click.option(
+    "--print",
+    "print_only",
+    is_flag=True,
+    help="Print the prompt without running the agent",
+)
+def upgrade(
+    packages: tuple[str, ...],
+    diff: bool,
+    agent_command: str | None = None,
+    print_only: bool = False,
+) -> None:
+    """Upgrade Plain packages with the help of an agent."""
+    if not packages:
+        click.secho("Getting installed packages...", bold=True, err=True)
+        packages = tuple(sorted(get_installed_plain_packages()))
+        for pkg in packages:
+            click.secho(f"- {click.style(pkg, fg='yellow')}", err=True)
+        click.echo(err=True)
+
+    if not packages:
+        raise click.UsageError("No plain packages found or specified.")
+
+    if diff:
+        before_after = versions_from_diff(packages)
+    else:
+        before_after = upgrade_packages(packages)
+
+    # Remove all packages that were not upgraded
+    before_after = {
+        pkg: versions
+        for pkg, versions in before_after.items()
+        if versions[0] != versions[1]
+    }
+
+    if not before_after:
+        click.secho(
+            "No packages were upgraded. If uv.lock has already been updated, use --diff instead.",
+            fg="green",
+            err=True,
+        )
+        return
+
+    prompt = build_prompt(before_after)
+    success = prompt_agent(prompt, agent_command, print_only)
+    if not success:
+        raise click.Abort()
+
+
+def get_installed_plain_packages() -> list[str]:
+    lock_text = LOCK_FILE.read_text()
+    data = tomllib.loads(lock_text)
+    names: list[str] = []
+    for pkg in data.get("package", []):
+        name = pkg.get("name", "")
+        if name.startswith("plain") and name != "plain-upgrade":
+            names.append(name)
+    return names
+
+
+def parse_lock_versions(lock_text: str, packages: set[str]) -> dict[str, str]:
+    data = tomllib.loads(lock_text)
+    versions: dict[str, str] = {}
+    for pkg in data.get("package", []):
+        name = pkg.get("name")
+        if name in packages:
+            versions[name] = pkg.get("version")
+    return versions
+
+
+def versions_from_diff(
+    packages: tuple[str, ...],
+) -> dict[str, tuple[str | None, str | None]]:
+    result = subprocess.run(
+        ["git", "status", "--porcelain", str(LOCK_FILE)], capture_output=True, text=True
+    )
+    if not result.stdout.strip():
+        raise click.UsageError(
+            "--diff specified but uv.lock has no uncommitted changes"
+        )
+
+    prev_text = subprocess.run(
+        ["git", "show", f"HEAD:{LOCK_FILE}"], capture_output=True, text=True, check=True
+    ).stdout
+    current_text = LOCK_FILE.read_text()
+
+    packages_set = set(packages)
+    before = parse_lock_versions(prev_text, packages_set)
+    after = parse_lock_versions(current_text, packages_set)
+
+    return {pkg: (before.get(pkg), after.get(pkg)) for pkg in packages}
+
+
+def upgrade_packages(
+    packages: tuple[str, ...],
+) -> dict[str, tuple[str | None, str | None]]:
+    before = parse_lock_versions(LOCK_FILE.read_text(), set(packages))
+
+    upgrade_args = ["uv", "sync"]
+    for pkg in packages:
+        upgrade_args.extend(["--upgrade-package", pkg])
+
+    click.secho("Upgrading with uv sync...", bold=True, err=True)
+    subprocess.run(upgrade_args, check=True, stdout=sys.stderr)
+    click.echo(err=True)
+
+    after = parse_lock_versions(LOCK_FILE.read_text(), set(packages))
+    return {pkg: (before.get(pkg), after.get(pkg)) for pkg in packages}
+
+
+def build_prompt(before_after: dict[str, tuple[str | None, str | None]]) -> str:
+    lines = [
+        "These packages have been updated and may require additional changes to the code:",
+        "",
+    ]
+    for pkg, (before, after) in before_after.items():
+        lines.append(f"- {pkg}: {before} -> {after}")
+
+    lines.extend(
+        [
+            "",
+            "## Instructions",
+            "",
+            "1. **Process each package systematically:**",
+            "   - For each package, run: `uv run plain-changelog {package} --from {before} --to {after}`",
+            "   - Read the 'Upgrade instructions' section carefully",
+            "   - If it says 'No changes required', skip to the next package",
+            "   - Apply any required code changes as specified",
+            "",
+            "2. **Important guidelines:**",
+            "   - Process ALL packages before testing or validation",
+            "   - After all packages are updated, run `uv run plain fix --unsafe-fixes` and `uv run plain pre-commit` to check results",
+            "   - DO NOT commit any changes",
+            "   - DO NOT run `plain migrate` with the `--no-backup` option",
+            "   - Keep code changes minimal and focused - avoid unnecessary comments",
+            "",
+            "3. **Available tools:**",
+            "   - Python shell: `uv run python`",
+            "",
+            "4. **Workflow:**",
+            "   - Review changelog for each package → Apply changes → Move to next package",
+            "   - Only after all packages: run pre-commit checks",
+            "   - Report any issues or conflicts encountered",
+        ]
+    )
+    return "\n".join(lines)

{plain-0.55.0 → plain-0.56.1}/plain/csrf/README.md

@@ -2,7 +2,12 @@
 
 **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 `CSRF-Token` header).
+- [Overview](#overview)
+- [Usage](#usage)
+
+## Overview
+
+Plain protects against [CSRF attacks](https://en.wikipedia.org/wiki/Cross-site_request_forgery) through a [middleware](./middleware.py#CsrfViewMiddleware) that compares the generated `csrftoken` cookie with the CSRF token from the request (either `_csrftoken` in form data or the `CSRF-Token` header).
 
 ## Usage
 

{plain-0.55.0 → plain-0.56.1}/plain/forms/README.md

@@ -2,6 +2,10 @@
 
 **HTML form handling and validation.**
 
+- [Overview](#overview)
+
+## Overview
+
 The `Form` and `Field` classes help output, parse, and validate form data from an HTTP request. Unlike other frameworks, the HTML inputs are not rendered automatically, though there are some helpers for you to do your own rendering.
 
 With forms, you will typically use one of the built-in view classes to tie everything together.

{plain-0.55.0 → plain-0.56.1}/plain/http/README.md

@@ -2,6 +2,10 @@
 
 **HTTP request and response handling.**
 
+- [Overview](#overview)
+
+## Overview
+
 Typically you will interact with [request](request.py#HttpRequest) and [response](response.py#ResponseBase) objects in your views and middleware.
 
 ```python

{plain-0.55.0 → plain-0.56.1}/plain/logs/README.md

@@ -2,6 +2,13 @@
 
 **Logging configuration and utilities.**
 
+- [Overview](#overview)
+- [`app_logger`](#app_logger)
+- [`app_logger.kv`](#app_loggerkv)
+- [Logging settings](#logging-settings)
+
+## Overview
+
 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.55.0 → plain-0.56.1}/plain/packages/README.md

@@ -2,6 +2,13 @@
 
 **Install Python modules as Plain packages.**
 
+- [Overview](#overview)
+- [Creating app packages](#creating-app-packages)
+- [Package settings](#package-settings)
+- [Package `ready()` method](#package-ready-method)
+
+## Overview
+
 Most Python modules that you use with Plain will need to be installed via `settings.INSTALLED_PACKAGES`. This is what enables template detection, per-package settings, database models, and other features.
 
 A package can either be a local module inside of your `app`, or a third-party package from PyPI.

{plain-0.55.0 → plain-0.56.1}/plain/preflight/README.md

@@ -2,6 +2,14 @@
 
 **System checks for Plain applications.**
 
+- [Overview](#overview)
+- [Development](#development)
+- [Deployment](#deployment)
+- [Custom preflight checks](#custom-preflight-checks)
+- [Silencing preflight checks](#silencing-preflight-checks)
+
+## Overview
+
 Preflight checks help identify issues with your settings or environment before running your application.
 
 ```bash

{plain-0.55.0 → plain-0.56.1}/plain/runtime/README.md

@@ -2,6 +2,15 @@
 
 **Access app and package settings at runtime.**
 
+- [Overview](#overview)
+- [Environment variables](#environment-variables)
+    - [.env files](#env-files)
+- [Package settings](#package-settings)
+- [Custom app-wide settings](#custom-app-wide-settings)
+- [Using Plain in other environments](#using-plain-in-other-environments)
+
+## Overview
+
 Plain is configured by "settings", which are ultimately just Python variables. Most settings have default values which can be overidden either by your `app/settings.py` file or by environment variables.
 
 ```python

{plain-0.55.0 → plain-0.56.1}/plain/signals/README.md

@@ -2,6 +2,10 @@
 
 **Run code when certain events happen.**
 
+- [Overview](#overview)
+
+## Overview
+
 ```python
 from plain.signals import request_finished
 

{plain-0.55.0 → plain-0.56.1}/plain/templates/README.md

@@ -2,6 +2,13 @@
 
 **Render HTML templates using Jinja.**
 
+- [Overview](#overview)
+- [Template files](#template-files)
+- [Extending Jinja](#extending-jinja)
+- [Rendering templates manually](#rendering-templates-manually)
+
+## Overview
+
 Plain uses Jinja2 for template rendering. You can refer to the [Jinja documentation](https://jinja.palletsprojects.com/en/stable/api/) for all of the features available.
 
 In general, templates are used in combination with `TemplateView` or a more specific subclass of it.
@@ -37,7 +44,7 @@ All template directories are "merged" together, allowing you to override templat
 
 ## Extending Jinja
 
-Plain includes a set of default [global variables](jinja/globals.py) and [filters](jinja/filters.py). You can register additional extensions, globals, or filters either in a package or in your app. Typically this will be in `app/templates.py` or `<pkg>/templates.py`, which are automatically imported.
+Plain includes a set of default [global variables](./jinja/globals.py) and [filters](./jinja/filters.py). You can register additional extensions, globals, or filters either in a package or in your app. Typically this will be in `app/templates.py` or `<pkg>/templates.py`, which are automatically imported.
 
 ```python
 # app/templates.py
@@ -71,7 +78,7 @@ class HTMXJSExtension(InclusionTagExtension):
 
 ## Rendering templates manually
 
-Templates can also be rendered manually using the [`Template` class](core.py#Template).
+Templates can also be rendered manually using the [`Template` class](./core.py#Template).
 
 ```python
 from plain.templates import Template

{plain-0.55.0 → plain-0.56.1}/plain/test/README.md

@@ -2,7 +2,11 @@
 
 **Testing utilities for Plain.**
 
-This module provides a the [`Client`](client.py#Client) and [`RequestFactory`](client.py#RequestFactory) classes to facilitate testing requests and responses.
+- [Overview](#overview)
+
+## Overview
+
+This module provides the [`Client`](client.py#Client) and [`RequestFactory`](client.py#RequestFactory) classes to facilitate testing requests and responses.
 
 ```python
 from plain.test import Client

{plain-0.55.0 → plain-0.56.1}/plain/urls/README.md

@@ -2,6 +2,13 @@
 
 **Route requests to views.**
 
+- [Overview](#overview)
+- [Reversing URLs](#reversing-urls)
+- [URL args and kwargs](#url-args-and-kwargs)
+- [Package routers](#package-routers)
+
+## Overview
+
 URLs are typically the "entrypoint" to your app. Virtually all request handling up to this point happens behind the scenes, and then you decide how to route specific URL patterns to your views.
 
 The `URLS_ROUTER` is the primary router that handles all incoming requests. It is defined in your `app/settings.py` file. This will typically point to a `Router` class in your `app.urls` module.

{plain-0.55.0 → plain-0.56.1}/plain/utils/README.md

@@ -1,5 +1,9 @@
-# Utilities
+# Utils
 
 **Various utilities for text manipulation, parsing, dates, and more.**
 
+- [Overview](#overview)
+
+## Overview
+
 The utilities aren't going to be documented in detail here. Take a look at the source code for more information.