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

plain/cli/docs.py

@@ -1,218 +1,38 @@
-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",
+def docs(module, open):
+    if not module:
+        raise click.UsageError(
+            "You must specify a module. For LLM-friendly docs, use `plain agent docs`."
         )
 
-        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"
-    )
-
-    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
-        self.docs = {
-            doc
-            for doc in self.docs
-            if not (
-                "/migrations/" in str(doc)
-                and "/plain/models/migrations/" not in str(doc)
-            )
-        }
-        self.sources = {
-            source
-            for source in self.sources
-            if not (
-                "/migrations/" in str(source)
-                and "/plain/models/migrations/" not in str(source)
-            )
-        }
-
-        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):
-        click.secho(self.preamble, fg="yellow")
-
-        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("_"):  # and not node.name.endswith("__"):
-                    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("__")
-                    ):
-                        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)})")
-                # 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")
+    # Convert hyphens to dots (e.g., plain-models -> plain.models)
+    module = module.replace("-", ".")
 
-            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)}")
+    # Automatically prefix if we need to
+    if not module.startswith("plain"):
+        module = f"plain.{module}"
 
-            return lines
+    # 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")
 
-        symbolicated_lines = []
-        for node in parsed.body:
-            symbolicated_lines.extend(process_node(node))
+    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}")
 
-        return "\n".join(symbolicated_lines)
+    if open:
+        click.launch(str(readme_path))
+    else:
+        click.echo_via_pager(iterate_markdown(readme_path.read_text()))

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()

plain/cli/shell.py

@@ -12,12 +12,26 @@ import click
     type=click.Choice(["ipython", "bpython", "python"]),
     help="Specify an interactive interpreter interface.",
 )
