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

plain/logs/README.md

@@ -1,139 +1,238 @@
 # Logs
 
-**Logging configuration and utilities.**
+**Structured logging with sensible defaults and zero configuration.**
 
 - [Overview](#overview)
-- [`app_logger`](#app_logger)
+- [Using app_logger](#using-app_logger)
+    - [Basic logging](#basic-logging)
+    - [Adding context](#adding-context)
 - [Output formats](#output-formats)
+    - [Key-value format](#key-value-format)
+    - [JSON format](#json-format)
+    - [Standard format](#standard-format)
 - [Context management](#context-management)
+    - [Persistent context](#persistent-context)
+    - [Temporary context](#temporary-context)
 - [Debug mode](#debug-mode)
-- [Advanced usage](#advanced-usage)
-- [Logging settings](#logging-settings)
+- [Output streams](#output-streams)
+- [Settings reference](#settings-reference)
+- [FAQs](#faqs)
+- [Installation](#installation)
 
 ## Overview
 
-In Python, configuring logging can be surprisingly complex. For most use cases, Plain provides a [default configuration](./configure.py) that "just works".
+Python's logging module is powerful but notoriously difficult to configure. Plain provides a ready-to-use logging setup that works out of the box while supporting structured logging for production environments.
 
-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.
+You get two pre-configured loggers: `plain` (for framework internals) and `app` (for your application code). Both default to the `INFO` level and can be adjusted via environment variables.
 
-The `app_logger` supports multiple output formats and provides a friendly kwargs-based API for structured logging.
+```python
+from plain.logs import app_logger
+
+# Simple message logging
+app_logger.info("Application started")
+
+# Structured logging with context data
+app_logger.info("User logged in", context={"user_id": 123, "method": "oauth"})
+
+# All log levels work the same way
+app_logger.warning("Rate limit approaching", context={"requests": 95, "limit": 100})
+app_logger.error("Payment failed", context={"order_id": "abc-123", "reason": "insufficient_funds"})
+```
+
+## Using app_logger
 
-## `app_logger`
+### Basic logging
 
-The `app_logger` is an enhanced logger that supports kwargs-style logging and multiple output formats.
+The [`app_logger`](./app.py#AppLogger) supports all standard logging levels: `debug`, `info`, `warning`, `error`, and `critical`.
 
 ```python
-from plain.logs import app_logger
+app_logger.debug("Entering validation step")
+app_logger.info("Request processed successfully")
+app_logger.warning("Cache miss, falling back to database")
+app_logger.error("Failed to connect to external service")
+app_logger.critical("Database connection pool exhausted")
+```
 
+### Adding context
 
-def example_function():
-    # Basic logging
-    app_logger.info("User logged in")
+Pass structured data using the `context` parameter. This data appears in your log output based on your chosen format.
 
-    # With structured context data (explicit **context parameter)
-    app_logger.info("User action", user_id=123, action="login", success=True)
+```python
+app_logger.info("Order placed", context={
+    "order_id": "ord-456",
+    "items": 3,
+    "total": 99.99,
+})
+```
 
-    # 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")
+You can also include exception tracebacks:
 
-    # 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"
-        )
+```python
+try:
+    process_payment()
+except PaymentError:
+    app_logger.error(
+        "Payment processing failed",
+        exc_info=True,
+        context={"order_id": "ord-456"},
+    )
 ```
 
 ## Output formats
 
-The `app_logger` supports three output formats controlled by the `APP_LOG_FORMAT` environment variable:
+Control the log format with the `APP_LOG_FORMAT` environment variable.
+
+### Key-value format
 
-### Key-Value format (default)
+The default format. Context data appears as `key=value` pairs, easy for humans to read and machines to parse.
 
 ```bash
-export APP_LOG_FORMAT=keyvalue  # or leave unset for default
+export APP_LOG_FORMAT=keyvalue
 ```
 
 ```
-[INFO] User action user_id=123 action=login success=True
-[ERROR] Database error error_code=500 table=users
+[INFO] User logged in user_id=123 method=oauth
+[ERROR] Payment failed order_id="abc-123" reason="insufficient_funds"
 ```
 
 ### JSON format
 
+Each log entry is a single JSON object. Ideal for log aggregation services like Datadog, Splunk, or CloudWatch.
+
 ```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"}
+{"timestamp": "2024-01-15 10:30:00,123", "level": "INFO", "message": "User logged in", "logger": "app", "user_id": 123, "method": "oauth"}
 ```
 
 ### Standard format
 
+A minimal format that omits context data entirely.
+
 ```bash
 export APP_LOG_FORMAT=standard
 ```
 
 ```
-[INFO] User action
-[ERROR] Database error
+[INFO] User logged in
 ```
 
-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:
+Add context that applies to all subsequent log calls by modifying the `context` dict directly.
 
 ```python
-# Set persistent context
-app_logger.context["user_id"] = 123
-app_logger.context["request_id"] = "abc456"
+# Set context at the start of a request
+app_logger.context["request_id"] = "req-789"
+app_logger.context["user_id"] = 42
 
-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
+app_logger.info("Starting request")  # Includes request_id and user_id
+app_logger.info("Fetching data")     # Includes request_id and user_id
 
-# Clear context
+# Clear when done
 app_logger.context.clear()
 ```
 
 ### Temporary context
 
-Use `include_context()` for temporary context that only applies within a block:
+Use `include_context()` when you need context for a specific block of code.
 
 ```python
-app_logger.context["user_id"] = 123  # Persistent
+app_logger.context["user_id"] = 42
 
-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
+with app_logger.include_context(operation="checkout", cart_id="cart-123"):
+    app_logger.info("Starting checkout")  # Has user_id, operation, cart_id
+    app_logger.info("Validating items")   # Has user_id, operation, cart_id
 
-app_logger.info("Payment complete")        # Only has user_id
+app_logger.info("Checkout complete")      # Only has user_id
 ```
 
 ## Debug mode
 
-The `force_debug()` context manager allows temporarily enabling DEBUG level logging:
+When you need to temporarily see debug-level logs (even if the logger is set to `INFO`), use `force_debug()`.
 
 ```python
-# Debug messages might not show at INFO level
-app_logger.debug("This might not appear")
+# These won't show if log level is INFO
+app_logger.debug("Detailed trace info")
 
-# Temporarily enable debug logging
+# Temporarily enable debug output
 with app_logger.force_debug():
-    app_logger.debug("This will definitely appear", extra_data="debug_info")
+    app_logger.debug("This will appear")
+    app_logger.debug("So will this", context={"step": "validation"})
+
+# Back to normal
+app_logger.debug("This won't show again")
+```
+
+The [`DebugMode`](./debug.py#DebugMode) class handles reference counting, so nested `force_debug()` calls work correctly.
+
+## Output streams
+
+By default, Plain splits log output by severity:
+
+- **DEBUG, INFO** go to `stdout`
+- **WARNING, ERROR, CRITICAL** go to `stderr`
+
+This helps cloud platforms automatically classify log severity. You can change this behavior with `PLAIN_LOG_STREAM`:
+
+```bash
+# Default: split by level
+export PLAIN_LOG_STREAM=split
+
+# All logs to stdout
+export PLAIN_LOG_STREAM=stdout
+
+# All logs to stderr (traditional Python behavior)
+export PLAIN_LOG_STREAM=stderr
+```
+
+## Settings reference
+
+All logging settings use environment variables:
+
+| Environment Variable        | Default    | Description                                      |
+| --------------------------- | ---------- | ------------------------------------------------ |
+| `PLAIN_FRAMEWORK_LOG_LEVEL` | `INFO`     | Log level for the `plain` logger                 |
+| `PLAIN_LOG_LEVEL`           | `INFO`     | Log level for the `app` logger                   |
+| `PLAIN_LOG_FORMAT`          | `keyvalue` | Output format: `json`, `keyvalue`, or `standard` |
+| `PLAIN_LOG_STREAM`          | `split`    | Output stream: `split`, `stdout`, or `stderr`    |
+
+Valid log levels: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`
+
+## FAQs
+
+#### How do I use a custom logger instead of app_logger?
+
+You can use Python's standard `logging.getLogger()` for additional loggers. They won't have the context features of `app_logger`, but they'll use Plain's output configuration.
+
+#### Can I use app_logger in library code?
+
+The `app_logger` is designed for application code. If you're writing a reusable library, use `logging.getLogger(__name__)` to allow users to configure logging independently.
+
+#### Why are my debug logs not showing?
+
+The default log level is `INFO`. Set `PLAIN_LOG_LEVEL=DEBUG` in your environment or use `app_logger.force_debug()` temporarily.
+
+#### How do I add context to exception logs?
+
+Pass both `exc_info=True` and `context` to include both the traceback and structured data:
+
+```python
+except Exception:
+    app_logger.error("Operation failed", exc_info=True, context={"operation": "sync"})
+```
+
+## Installation
+
+`plain.logs` is included with Plain by default. No additional installation is required.
+
+To adjust log levels for development, add environment variables to your shell or `.env` file:
+
+```bash
+PLAIN_LOG_LEVEL=DEBUG
+PLAIN_FRAMEWORK_LOG_LEVEL=WARNING
 ```

plain/logs/__init__.py

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

plain/logs/{loggers.py → app.py}

@@ -1,19 +1,23 @@
+from __future__ import annotations
+
 import logging
+from collections.abc import Generator
 from contextlib import contextmanager
+from typing import Any
 
 from .debug import DebugMode
 
 
 class AppLogger(logging.Logger):
-    """Enhanced logger that supports kwargs-style logging and context management."""
+    """Enhanced logger that supports context dict logging and context management."""
 
-    def __init__(self, name):
+    def __init__(self, name: str):
         super().__init__(name)
-        self.context = {}  # Public, mutable context dict
+        self.context: dict[str, Any] = {}  # Public, mutable context dict
         self.debug_mode = DebugMode(self)
 
     @contextmanager
-    def include_context(self, **kwargs):
+    def include_context(self, **kwargs: Any) -> Generator[None, None, None]:
         """Context manager for temporary context."""
         # Store original context
         original_context = self.context.copy()
@@ -27,21 +31,21 @@ class AppLogger(logging.Logger):
             # Restore original context
             self.context = original_context
 
-    def force_debug(self):
+    def force_debug(self) -> DebugMode:
         """Return context manager for temporarily enabling DEBUG level logging."""
         return self.debug_mode
 
     # Override logging methods with explicit parameters for IDE support
-    def debug(
+    def debug(  # type: ignore[override]
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         if self.isEnabledFor(logging.DEBUG):
             self._log(
                 logging.DEBUG,
@@ -51,19 +55,19 @@ class AppLogger(logging.Logger):
                 extra=extra,
                 stack_info=stack_info,
                 stacklevel=stacklevel,
-                **context,
+                context=context,
             )
 
-    def info(
+    def info(  # type: ignore[override]
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         if self.isEnabledFor(logging.INFO):
             self._log(
                 logging.INFO,
@@ -73,19 +77,19 @@ class AppLogger(logging.Logger):
                 extra=extra,
                 stack_info=stack_info,
                 stacklevel=stacklevel,
-                **context,
+                context=context,
             )
 
-    def warning(
+    def warning(  # type: ignore[override]
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         if self.isEnabledFor(logging.WARNING):
             self._log(
                 logging.WARNING,
@@ -95,19 +99,19 @@ class AppLogger(logging.Logger):
                 extra=extra,
                 stack_info=stack_info,
                 stacklevel=stacklevel,
-                **context,
+                context=context,
             )
 
-    def error(
+    def error(  # type: ignore[override]
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         if self.isEnabledFor(logging.ERROR):
             self._log(
                 logging.ERROR,
@@ -117,19 +121,19 @@ class AppLogger(logging.Logger):
                 extra=extra,
                 stack_info=stack_info,
                 stacklevel=stacklevel,
-                **context,
+                context=context,
             )
 
-    def critical(
+    def critical(  # type: ignore[override]
         self,
-        msg,
-        *args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        msg: object,
+        *args: object,
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         if self.isEnabledFor(logging.CRITICAL):
             self._log(
                 logging.CRITICAL,
@@ -139,20 +143,20 @@ class AppLogger(logging.Logger):
                 extra=extra,
                 stack_info=stack_info,
                 stacklevel=stacklevel,
-                **context,
+                context=context,
             )
 
-    def _log(
+    def _log(  # type: ignore[override]
         self,
-        level,
-        msg,
-        args,
-        exc_info=None,
-        extra=None,
-        stack_info=False,
-        stacklevel=1,
-        **context,
-    ):
+        level: int,
+        msg: object,
+        args: tuple[object, ...],
+        exc_info: Any = None,
+        extra: dict[str, Any] | None = None,
+        stack_info: bool = False,
+        stacklevel: int = 1,
+        context: dict[str, Any] | None = None,
+    ) -> None:
         """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:
@@ -163,9 +167,9 @@ class AppLogger(logging.Logger):
         # Build final extra with context
         extra = extra.copy() if extra else {}
 
-        # Add our context (persistent + kwargs) to extra["context"]
+        # Add our context (persistent + passed context) to extra["context"]
         if self.context or context:
-            extra["context"] = {**self.context, **context}
+            extra["context"] = {**self.context, **(context or {})}
 
         # Call the parent logger's _log method with explicit parameters
         super()._log(

plain/logs/configure.py

@@ -1,36 +1,85 @@
 import logging
+import sys
+from typing import TextIO
 
+from .filters import DebugInfoFilter, WarningErrorCriticalFilter
 from .formatters import JSONFormatter, KeyValueFormatter
 
 
-def configure_logging(*, plain_log_level, app_log_level, app_log_format):
+def attach_log_handlers(
+    *,
+    logger: logging.Logger,
+    info_stream: TextIO,
+    warning_stream: TextIO,
+    formatter: logging.Formatter,
+) -> None:
+    """Attach two handlers to a logger that split by log level.
+
+    INFO and below go to info_stream, WARNING and above go to warning_stream.
+    """
+    # DEBUG and INFO handler
+    info_handler = logging.StreamHandler(info_stream)
+    info_handler.addFilter(DebugInfoFilter())
+    info_handler.setFormatter(formatter)
+    logger.addHandler(info_handler)
+
+    # WARNING, ERROR, and CRITICAL handler
+    warning_handler = logging.StreamHandler(warning_stream)
+    warning_handler.addFilter(WarningErrorCriticalFilter())
+    warning_handler.setFormatter(formatter)
+    logger.addHandler(warning_handler)
+
+
+def configure_logging(
+    *,
+    plain_log_level: int | str,
+    app_log_level: int | str,
+    app_log_format: str,
+    log_stream: str = "split",
+) -> None:
+    # Determine which streams to use based on log_stream setting
+    if log_stream == "split":
+        info_stream = sys.stdout
+        warning_stream = sys.stderr
+    elif log_stream == "stdout":
+        info_stream = sys.stdout
+        warning_stream = sys.stdout
+    else:  # stderr (or any other value defaults to stderr for backwards compat)
+        info_stream = sys.stderr
+        warning_stream = sys.stderr
+
     # Create and configure the plain logger (uses standard Logger, not AppLogger)
-    plain_logger = logging.Logger("plain")
+    plain_logger = logging.getLogger("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)
+    attach_log_handlers(
+        logger=plain_logger,
+        info_stream=info_stream,
+        warning_stream=warning_stream,
+        formatter=logging.Formatter("[%(levelname)s] %(message)s"),
+    )
     plain_logger.propagate = False
-    logging.root.manager.loggerDict["plain"] = plain_logger
 
     # Configure the existing app_logger
-    from .loggers import app_logger
+    from .app import app_logger
 
     app_logger.setLevel(app_log_level)
     app_logger.propagate = False
 
-    app_handler = logging.StreamHandler()
+    # Determine formatter based on app_log_format
     match app_log_format:
         case "json":
-            app_handler.setFormatter(JSONFormatter("%(json)s"))
+            formatter = JSONFormatter("%(json)s")
         case "keyvalue":
-            app_handler.setFormatter(
-                KeyValueFormatter("[%(levelname)s] %(message)s %(keyvalue)s")
-            )
+            formatter = KeyValueFormatter("[%(levelname)s] %(message)s %(keyvalue)s")
         case _:
-            app_handler.setFormatter(logging.Formatter("[%(levelname)s] %(message)s"))
+            formatter = logging.Formatter("[%(levelname)s] %(message)s")
 
-    app_logger.addHandler(app_handler)
+    attach_log_handlers(
+        logger=app_logger,
+        info_stream=info_stream,
+        warning_stream=warning_stream,
+        formatter=formatter,
+    )
 
     # Register the app_logger in the logging system so getLogger("app") returns it
     logging.root.manager.loggerDict["app"] = app_logger