plain 0.61.0__tar.gz → 0.62.0__tar.gz

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

@@ -1,10 +1,10 @@
 Metadata-Version: 2.4
 Name: plain
-Version: 0.61.0
+Version: 0.62.0
 Summary: A web framework for building products with Python.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-File: LICENSE
-Requires-Python: >=3.11
+Requires-Python: >=3.13
 Requires-Dist: click>=8.0.0
 Requires-Dist: jinja2>=3.1.2
 Requires-Dist: opentelemetry-api>=1.34.1

{plain-0.61.0 → plain-0.62.0}/plain/AGENTS.md

@@ -11,4 +11,8 @@ The `plain` CLI is the main entrypoint for the framework. If `plain` is not avai
 - `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 --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-0.61.0 → plain-0.62.0}/plain/CHANGELOG.md

@@ -1,5 +1,17 @@
 # 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

{plain-0.61.0 → plain-0.62.0}/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-0.61.0 → plain-0.62.0}/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-0.61.0 → plain-0.62.0}/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-0.62.0/plain/logs/README.md

@@ -0,0 +1,139 @@
+# Logs
+
+**Logging configuration and utilities.**
+
+- [Overview](#overview)
+- [`app_logger`](#app_logger)
+- [Output formats](#output-formats)
+- [Context management](#context-management)
+- [Debug mode](#debug-mode)
+- [Advanced usage](#advanced-usage)
+- [Logging settings](#logging-settings)
+
+## Overview
+
+In Python, configuring logging can be surprisingly complex. For most use cases, Plain provides a [default configuration](./configure.py) that "just works".
+
+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 an enhanced logger that supports kwargs-style logging and multiple output formats.
+
+```python
+from plain.logs import app_logger
+
+
+def example_function():
+    # 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"
+        )
+```
+
+## Output formats
+
+The `app_logger` supports three output formats controlled by the `APP_LOG_FORMAT` environment variable:
+
+### 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
+# 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
+
+# Clear context
+app_logger.context.clear()
+```
+
+### Temporary context
+
+Use `include_context()` for temporary context that only applies within a block:
+
+```python
+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-0.62.0/plain/logs/__init__.py

@@ -0,0 +1,3 @@
+from .loggers import app_logger
+
+__all__ = ["app_logger"]

plain-0.62.0/plain/logs/configure.py

@@ -0,0 +1,36 @@
+import logging
+
+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-0.62.0/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-0.62.0/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)

plain-0.62.0/plain/logs/loggers.py

@@ -0,0 +1,183 @@
+import logging
+from contextlib import contextmanager
+
+from .debug import DebugMode
+
+
+class AppLogger(logging.Logger):
+    """Enhanced logger that supports kwargs-style logging and context management."""
+
+    def __init__(self, name):
+        super().__init__(name)
+        self.context = {}  # Public, mutable context dict
+        self.debug_mode = DebugMode(self)
+
+    @contextmanager
+    def include_context(self, **kwargs):
+        """Context manager for temporary context."""
+        # Store original context
+        original_context = self.context.copy()
+
+        # Add temporary context
+        self.context.update(kwargs)
+
+        try:
+            yield
+        finally:
+            # Restore original context
+            self.context = original_context
+
+    def force_debug(self):
+        """Return context manager for temporarily enabling DEBUG level logging."""
+        return self.debug_mode
+
+    # Override logging methods with explicit parameters for IDE support
+    def debug(
+        self,
+        msg,
+        *args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        if self.isEnabledFor(logging.DEBUG):
+            self._log(
+                logging.DEBUG,
+                msg,
+                args,
+                exc_info=exc_info,
+                extra=extra,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                **context,
+            )
+
+    def info(
+        self,
+        msg,
+        *args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        if self.isEnabledFor(logging.INFO):
+            self._log(
+                logging.INFO,
+                msg,
+                args,
+                exc_info=exc_info,
+                extra=extra,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                **context,
+            )
+
+    def warning(
+        self,
+        msg,
+        *args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        if self.isEnabledFor(logging.WARNING):
+            self._log(
+                logging.WARNING,
+                msg,
+                args,
+                exc_info=exc_info,
+                extra=extra,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                **context,
+            )
+
+    def error(
+        self,
+        msg,
+        *args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        if self.isEnabledFor(logging.ERROR):
+            self._log(
+                logging.ERROR,
+                msg,
+                args,
+                exc_info=exc_info,
+                extra=extra,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                **context,
+            )
+
+    def critical(
+        self,
+        msg,
+        *args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        if self.isEnabledFor(logging.CRITICAL):
+            self._log(
+                logging.CRITICAL,
+                msg,
+                args,
+                exc_info=exc_info,
+                extra=extra,
+                stack_info=stack_info,
+                stacklevel=stacklevel,
+                **context,
+            )
+
+    def _log(
+        self,
+        level,
+        msg,
+        args,
+        exc_info=None,
+        extra=None,
+        stack_info=False,
+        stacklevel=1,
+        **context,
+    ):
+        """Low-level logging routine which creates a LogRecord and then calls all handlers."""
+        # Check if extra already has a 'context' key
+        if extra and "context" in extra:
+            raise ValueError(
+                "The 'context' key in extra is reserved for Plain's context system"
+            )
+
+        # Build final extra with context
+        extra = extra.copy() if extra else {}
+
+        # Add our context (persistent + kwargs) to extra["context"]
+        if self.context or context:
+            extra["context"] = {**self.context, **context}
+
+        # Call the parent logger's _log method with explicit parameters
+        super()._log(
+            level=level,
+            msg=msg,
+            args=args,
+            exc_info=exc_info,
+            extra=extra or None,
+            stack_info=stack_info,
+            stacklevel=stacklevel,
+        )
+
+
+# Create the default app logger instance
+app_logger = AppLogger("app")

{plain-0.61.0 → plain-0.62.0}/plain/runtime/__init__.py

@@ -3,6 +3,9 @@ import sys
 from importlib.metadata import entry_points
 from pathlib import Path
 
+from plain.logs.configure import configure_logging
+from plain.packages import packages_registry
+
 from .user_settings import Settings
 
 try:
@@ -48,9 +51,6 @@ def setup():
     for entry_point in entry_points().select(group="plain.setup"):
         entry_point.load()()
 
-    from plain.logs import configure_logging
-    from plain.packages import packages_registry
-
     if not APP_PATH.exists():
         raise AppPathNotFound(
             "No app directory found. Are you sure you're in a Plain project?"
@@ -62,7 +62,11 @@ def setup():
     if APP_PATH.parent.as_posix() not in sys.path:
         sys.path.insert(0, APP_PATH.parent.as_posix())
 
-    configure_logging(settings.LOGGING)
+    configure_logging(
+        plain_log_level=settings.PLAIN_LOG_LEVEL,
+        app_log_level=settings.APP_LOG_LEVEL,
+        app_log_format=settings.APP_LOG_FORMAT,
+    )
 
     packages_registry.populate(settings.INSTALLED_PACKAGES)
 

{plain-0.61.0 → plain-0.62.0}/plain/runtime/global_settings.py

@@ -3,6 +3,8 @@ Default Plain settings. Override these with settings in the module pointed to
 by the PLAIN_SETTINGS_MODULE environment variable.
 """
 
+from os import environ
+
 from .utils import get_app_info_from_pyproject
 
 # MARK: Core Settings
@@ -137,9 +139,11 @@ CSRF_TRUSTED_ORIGINS: list[str] = []
 CSRF_EXEMPT_PATHS: list[str] = []
 
 # MARK: Logging
+# (Uses some custom env names in addition to PLAIN_ prefixed )
 
-# Custom logging configuration.
-LOGGING = {}
+PLAIN_LOG_LEVEL: str = environ.get("PLAIN_LOG_LEVEL", "INFO")
+APP_LOG_LEVEL: str = environ.get("APP_LOG_LEVEL", "INFO")
+APP_LOG_FORMAT: str = environ.get("APP_LOG_FORMAT", "keyvalue")
 
 # MARK: Assets
 

{plain-0.61.0 → plain-0.62.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain"
-version = "0.61.0"
+version = "0.62.0"
 description = "A web framework for building products with Python."
 authors = [{name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev"}]
 readme = "README.md"
@@ -10,7 +10,7 @@ dependencies = [
     "opentelemetry-api>=1.34.1",
     "opentelemetry-semantic-conventions>=0.55b1",
 ]
-requires-python = ">=3.11"
+requires-python = ">=3.13"
 
 [project.scripts]
 plain = "plain.cli.core:cli"