plain 0.54.1__tar.gz → 0.56.0__tar.gz

{plain-0.54.1 → plain-0.56.0}/PKG-INFO

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

{plain-0.54.1 → plain-0.56.0}/plain/CHANGELOG.md

@@ -1,5 +1,31 @@
 # plain changelog
 
+## [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
+
+- Updated URL pattern documentation examples to use `id` instead of `pk` in URL kwargs ([b656ee6](https://github.com/dropseed/plain/commit/b656ee6e4e))
+- Updated views documentation examples to use `id` instead of `pk` for DetailView, UpdateView, and DeleteView ([b656ee6](https://github.com/dropseed/plain/commit/b656ee6e4e))
+
+### Upgrade instructions
+
+- Update your URL patterns from `<int:pk>` to `<int:id>` in your URLconf
+- Update view code that accesses `self.url_kwargs["pk"]` to use `self.url_kwargs["id"]` instead
+- Replace any QuerySet filters using `pk` with `id` (e.g., `Model.objects.get(pk=1)` becomes `Model.objects.get(id=1)`)
+
 ## [0.54.1](https://github.com/dropseed/plain/releases/plain@0.54.1) (2025-07-20)
 
 ### What's changed

plain-0.56.0/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.54.1 → plain-0.56.0}/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.54.1 → plain-0.56.0}/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.0/plain/cli/install.py

@@ -0,0 +1,81 @@
+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 follow any setup instructions",
+        "2. If the docs point out that it is a --dev tool, move it to dev dependencies: `uv remove <package> && uv add <package> --dev`",
+        "",
+        "DO NOT commit any changes",
+        "",
+        "Report back with:",
+        "- Whether the setup completed successfully",
+        "- Any manual steps that still need to be completed",
+        "- 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.0/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.54.1 → plain-0.56.0}/plain/urls/patterns.py

@@ -111,8 +111,8 @@ def _route_to_regex(route, is_endpoint=False):
     """
     Convert a path pattern into a regular expression. Return the regular
     expression and a dictionary mapping the capture names to the converters.
-    For example, 'foo/<int:pk>' returns '^foo\\/(?P<pk>[0-9]+)'
-    and {'pk': <plain.urls.converters.IntConverter>}.
+    For example, 'foo/<int:id>' returns '^foo\\/(?P<id>[0-9]+)'
+    and {'id': <plain.urls.converters.IntConverter>}.
     """
     original_route = route
     parts = ["^"]

{plain-0.54.1 → plain-0.56.0}/plain/views/README.md

@@ -169,7 +169,7 @@ class ExampleDetailView(DetailView):
 
     def get_object(self):
         return MyObjectClass.objects.get(
-            pk=self.url_kwargs["pk"],
+            id=self.url_kwargs["id"],
             user=self.request.user,  # Limit access
         )
 
@@ -187,7 +187,7 @@ class ExampleUpdateView(UpdateView):
 
     def get_object(self):
         return MyObjectClass.objects.get(
-            pk=self.url_kwargs["pk"],
+            id=self.url_kwargs["id"],
             user=self.request.user,  # Limit access
         )
 
@@ -201,7 +201,7 @@ class ExampleDeleteView(DeleteView):
 
     def get_object(self):
         return MyObjectClass.objects.get(
-            pk=self.url_kwargs["pk"],
+            id=self.url_kwargs["id"],
             user=self.request.user,  # Limit access
         )
 

{plain-0.54.1 → plain-0.56.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.54.1"
+version = "0.56.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"