-def shell(interface):
+@click.option(
+    "-c",
+    "--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.
     """
 
+    if command:
+        # Execute the command and exit
+        before_script = "import plain.runtime; plain.runtime.setup()"
+        full_command = f"{before_script}; {command}"
+        result = subprocess.run(["python", "-c", full_command])
+        if result.returncode:
+            sys.exit(result.returncode)
+        return
+
     if interface:
         interface = [interface]
     else:

plain/cli/upgrade.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 import click
 
-from .agent import prompt_agent
+from .agent.prompt import prompt_agent
 
 LOCK_FILE = Path("uv.lock")
 

plain/csrf/middleware.py

@@ -3,7 +3,7 @@ import re
 from urllib.parse import urlparse
 
 from plain.exceptions import DisallowedHost
-from plain.logs import log_response
+from plain.logs.utils import log_response
 from plain.runtime import settings
 
 from .views import CsrfFailureView

plain/internal/handlers/base.py

@@ -5,7 +5,7 @@ from opentelemetry import baggage, trace
 from opentelemetry.semconv.attributes import http_attributes, url_attributes
 
 from plain.exceptions import ImproperlyConfigured
-from plain.logs import log_response
+from plain.logs.utils import log_response
 from plain.runtime import settings
 from plain.urls import get_resolver
 from plain.utils.module_loading import import_string

plain/internal/handlers/exception.py

@@ -12,7 +12,7 @@ from plain.exceptions import (
 )
 from plain.http import Http404, ResponseServerError
 from plain.http.multipartparser import MultiPartParserError
-from plain.logs import log_response
+from plain.logs.utils import log_response
 from plain.runtime import settings
 from plain.utils.module_loading import import_string
 from plain.views.errors import ErrorView

plain/logs/README.md

@@ -4,7 +4,10 @@
 
 - [Overview](#overview)
 - [`app_logger`](#app_logger)
-- [`app_logger.kv`](#app_loggerkv)
+- [Output formats](#output-formats)
+- [Context management](#context-management)
+- [Debug mode](#debug-mode)
+- [Advanced usage](#advanced-usage)
 - [Logging settings](#logging-settings)
 
 ## Overview
@@ -13,49 +16,124 @@ In Python, configuring logging can be surprisingly complex. For most use cases,
 
 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.
 
+The `app_logger` supports multiple output formats and provides a friendly kwargs-based API for structured logging.
+
 ## `app_logger`
 
-The `app_logger` is a pre-configured logger you can use inside your app code.
+The `app_logger` is an enhanced logger that supports kwargs-style logging and multiple output formats.
 
 ```python
 from plain.logs import app_logger
 
 
 def example_function():
-    app_logger.info("Hey!")
+    # Basic logging
+    app_logger.info("User logged in")
+
+    # With structured context data (explicit **context parameter)
+    app_logger.info("User action", user_id=123, action="login", success=True)
+
+    # All log levels support context parameters
+    app_logger.debug("Debug info", step="validation", count=5)
+    app_logger.warning("Rate limit warning", user_id=456, limit_exceeded=True)
+    app_logger.error("Database error", error_code=500, table="users")
+
+    # Standard logging parameters with context
+    try:
+        risky_operation()
+    except Exception:
+        app_logger.error(
+            "Operation failed",
+            exc_info=True,  # Include exception traceback
+            stack_info=True,  # Include stack trace
+            user_id=789,
+            operation="risky_operation"
+        )
 ```
 
-## `app_logger.kv`
+## Output formats
+
+The `app_logger` supports three output formats controlled by the `APP_LOG_FORMAT` environment variable:
 
-The key-value logging format is popular for outputting more structured logs that are still human-readable.
+### Key-Value format (default)
+
+```bash
+export APP_LOG_FORMAT=keyvalue  # or leave unset for default
+```
+
+```
+[INFO] User action user_id=123 action=login success=True
+[ERROR] Database error error_code=500 table=users
+```
+
+### JSON format
+
+```bash
+export APP_LOG_FORMAT=json
+```
+
+```json
+{"timestamp": "2024-01-01 12:00:00,123", "level": "INFO", "message": "User action", "user_id": 123, "action": "login", "success": true}
+{"timestamp": "2024-01-01 12:00:01,456", "level": "ERROR", "message": "Database error", "error_code": 500, "table": "users"}
+```
+
+### Standard format
+
+```bash
+export APP_LOG_FORMAT=standard
+```
+
+```
+[INFO] User action
+[ERROR] Database error
+```
+
+Note: In standard format, the context kwargs are ignored and not displayed.
+
+## Context management
+
+The `app_logger` provides powerful context management for adding data to multiple log statements.
+
+### Persistent context
+
+Use the `context` dict to add data that persists across log calls:
 
 ```python
-from plain.logs import app_logger
+# Set persistent context
+app_logger.context["user_id"] = 123
+app_logger.context["request_id"] = "abc456"
 
+app_logger.info("Started processing")      # Includes user_id and request_id
+app_logger.info("Validation complete")     # Includes user_id and request_id
+app_logger.info("Processing finished")     # Includes user_id and request_id
 
-def example_function():
-    app_logger.kv("Example log line with", example_key="example_value")
+# Clear context
+app_logger.context.clear()
 ```
 
-## Logging settings
+### Temporary context
 
-You can further configure your logging with `settings.LOGGING`.
+Use `include_context()` for temporary context that only applies within a block:
 
 ```python
-# app/settings.py
-LOGGING = {
-    "version": 1,
-    "disable_existing_loggers": False,
-    "handlers": {
-        "console": {
-            "class": "logging.StreamHandler",
-        },
-    },
-    "loggers": {
-        "mylogger": {
-            "handlers": ["console"],
-            "level": "DEBUG",
-        },
-    },
-}
+app_logger.context["user_id"] = 123  # Persistent
+
+with app_logger.include_context(operation="payment", transaction_id="txn789"):
+    app_logger.info("Payment started")     # Has user_id, operation, transaction_id
+    app_logger.info("Payment validated")   # Has user_id, operation, transaction_id
+
+app_logger.info("Payment complete")        # Only has user_id
+```
+
+## Debug mode
+
+The `force_debug()` context manager allows temporarily enabling DEBUG level logging:
+
+```python
+# Debug messages might not show at INFO level
+app_logger.debug("This might not appear")
+
+# Temporarily enable debug logging
+with app_logger.force_debug():
+    app_logger.debug("This will definitely appear", extra_data="debug_info")
 ```

plain/logs/__init__.py

@@ -1,5 +1,3 @@
-from .configure import configure_logging
 from .loggers import app_logger
-from .utils import log_response
 
-__all__ = ["app_logger", "log_response", "configure_logging"]
+__all__ = ["app_logger"]

plain/logs/configure.py

@@ -1,44 +1,36 @@
 import logging
-import logging.config
-from os import environ
-
-
-def configure_logging(logging_settings):
-    # Load the defaults
-    default_logging = {
-        "version": 1,
-        "disable_existing_loggers": False,
-        "formatters": {
-            "simple": {
-                "format": "[%(levelname)s] %(message)s",
-            },
-        },
-        "handlers": {
-            "plain_console": {
-                "level": environ.get("PLAIN_LOG_LEVEL", "INFO"),
-                "class": "logging.StreamHandler",
-                "formatter": "simple",
-            },
-            "app_console": {
-                "level": environ.get("APP_LOG_LEVEL", "INFO"),
-                "class": "logging.StreamHandler",
-                "formatter": "simple",
-            },
-        },
-        "loggers": {
-            "plain": {
-                "handlers": ["plain_console"],
-                "level": environ.get("PLAIN_LOG_LEVEL", "INFO"),
-            },
-            "app": {
-                "handlers": ["app_console"],
-                "level": environ.get("APP_LOG_LEVEL", "INFO"),
-                "propagate": False,
-            },
-        },
-    }
-    logging.config.dictConfig(default_logging)
-
-    # Then customize it from settings
-    if logging_settings:
-        logging.config.dictConfig(logging_settings)
+
+from .formatters import JSONFormatter, KeyValueFormatter
+
+
+def configure_logging(*, plain_log_level, app_log_level, app_log_format):
+    # Create and configure the plain logger (uses standard Logger, not AppLogger)
+    plain_logger = logging.Logger("plain")
+    plain_logger.setLevel(plain_log_level)
+    plain_handler = logging.StreamHandler()
+    plain_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+    plain_logger.addHandler(plain_handler)
+    plain_logger.propagate = False
+    logging.root.manager.loggerDict["plain"] = plain_logger
+
+    # Configure the existing app_logger
+    from .loggers import app_logger
+
+    app_logger.setLevel(app_log_level)
+    app_logger.propagate = False
+
+    app_handler = logging.StreamHandler()
+    match app_log_format:
+        case "json":
+            app_handler.setFormatter(JSONFormatter("%(json)s"))
+        case "keyvalue":
+            app_handler.setFormatter(
+                KeyValueFormatter("[%(levelname)s] %(message)s %(keyvalue)s")
+            )
+        case _:
+            app_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+
+    app_logger.addHandler(app_handler)
+
+    # Register the app_logger in the logging system so getLogger("app") returns it
+    logging.root.manager.loggerDict["app"] = app_logger

plain/logs/debug.py

@@ -0,0 +1,36 @@
+import logging
+import threading
+
+
+class DebugMode:
+    """Context manager to temporarily set DEBUG level on a logger with reference counting."""
+
+    def __init__(self, logger):
+        self.logger = logger
+        self.original_level = None
+        self._ref_count = 0
+        self._lock = threading.Lock()
+
+    def __enter__(self):
+        """Store original level and set to DEBUG."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Restore original level."""
+        self.end()
+
+    def start(self):
+        """Enable DEBUG logging level."""
+        with self._lock:
+            if self._ref_count == 0:
+                self.original_level = self.logger.level
+                self.logger.setLevel(logging.DEBUG)
+            self._ref_count += 1
+
+    def end(self):
+        """Restore original logging level."""
+        with self._lock:
+            self._ref_count = max(0, self._ref_count - 1)
+            if self._ref_count == 0:
+                self.logger.setLevel(self.original_level)

plain/logs/formatters.py

@@ -0,0 +1,70 @@
+import json
+import logging
+
+
+class KeyValueFormatter(logging.Formatter):
+    """Formatter that outputs key-value pairs from Plain's context system."""
+
+    def format(self, record):
+        # Build key-value pairs from context
+        kv_pairs = []
+
+        # Look for Plain's context data
+        if hasattr(record, "context") and isinstance(record.context, dict):
+            for key, value in record.context.items():
+                formatted_value = self._format_value(value)
+                kv_pairs.append(f"{key}={formatted_value}")
+
+        # Add the keyvalue attribute to the record for %(keyvalue)s substitution
+        record.keyvalue = " ".join(kv_pairs)
+
+        # Let the parent formatter handle the format string with %(keyvalue)s
+        return super().format(record)
+
+    @staticmethod
+    def _format_value(value):
+        """Format a value for key-value output."""
+        if isinstance(value, str):
+            s = value
+        else:
+            s = str(value)
+
+        if '"' in s:
+            # Escape quotes and surround it
+            s = s.replace('"', '\\"')
+            s = f'"{s}"'
+        elif s == "":
+            # Quote empty strings instead of printing nothing
+            s = '""'
+        elif any(char in s for char in [" ", "/", "'", ":", "=", "."]):
+            # Surround these with quotes for parsers
+            s = f'"{s}"'
+
+        return s
+
+
+class JSONFormatter(logging.Formatter):
+    """Formatter that outputs JSON from Plain's context system, with optional format string."""
+
+    def format(self, record):
+        # Build the JSON object from Plain's context data
+        log_obj = {
+            "timestamp": self.formatTime(record),
+            "level": record.levelname,
+            "message": record.getMessage(),
+            "logger": record.name,
+        }
+
+        # Add Plain's context data to the main JSON object
+        if hasattr(record, "context") and isinstance(record.context, dict):
+            log_obj.update(record.context)
+
+        # Handle exceptions
+        if record.exc_info:
+            log_obj["exception"] = self.formatException(record.exc_info)
+
+        # Add the json attribute to the record for %(json)s substitution
+        record.json = json.dumps(log_obj, default=str, ensure_ascii=False)
+
+        # Let the parent formatter handle the format string with %(json)s
+        return super().format(record)