plain 0.59.0__tar.gz → 0.61.0__tar.gz

{plain-0.59.0 → plain-0.61.0}/PKG-INFO

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

plain-0.61.0/plain/AGENTS.md

@@ -0,0 +1,14 @@
+# Plain AGENTS.md
+
+Plain is a Python web framework that was originally forked from Django. While it still has a lot in common with Django, there are also significant changes -- don't solely rely on knowledge of Django when working with Plain.
+
+## Commands
+
+The `plain` CLI is the main entrypoint for the framework. If `plain` is not available by itself, try `uv run plain`.
+
+- `plain shell -c <command>`: Run a Python command with Plain configured.
+- `plain run <filename>`: Run a Python script with Plain configured.
+- `plain agent docs <package>`: Show README.md and symbolicated source files for a specific package.
+- `plain agent docs --list`: List packages with docs available.
+- `plain agent request <path> --user <user_id>`: Make an authenticated request to the application and inspect the output.
+- `plain --help`: List all available commands (including those from installed packages)

{plain-0.59.0 → plain-0.61.0}/plain/CHANGELOG.md

@@ -1,5 +1,30 @@
 # plain changelog
 
+## [0.61.0](https://github.com/dropseed/plain/releases/plain@0.61.0) (2025-09-03)
+
+### What's changed
+
+- Added new `plain agent` command with subcommands for coding agents including `docs`, `md`, and `request` ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+- Added `-c` option to `plain shell` to execute commands and exit, similar to `python -c` ([5e67f0b](https://github.com/dropseed/plain/commit/5e67f0bcd8))
+- The `plain docs --llm` functionality has been moved to `plain agent docs` command ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+- Removed the `plain help` command in favor of standard `plain --help` ([df3edbf](https://github.com/dropseed/plain/commit/df3edbf0bd))
+
+### Upgrade instructions
+
+- Replace `plain docs --llm` usage with `plain agent docs` command
+- Use `plain --help` instead of `plain help` command
+
+## [0.60.0](https://github.com/dropseed/plain/releases/plain@0.60.0) (2025-08-27)
+
+### What's changed
+
+- Added new `APP_VERSION` setting that defaults to the project version from `pyproject.toml` ([57fb948d46](https://github.com/dropseed/plain/commit/57fb948d46))
+- Updated `get_app_name_from_pyproject()` to `get_app_info_from_pyproject()` to return both name and version ([57fb948d46](https://github.com/dropseed/plain/commit/57fb948d46))
+
+### Upgrade instructions
+
+- No changes required
+
 ## [0.59.0](https://github.com/dropseed/plain/releases/plain@0.59.0) (2025-08-22)
 
 ### What's changed

plain-0.61.0/plain/cli/agent/__init__.py

@@ -0,0 +1,20 @@
+import click
+
+from .docs import docs
+from .md import md
+from .request import request
+
+
+@click.group("agent", invoke_without_command=True)
+@click.pass_context
+def agent(ctx):
+    """Tools for coding agents."""
+    if ctx.invoked_subcommand is None:
+        # If no subcommand provided, show all AGENTS.md files
+        ctx.invoke(md, show_all=True, show_list=False, package="")
+
+
+# Add commands to the group
+agent.add_command(docs)
+agent.add_command(md)
+agent.add_command(request)

plain-0.61.0/plain/cli/agent/docs.py

@@ -0,0 +1,80 @@
+import importlib.util
+import pkgutil
+from pathlib import Path
+
+import click
+
+from .llmdocs import LLMDocs
+
+
+@click.command()
+@click.argument("package", default="", required=False)
+@click.option(
+    "--list",
+    "show_list",
+    is_flag=True,
+    help="List available packages",
+)
+def docs(package, show_list):
+    """Show LLM-friendly documentation and source for a package."""
+
+    if show_list:
+        # List available packages using same discovery logic as md command
+        try:
+            available_packages = []
+
+            # Check for plain.* subpackages (including core plain)
+            try:
+                import plain
+
+                # Check core plain package (namespace package)
+                plain_spec = importlib.util.find_spec("plain")
+                if plain_spec and plain_spec.submodule_search_locations:
+                    available_packages.append("plain")
+
+                # Check other plain.* subpackages
+                for importer, modname, ispkg in pkgutil.iter_modules(
+                    plain.__path__, "plain."
+                ):
+                    if ispkg:
+                        available_packages.append(modname)
+            except Exception:
+                pass
+
+            if available_packages:
+                for pkg in sorted(available_packages):
+                    click.echo(f"- {pkg}")
+            else:
+                click.echo("No packages found.")
+        except Exception as e:
+            click.echo(f"Error listing packages: {e}")
+        return
+
+    if not package:
+        raise click.UsageError(
+            "Package name required. Usage: plain agent docs [package-name]"
+        )
+
+    # Convert hyphens to dots (e.g., plain-models -> plain.models)
+    package = package.replace("-", ".")
+
+    # Automatically prefix if we need to
+    if not package.startswith("plain"):
+        package = f"plain.{package}"
+
+    try:
+        # Get the path for this specific package
+        spec = importlib.util.find_spec(package)
+        if not spec or not spec.origin:
+            raise click.UsageError(f"Package {package} not found")
+
+        package_path = Path(spec.origin).parent
+        paths = [package_path]
+
+        # Generate docs for this specific package
+        source_docs = LLMDocs(paths)
+        source_docs.load()
+        source_docs.print(relative_to=package_path.parent)
+
+    except Exception as e:
+        raise click.UsageError(f"Error loading documentation for {package}: {e}")

plain-0.59.0/plain/cli/docs.py → plain-0.61.0/plain/cli/agent/llmdocs.py

@@ -1,75 +1,11 @@
 import ast
-import importlib.util
 from pathlib import Path
 
 import click
 
-from plain.packages import packages_registry
-
-from .output import iterate_markdown
-
-
-@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:
-        raise click.UsageError("You must specify a module or use --llm")
-
-    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:
-        # 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}"
-
-        # Get the README.md file for the module
-        spec = importlib.util.find_spec(module)
-        if not spec:
-            raise click.UsageError(f"Module {module} not found")
-
-        module_path = Path(spec.origin).parent
-        readme_path = module_path / "README.md"
-        if not readme_path.exists():
-            raise click.UsageError(f"README.md not found for {module}")
-
-        if open:
-            click.launch(str(readme_path))
-        else:
-            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"
-    )
+    """Generates LLM-friendly documentation."""
 
     def __init__(self, paths):
         self.paths = paths
@@ -88,6 +24,7 @@ class LLMDocs:
                 self.docs.add(path)
 
         # Exclude "migrations" code from plain apps, except for plain/models/migrations
+        # Also exclude CHANGELOG.md and AGENTS.md
         self.docs = {
             doc
             for doc in self.docs
@@ -95,6 +32,7 @@ class LLMDocs:
                 "/migrations/" in str(doc)
                 and "/plain/models/migrations/" not in str(doc)
             )
+            and doc.name not in ("CHANGELOG.md", "AGENTS.md")
         }
         self.sources = {
             source
@@ -103,6 +41,7 @@ class LLMDocs:
                 "/migrations/" in str(source)
                 and "/plain/models/migrations/" not in str(source)
             )
+            and source.name != "cli.py"
         }
 
         self.docs = sorted(self.docs)
@@ -120,8 +59,6 @@ class LLMDocs:
         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)
@@ -159,14 +96,11 @@ class LLMDocs:
                     for d in node.decorator_list
                 ):
                     return True
-                if node.name.startswith("_"):  # and not node.name.endswith("__"):
+                if node.name.startswith("_"):
                     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("__")
-                    ):
+                    if isinstance(target, ast.Name) and target.id.startswith("_"):
                         return True
             return False
 
@@ -186,23 +120,16 @@ class LLMDocs:
                 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:

plain-0.61.0/plain/cli/agent/md.py

@@ -0,0 +1,87 @@
+import importlib.util
+import pkgutil
+from pathlib import Path
+
+import click
+
+from ..output import iterate_markdown
+
+
+def _get_packages_with_agents():
+    """Get dict mapping package names to AGENTS.md paths."""
+    agents_files = {}
+
+    # Check for plain.* subpackages (including core plain)
+    try:
+        import plain
+
+        # Check core plain package (namespace package)
+        plain_spec = importlib.util.find_spec("plain")
+        if plain_spec and plain_spec.submodule_search_locations:
+            # For namespace packages, use the first search location
+            plain_path = Path(plain_spec.submodule_search_locations[0])
+            agents_path = plain_path / "AGENTS.md"
+            if agents_path.exists():
+                agents_files["plain"] = agents_path
+
+        # Check other plain.* subpackages
+        for importer, modname, ispkg in pkgutil.iter_modules(plain.__path__, "plain."):
+            if ispkg:
+                try:
+                    spec = importlib.util.find_spec(modname)
+                    if spec and spec.origin:
+                        package_path = Path(spec.origin).parent
+                        # Look for AGENTS.md at package root
+                        agents_path = package_path / "AGENTS.md"
+                        if agents_path.exists():
+                            agents_files[modname] = agents_path
+                except Exception:
+                    continue
+    except Exception:
+        pass
+
+    return agents_files
+
+
+@click.command("md")
+@click.argument("package", default="", required=False)
+@click.option(
+    "--all",
+    "show_all",
+    is_flag=True,
+    help="Show AGENTS.md for all packages that have them",
+)
+@click.option(
+    "--list",
+    "show_list",
+    is_flag=True,
+    help="List packages with AGENTS.md files",
+)
+def md(package, show_all, show_list):
+    """Show AGENTS.md for a package."""
+
+    agents_files = _get_packages_with_agents()
+
+    if show_list:
+        for pkg in sorted(agents_files.keys()):
+            click.echo(f"- {pkg}")
+
+        return
+
+    if show_all:
+        for pkg in sorted(agents_files.keys()):
+            agents_path = agents_files[pkg]
+            for line in iterate_markdown(agents_path.read_text()):
+                click.echo(line, nl=False)
+            print()
+
+        return
+
+    if not package:
+        raise click.UsageError(
+            "Package name or --all required. Use --list to see available packages."
+        )
+
+    agents_path = agents_files[package]
+    for line in iterate_markdown(agents_path.read_text()):
+        click.echo(line, nl=False)

plain-0.59.0/plain/cli/agent.py → plain-0.61.0/plain/cli/agent/prompt.py

@@ -5,24 +5,19 @@ import subprocess
 import click
 
 
+def is_agent_environment():
+    """Check if we're running inside a coding agent."""
+    return bool(
+        os.environ.get("CLAUDECODE")
+        or os.environ.get("CODEX_SANDBOX")
+        or os.environ.get("CURSOR_ENVIRONMENT")
+    )
+
+
 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.
-    """
-    # Check if running inside an agent and just print the prompt if so
-    if os.environ.get("CLAUDECODE") or os.environ.get("CODEX_SANDBOX"):
+    if is_agent_environment():
         click.echo(prompt)
         return True
 

plain-0.61.0/plain/cli/agent/request.py

@@ -0,0 +1,181 @@
+import json
+
+import click
+
+from plain.runtime import settings
+from plain.test import Client
+
+
+@click.command()
+@click.argument("path")
+@click.option(
+    "--method",
+    default="GET",
+    help="HTTP method (GET, POST, PUT, PATCH, DELETE, etc.)",
+)
+@click.option(
+    "--data",
+    help="Request data (JSON string for POST/PUT/PATCH)",
+)
+@click.option(
+    "--user",
+    "user_id",
+    help="User ID to authenticate as (skips normal authentication)",
+)
+@click.option(
+    "--follow/--no-follow",
+    default=True,
+    help="Follow redirects (default: True)",
+)
+@click.option(
+    "--content-type",
+    help="Content-Type header for request data",
+)
+@click.option(
+    "--header",
+    "headers",
+    multiple=True,
+    help="Additional headers (format: 'Name: Value')",
+)
+def request(path, method, data, user_id, follow, content_type, headers):
+    """Make an HTTP request using the test client against the development database."""
+
+    try:
+        # Only allow in DEBUG mode for security
+        if not settings.DEBUG:
+            click.secho("This command only works when DEBUG=True", fg="red", err=True)
+            return
+
+        # Temporarily add testserver to ALLOWED_HOSTS so the test client can make requests
+        original_allowed_hosts = settings.ALLOWED_HOSTS
+        settings.ALLOWED_HOSTS = ["*"]
+
+        try:
+            # Create test client
+            client = Client()
+
+            # If user_id provided, force login
+            if user_id:
+                try:
+                    # Get the User model using plain.auth utility
+                    from plain.auth import get_user_model
+
+                    User = get_user_model()
+
+                    # Get the user
+                    try:
+                        user = User.objects.get(id=user_id)
+                        client.force_login(user)
+                        click.secho(
+                            f"Authenticated as user {user_id}", fg="green", dim=True
+                        )
+                    except User.DoesNotExist:
+                        click.secho(f"User {user_id} not found", fg="red", err=True)
+                        return
+
+                except Exception as e:
+                    click.secho(f"Authentication error: {e}", fg="red", err=True)
+                    return
+
+            # Parse additional headers
+            header_dict = {}
+            for header in headers:
+                if ":" in header:
+                    key, value = header.split(":", 1)
+                    header_dict[key.strip()] = value.strip()
+
+            # Prepare request data
+            if data and content_type and "json" in content_type.lower():
+                try:
+                    # Validate JSON
+                    json.loads(data)
+                except json.JSONDecodeError as e:
+                    click.secho(f"Invalid JSON data: {e}", fg="red", err=True)
+                    return
+
+            # Make the request
+            method = method.upper()
+            kwargs = {
+                "path": path,
+                "follow": follow,
+                "headers": header_dict or None,
+            }
+
+            if method in ("POST", "PUT", "PATCH") and data:
+                kwargs["data"] = data
+                if content_type:
+                    kwargs["content_type"] = content_type
+
+            # Call the appropriate client method
+            if method == "GET":
+                response = client.get(**kwargs)
+            elif method == "POST":
+                response = client.post(**kwargs)
+            elif method == "PUT":
+                response = client.put(**kwargs)
+            elif method == "PATCH":
+                response = client.patch(**kwargs)
+            elif method == "DELETE":
+                response = client.delete(**kwargs)
+            elif method == "HEAD":
+                response = client.head(**kwargs)
+            elif method == "OPTIONS":
+                response = client.options(**kwargs)
+            elif method == "TRACE":
+                response = client.trace(**kwargs)
+            else:
+                click.secho(f"Unsupported HTTP method: {method}", fg="red", err=True)
+                return
+
+            # Display response information
+            click.secho(
+                f"HTTP {response.status_code}",
+                fg="green" if response.status_code < 400 else "red",
+                bold=True,
+            )
+
+            # Show additional response info first
+            if hasattr(response, "user"):
+                click.secho(f"Authenticated user: {response.user}", fg="blue", dim=True)
+
+            if hasattr(response, "resolver_match") and response.resolver_match:
+                match = response.resolver_match
+                url_name = match.namespaced_url_name or match.url_name or "unnamed"
+                click.secho(f"URL pattern matched: {url_name}", fg="blue", dim=True)
+
+            # Show headers
+            if response.headers:
+                click.secho("Response Headers:", fg="yellow", bold=True)
+                for key, value in response.headers.items():
+                    click.echo(f"  {key}: {value}")
+                click.echo()
+
+            # Show response content last
+            if response.content:
+                content_type = response.headers.get("Content-Type", "")
+
+                if "json" in content_type.lower():
+                    try:
+                        json_data = response.json()
+                        click.secho("Response Body (JSON):", fg="yellow", bold=True)
+                        click.echo(json.dumps(json_data, indent=2))
+                    except Exception:
+                        click.secho("Response Body:", fg="yellow", bold=True)
+                        click.echo(response.content.decode("utf-8", errors="replace"))
+                elif "html" in content_type.lower():
+                    click.secho("Response Body (HTML):", fg="yellow", bold=True)
+                    content = response.content.decode("utf-8", errors="replace")
+                    click.echo(content)
+                else:
+                    click.secho("Response Body:", fg="yellow", bold=True)
+                    content = response.content.decode("utf-8", errors="replace")
+                    click.echo(content)
+            else:
+                click.secho("(No response body)", fg="yellow", dim=True)
+
+        finally:
+            # Restore original ALLOWED_HOSTS
+            settings.ALLOWED_HOSTS = original_allowed_hosts
+
+    except Exception as e:
+        click.secho(f"Request failed: {e}", fg="red", err=True)

{plain-0.59.0 → plain-0.61.0}/plain/cli/core.py

@@ -6,12 +6,12 @@ from click.core import Command, Context
 import plain.runtime
 from plain.exceptions import ImproperlyConfigured
 
+from .agent import agent
 from .build import build
 from .changelog import changelog
 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
@@ -28,6 +28,7 @@ def plain_cli():
     pass
 
 
+plain_cli.add_command(agent)
 plain_cli.add_command(docs)
 plain_cli.add_command(preflight_checks)
 plain_cli.add_command(create)
@@ -41,7 +42,6 @@ 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)
 
 
 class CLIRegistryGroup(click.Group):

plain-0.61.0/plain/cli/docs.py

@@ -0,0 +1,38 @@
+import importlib.util
+from pathlib import Path
+
+import click
+
+from .output import iterate_markdown
+
+
+@click.command()
+@click.option("--open")
+@click.argument("module", default="")
+def docs(module, open):
+    if not module:
+        raise click.UsageError(
+            "You must specify a module. For LLM-friendly docs, use `plain agent docs`."
+        )
+
+    # 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}"
+
+    # Get the README.md file for the module
+    spec = importlib.util.find_spec(module)
+    if not spec:
+        raise click.UsageError(f"Module {module} not found")
+
+    module_path = Path(spec.origin).parent
+    readme_path = module_path / "README.md"
+    if not readme_path.exists():
+        raise click.UsageError(f"README.md not found for {module}")
+
+    if open:
+        click.launch(str(readme_path))
+    else:
+        click.echo_via_pager(iterate_markdown(readme_path.read_text()))

{plain-0.59.0 → plain-0.61.0}/plain/cli/install.py

@@ -3,7 +3,7 @@ import sys
 
 import click
 
-from .agent import prompt_agent
+from .agent.prompt import prompt_agent
 
 
 @click.command()