plain 0.68.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

plain/cli/{agent/request.py → request.py}

@@ -1,4 +1,7 @@
+from __future__ import annotations
+
 import json
+from typing import Any
 
 import click
 
@@ -37,8 +40,28 @@ from plain.test import Client
     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."""
+@click.option(
+    "--no-headers",
+    is_flag=True,
+    help="Hide response headers from output",
+)
+@click.option(
+    "--no-body",
+    is_flag=True,
+    help="Hide response body from output",
+)
+def request(
+    path: str,
+    method: str,
+    data: str | None,
+    user_id: str | None,
+    follow: bool,
+    content_type: str | None,
+    headers: tuple[str, ...],
+    no_headers: bool,
+    no_body: bool,
+) -> None:
+    """Make HTTP requests against the dev database"""
 
     try:
         # Only allow in DEBUG mode for security
@@ -61,9 +84,6 @@ def request(path, method, data, user_id, follow, content_type, headers):
                 try:
                     user = User.query.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
@@ -90,11 +110,11 @@ def request(path, method, data, user_id, follow, content_type, headers):
 
         # Make the request
         method = method.upper()
-        kwargs = {
-            "path": path,
+        kwargs: dict[str, Any] = {
             "follow": follow,
-            "headers": header_dict or None,
         }
+        if header_dict:
+            kwargs["headers"] = header_dict
 
         if method in ("POST", "PUT", "PATCH") and data:
             kwargs["data"] = data
@@ -103,57 +123,71 @@ def request(path, method, data, user_id, follow, content_type, headers):
 
         # Call the appropriate client method
         if method == "GET":
-            response = client.get(**kwargs)
+            response = client.get(path, **kwargs)
         elif method == "POST":
-            response = client.post(**kwargs)
+            response = client.post(path, **kwargs)
         elif method == "PUT":
-            response = client.put(**kwargs)
+            response = client.put(path, **kwargs)
         elif method == "PATCH":
-            response = client.patch(**kwargs)
+            response = client.patch(path, **kwargs)
         elif method == "DELETE":
-            response = client.delete(**kwargs)
+            response = client.delete(path, **kwargs)
         elif method == "HEAD":
-            response = client.head(**kwargs)
+            response = client.head(path, **kwargs)
         elif method == "OPTIONS":
-            response = client.options(**kwargs)
+            response = client.options(path, **kwargs)
         elif method == "TRACE":
-            response = client.trace(**kwargs)
+            response = client.trace(path, **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,
-        )
+        click.secho("Response:", fg="yellow", bold=True)
 
-        # Show additional response info first
-        if hasattr(response, "user"):
-            click.secho(f"Authenticated user: {response.user}", fg="blue", dim=True)
+        # Status code
+        click.echo(f"  Status: {response.status_code}")
 
-        if hasattr(response, "resolver_match") and response.resolver_match:
+        # Request ID
+        click.echo(f"  Request ID: {response.wsgi_request.unique_id}")
+
+        # User
+        if response.user:
+            click.echo(f"  Authenticated user: {response.user}")
+
+        # URL pattern
+        if 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)
+            namespaced_url_name = getattr(match, "namespaced_url_name", None)
+            url_name_attr = getattr(match, "url_name", None)
+            url_name = namespaced_url_name or url_name_attr
+            if url_name:
+                click.echo(f"  URL pattern: {url_name}")
+
+        click.echo()
 
         # Show headers
-        if response.headers:
+        if response.headers and not no_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:
+        if response.content and not no_body:
             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))
+                    # The test client adds a json() method to the response
+                    json_method = getattr(response, "json", None)
+                    if json_method and callable(json_method):
+                        json_data: Any = json_method()
+                        click.secho("Response Body (JSON):", fg="yellow", bold=True)
+                        click.echo(json.dumps(json_data, indent=2))
+                    else:
+                        click.secho("Response Body:", fg="yellow", bold=True)
+                        click.echo(response.content.decode("utf-8", errors="replace"))
                 except Exception:
                     click.secho("Response Body:", fg="yellow", bold=True)
                     click.echo(response.content.decode("utf-8", errors="replace"))
@@ -165,7 +199,7 @@ def request(path, method, data, user_id, follow, content_type, headers):
                 click.secho("Response Body:", fg="yellow", bold=True)
                 content = response.content.decode("utf-8", errors="replace")
                 click.echo(content)
-        else:
+        elif not no_body:
             click.secho("(No response body)", fg="yellow", dim=True)
 
     except Exception as e:

plain/cli/runtime.py

@@ -0,0 +1,45 @@
+"""
+CLI runtime utilities.
+
+This module provides decorators and utilities for CLI commands.
+"""
+
+from collections.abc import Callable
+from typing import TypeVar
+
+F = TypeVar("F", bound=Callable)
+
+
+def without_runtime_setup(f: F) -> F:
+    """
+    Decorator to mark commands that don't need plain.runtime.setup().
+
+    Use this for commands that don't access settings or app code,
+    particularly for commands that fork (like server) where setup()
+    should happen in the worker process, not the parent.
+
+    Example:
+        @without_runtime_setup
+        @click.command()
+        def server(**options):
+            ...
+    """
+    f.without_runtime_setup = True  # dynamic attribute for decorator
+    return f
+
+
+def common_command(f: F) -> F:
+    """
+    Decorator to mark commands as commonly used.
+
+    Common commands are shown in a separate "Common Commands" section
+    in the help output, making them easier to discover.
+
+    Example:
+        @common_command
+        @click.command()
+        def dev(**options):
+            ...
+    """
+    f.is_common_command = True  # dynamic attribute for decorator
+    return f

plain/cli/scaffold.py

@@ -7,13 +7,8 @@ import plain.runtime
 
 @click.command()
 @click.argument("package_name")
-def create(package_name):
-    """
-    Create a new local package.
-
-    The PACKAGE_NAME is typically a plural noun, like "users" or "posts",
-    where you might create a "User" or "Post" model inside of the package.
-    """
+def create(package_name: str) -> None:
+    """Create a new local package"""
     package_dir = plain.runtime.APP_PATH / package_name
     package_dir.mkdir(exist_ok=True)
 

plain/cli/server.py

@@ -0,0 +1,153 @@
+import os
+
+import click
+
+from plain.cli.runtime import without_runtime_setup
+
+
+def parse_workers(ctx: click.Context, param: click.Parameter, value: str) -> int:
+    """Parse workers value - accepts int or 'auto' for CPU count."""
+    if value == "auto":
+        return os.cpu_count() or 1
+    return int(value)
+
+
+@without_runtime_setup
+@click.command()
+@click.option(
+    "--bind",
+    "-b",
+    multiple=True,
+    default=["127.0.0.1:8000"],
+    help="Address to bind to (HOST:PORT, can be used multiple times)",
+)
+@click.option(
+    "--threads",
+    type=int,
+    default=1,
+    help="Number of threads per worker",
+    show_default=True,
+)
+@click.option(
+    "--workers",
+    "-w",
+    type=str,
+    default="1",
+    envvar="WEB_CONCURRENCY",
+    callback=parse_workers,
+    help="Number of worker processes (or 'auto' for CPU count)",
+    show_default=True,
+)
+@click.option(
+    "--timeout",
+    "-t",
+    type=int,
+    default=30,
+    help="Worker timeout in seconds",
+    show_default=True,
+)
+@click.option(
+    "--certfile",
+    type=click.Path(exists=True),
+    help="SSL certificate file",
+)
+@click.option(
+    "--keyfile",
+    type=click.Path(exists=True),
+    help="SSL key file",
+)
+@click.option(
+    "--log-level",
+    default="info",
+    type=click.Choice(["debug", "info", "warning", "error", "critical"]),
+    help="Logging level",
+    show_default=True,
+)
+@click.option(
+    "--reload",
+    is_flag=True,
+    help="Restart workers when code changes (dev only)",
+)
+@click.option(
+    "--access-log",
+    default="-",
+    help="Access log file (use '-' for stdout)",
+    show_default=True,
+)
+@click.option(
+    "--error-log",
+    default="-",
+    help="Error log file (use '-' for stderr)",
+    show_default=True,
+)
+@click.option(
+    "--log-format",
+    default="%(asctime)s [%(process)d] [%(levelname)s] %(message)s",
+    help="Log format string (applies to both error and access logs)",
+    show_default=True,
+)
+@click.option(
+    "--access-log-format",
+    help="Access log format string (HTTP request details)",
+    default='%(h)s %(l)s %(u)s %(t)s "%(r)s" %(s)s %(b)s "%(f)s" "%(a)s"',
+    show_default=True,
+)
+@click.option(
+    "--max-requests",
+    type=int,
+    default=0,
+    help="Max requests before worker restart (0=disabled)",
+    show_default=True,
+)
+@click.option(
+    "--pidfile",
+    type=click.Path(),
+    help="PID file path",
+)
+def server(
+    bind: tuple[str, ...],
+    threads: int,
+    workers: int,
+    timeout: int,
+    certfile: str | None,
+    keyfile: str | None,
+    log_level: str,
+    reload: bool,
+    access_log: str,
+    error_log: str,
+    log_format: str,
+    access_log_format: str,
+    max_requests: int,
+    pidfile: str | None,
+) -> None:
+    """Production-ready WSGI server"""
+    from plain.runtime import settings
+
+    # Show settings loaded from environment
+    if env_settings := settings.get_env_settings():
+        click.secho("Settings from env:", dim=True)
+        for name, defn in env_settings:
+            click.secho(
+                f"  {defn.env_var_name} -> {name}={defn.display_value()}", dim=True
+            )
+
+    from plain.server import ServerApplication
+    from plain.server.config import Config
+
+    cfg = Config(
+        bind=list(bind),
+        threads=threads,
+        workers=workers,
+        timeout=timeout,
+        max_requests=max_requests,
+        reload=reload,
+        pidfile=pidfile,
+        certfile=certfile,
+        keyfile=keyfile,
+        loglevel=log_level,
+        accesslog=access_log,
+        errorlog=error_log,
+        log_format=log_format,
+        access_log_format=access_log_format,
+    )
+    ServerApplication(cfg=cfg).run()

plain/cli/settings.py

@@ -3,58 +3,62 @@ import click
 import plain.runtime
 
 
-@click.command()
+@click.group()
+def settings() -> None:
+    """View and inspect settings"""
+    pass
+
+
+@settings.command()
 @click.argument("setting_name")
-def setting(setting_name):
-    """Print the value of a setting at runtime"""
+def get(setting_name: str) -> None:
+    """Get the value of a specific setting"""
     try:
-        setting = getattr(plain.runtime.settings, setting_name)
-        click.echo(setting)
+        value = getattr(plain.runtime.settings, setting_name)
+        click.echo(value)
     except AttributeError:
         click.secho(f'Setting "{setting_name}" not found', fg="red")
 
 
-# @plain_cli.command()
-# @click.option("--filter", "-f", "name_filter", help="Filter settings by name")
-# @click.option("--overridden", is_flag=True, help="Only show overridden settings")
-# def settings(name_filter, overridden):
-#     """Print Plain settings"""
-#     table = Table(box=box.MINIMAL)
-#     table.add_column("Setting")
-#     table.add_column("Default value")
-#     table.add_column("App value")
-#     table.add_column("Type")
-#     table.add_column("Module")
-
-#     for setting in dir(settings):
-#         if setting.isupper():
-#             if name_filter and name_filter.upper() not in setting:
-#                 continue
-
-#             is_overridden = settings.is_overridden(setting)
-
-#             if overridden and not is_overridden:
-#                 continue
-
-#             default_setting = settings._default_settings.get(setting)
-#             if default_setting:
-#                 default_value = default_setting.value
-#                 annotation = default_setting.annotation
-#                 module = default_setting.module
-#             else:
-#                 default_value = ""
-#                 annotation = ""
-#                 module = ""
-
-#             table.add_row(
-#                 setting,
-#                 Pretty(default_value) if default_value else "",
-#                 Pretty(getattr(settings, setting))
-#                 if is_overridden
-#                 else Text("<Default>", style="italic dim"),
-#                 Pretty(annotation) if annotation else "",
-#                 str(module.__name__) if module else "",
-#             )
-
-#     console = Console()
-#     console.print(table)
+@settings.command(name="list")
+def list_settings() -> None:
+    """List all settings with their sources"""
+    if not (items := plain.runtime.settings.get_settings()):
+        click.echo("No settings configured.")
+        return
+
+    # Calculate column widths
+    max_name = max(len(name) for name, _ in items)
+    max_source = max(len(defn.env_var_name or defn.source) for _, defn in items)
+
+    # Print header
+    header = (
+        click.style(f"{'Setting':<{max_name}}", bold=True)
+        + "  "
+        + click.style(f"{'Source':<{max_source}}", bold=True)
+        + "  "
+        + click.style("Value", bold=True)
+    )
+    click.echo(header)
+    click.secho("-" * (max_name + max_source + 10), dim=True)
+
+    # Print each setting
+    for name, defn in items:
+        source_info = defn.env_var_name or defn.source
+        value = defn.display_value()
+
+        # Style based on source
+        if defn.source == "env":
+            source_styled = click.style(f"{source_info:<{max_source}}", fg="green")
+        elif defn.source == "explicit":
+            source_styled = click.style(f"{source_info:<{max_source}}", fg="cyan")
+        else:
+            source_styled = click.style(f"{source_info:<{max_source}}", dim=True)
+
+        # Style secret values
+        if defn.is_secret:
+            value_styled = click.style(value, dim=True)
+        else:
+            value_styled = value
+
+        click.echo(f"{name:<{max_name}}  {source_styled}  {value_styled}")

plain/cli/shell.py

@@ -1,10 +1,15 @@
+from __future__ import annotations
+
 import os
 import subprocess
 import sys
 
 import click
 
+from plain.cli.runtime import common_command
+
 
+@common_command
 @click.command()
 @click.option(
     "-i",
@@ -17,11 +22,8 @@ import click
     "--command",
     help="Execute the given command and exit.",
 )
-def shell(interface, command):
-    """
-    Runs a Python interactive interpreter. Tries to use IPython or
-    bpython, if one of them is available.
-    """
+def shell(interface: str | None, command: str | None) -> None:
+    """Interactive Python shell"""
 
     if command:
         # Execute the command and exit
@@ -32,13 +34,14 @@ def shell(interface, command):
             sys.exit(result.returncode)
         return
 
+    interface_list: list[str]
     if interface:
-        interface = [interface]
+        interface_list = [interface]
     else:
 
-        def get_default_interface():
+        def get_default_interface() -> list[str]:
             try:
-                import IPython  # noqa
+                import IPython  # noqa: F401  # type: ignore[import-not-found]
 
                 return ["python", "-m", "IPython"]
             except ImportError:
@@ -46,10 +49,10 @@ def shell(interface, command):
 
             return ["python"]
 
-        interface = get_default_interface()
+        interface_list = get_default_interface()
 
     result = subprocess.run(
-        interface,
+        interface_list,
         env={
             "PYTHONSTARTUP": os.path.join(os.path.dirname(__file__), "startup.py"),
             **os.environ,
@@ -61,8 +64,8 @@ def shell(interface, command):
 
 @click.command()
 @click.argument("script", nargs=1, type=click.Path(exists=True))
-def run(script):
-    """Run a Python script in the context of your app"""
+def run(script: str) -> None:
+    """Execute Python scripts with app context"""
     before_script = "import plain.runtime; plain.runtime.setup()"
     command = f"{before_script}; exec(open('{script}').read())"
     result = subprocess.run(["python", "-c", command])

plain/cli/startup.py

@@ -3,19 +3,19 @@ import plain.runtime
 plain.runtime.setup()
 
 
-def print_bold(s):
+def print_bold(s: str) -> None:
     print("\033[1m", end="")
     print(s)
     print("\033[0m", end="")
 
 
-def print_italic(s):
+def print_italic(s: str) -> None:
     print("\x1b[3m", end="")
     print(s)
     print("\x1b[0m", end="")
 
 
-def print_dim(s):
+def print_dim(s: str) -> None:
     print("\x1b[2m", end="")
     print(s)
     print("\x1b[0m", end="")
@@ -29,12 +29,13 @@ if shell_import := plain.runtime.settings.SHELL_IMPORT:
     print_bold(f"Importing {shell_import}")
     module = import_module(shell_import)
 
-    with open(module.__file__) as f:
-        contents = f.read()
-        for line in contents.splitlines():
-            print_dim(f"{line}")
+    if module.__file__:
+        with open(module.__file__) as f:
+            contents = f.read()
+            for line in contents.splitlines():
+                print_dim(f"{line}")
 
-    print()
+        print()
 
     # Emulate `from module import *`
     names = getattr(