plain 0.60.0__py3-none-any.whl → 0.62.0__py3-none-any.whl

plain/AGENTS.md

@@ -0,0 +1,18 @@
+# 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).
+
+## Code style
+
+- Imports should be at the top of the file, unless there is a specific reason to import later (e.g. to avoid circular imports).

plain/CHANGELOG.md

@@ -1,5 +1,31 @@
 # plain changelog
 
+## [0.62.0](https://github.com/dropseed/plain/releases/plain@0.62.0) (2025-09-09)
+
+### What's changed
+
+- Complete rewrite of logging settings and AppLogger with improved formatters and debug capabilities ([ea7c953](https://github.com/dropseed/plain/commit/ea7c9537e3))
+- Added `app_logger.debug_mode()` context manager to temporarily change log level ([f535459](https://github.com/dropseed/plain/commit/f53545f9fa))
+- Minimum Python version updated to 3.13 ([d86e307](https://github.com/dropseed/plain/commit/d86e307efb))
+
+### Upgrade instructions
+
+- Make sure you are using Python 3.13 or higher
+
+## [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

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/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/cli/agent/llmdocs.py

@@ -0,0 +1,145 @@
+import ast
+from pathlib import Path
+
+import click
+
+
+class LLMDocs:
+    """Generates LLM-friendly documentation."""
+
+    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
+        # Also exclude CHANGELOG.md and AGENTS.md
+        self.docs = {
+            doc
+            for doc in self.docs
+            if not (
+                "/migrations/" in str(doc)
+                and "/plain/models/migrations/" not in str(doc)
+            )
+            and doc.name not in ("CHANGELOG.md", "AGENTS.md")
+        }
+        self.sources = {
+            source
+            for source in self.sources
+            if not (
+                "/migrations/" in str(source)
+                and "/plain/models/migrations/" not in str(source)
+            )
+            and source.name != "cli.py"
+        }
+
+        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):
+        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("_"):
+                    return True
+            elif isinstance(node, ast.Assign):
+                for target in node.targets:
+                    if isinstance(target, ast.Name) and target.id.startswith("_"):
+                        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)})")
+                for child in node.body:
+                    child_lines = process_node(child, indent + 1)
+                    if child_lines:
+                        lines.extend(child_lines)
+
+            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})")
+
+            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/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/cli/{agent.py → 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/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/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):