yapl-kit 0.1.0__py3-none-any.whl

yapl/__init__.py

@@ -0,0 +1,97 @@
+"""YAPL's small, typed public logging setup API.
+
+Typical use is ``setup_logging(...)`` once during application startup followed
+by ``get_logger(__name__)`` in modules that emit records. Queue and webhook
+configuration classes are re-exported here for ergonomic setup; specialised
+handlers and formatters remain in ``yapl.extensions``.
+"""
+
+from __future__ import annotations
+
+from .config import (
+    ConsoleConfig,
+    LoggerOverrides,
+    OutputConfig,
+    StackConfig,
+    SuppressionRule,
+    SuppressionRules,
+    YaplConfig,
+)
+from .extensions.queueing.models import QueueDiagnostics, QueueingConfig
+from .extensions.webhook.models import (
+    WebhookAuthConfig,
+    WebhookConfig,
+    WebhookDiagnostics,
+    WebhookFailurePolicy,
+    WebhookMethod,
+    WebhookPayloadMode,
+    WebhookProvider,
+    WebhookRetryConfig,
+)
+from .factory import get_logger, setup_logging, shutdown_logging
+from .levels import (
+    level_name,
+    register_default_levels,
+    register_level,
+    registered_levels,
+    resolve_level,
+)
+from .logger import (
+    RecordFlagPolicy,
+    YaplLogger,
+    register_level_method,
+    set_as_default_logger_class,
+)
+from .types import (
+    ColorMode,
+    ConsoleStream,
+    ContextEnrichValue,
+    LevelLike,
+    LevelMode,
+    OutputDestination,
+    OutputFormat,
+    QueueOverflowPolicy,
+    StackMode,
+)
+
+
+__all__ = [
+    "ColorMode",
+    "ConsoleConfig",
+    "ConsoleStream",
+    "ContextEnrichValue",
+    "LevelLike",
+    "LevelMode",
+    "LoggerOverrides",
+    "OutputConfig",
+    "OutputDestination",
+    "OutputFormat",
+    "QueueDiagnostics",
+    "QueueOverflowPolicy",
+    "QueueingConfig",
+    "RecordFlagPolicy",
+    "StackConfig",
+    "StackMode",
+    "SuppressionRule",
+    "SuppressionRules",
+    "WebhookAuthConfig",
+    "WebhookConfig",
+    "WebhookDiagnostics",
+    "WebhookFailurePolicy",
+    "WebhookMethod",
+    "WebhookPayloadMode",
+    "WebhookProvider",
+    "WebhookRetryConfig",
+    "YaplConfig",
+    "YaplLogger",
+    "get_logger",
+    "level_name",
+    "register_default_levels",
+    "register_level",
+    "register_level_method",
+    "registered_levels",
+    "resolve_level",
+    "set_as_default_logger_class",
+    "setup_logging",
+    "shutdown_logging",
+]

yapl/config.py

@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any
+
+from .levels import resolve_level
+from .types import (
+    ColorMode,
+    ConsoleStream,
+    LevelLike,
+    OutputDestination,
+    OutputFormat,
+    QueueOverflowPolicy,
+    StackMode,
+)
+
+
+if TYPE_CHECKING:
+    from .extensions.formatting.processors import LogEventProcessor
+    from .extensions.webhook.models import WebhookConfig
+
+
+@dataclass(frozen=True, slots=True)
+class SuppressionRule:
+    """Match records that should be suppressed before they reach a sink.
+
+    Every non-``None`` field must match. ``logger_prefix`` changes ``logger``
+    from an exact logger name to a prefix match.
+
+    Attributes:
+        logger: Logger name to match.
+        logger_prefix: Whether ``logger`` matches descendant logger names.
+        filename: Source filename to match.
+        function: Source function name to match.
+        line: Source line number to match.
+        message_contains: Text that must occur in the rendered message.
+    """
+
+    logger: str | None = None
+    logger_prefix: bool = False
+
+    filename: str | None = None
+    function: str | None = None
+    line: int | None = None
+    message_contains: str | None = None
+
+
+@dataclass(slots=True)
+class SuppressionRules:
+    """Mutable collection of :class:`SuppressionRule` instances.
+
+    The fluent helpers return this collection so rules can be assembled while
+    building a :class:`YaplConfig`.
+    """
+
+    rules: list[SuppressionRule] = field(default_factory=list)
+
+    def drop(
+        self,
+        *,
+        logger: str | None = None,
+        logger_prefix: bool = False,
+        filename: str | None = None,
+        function: str | None = None,
+        line: int | None = None,
+        message_contains: str | None = None,
+    ) -> SuppressionRules:
+        """Append one suppression rule and return this collection.
+
+        Args:
+            logger: Logger name to match.
+            logger_prefix: Match descendant logger names when ``True``.
+            filename: Source filename to match.
+            function: Source function name to match.
+            line: Source line number to match.
+            message_contains: Text that must occur in the rendered message.
+        """
+        self.rules.append(
+            SuppressionRule(
+                logger=logger,
+                logger_prefix=logger_prefix,
+                filename=filename,
+                function=function,
+                line=line,
+                message_contains=message_contains,
+            )
+        )
+        return self
+
+    def extend(self, items: Iterable[SuppressionRule]) -> SuppressionRules:
+        """Append ``items`` and return this collection."""
+        self.rules.extend(items)
+        return self
+
+
+@dataclass(slots=True)
+class LoggerOverrides:
+    """Per-logger level overrides applied by :func:`yapl.setup_logging`."""
+
+    levels: dict[str, int] = field(default_factory=dict)
+
+    def set(self, logger_name: str, level: LevelLike) -> LoggerOverrides:
+        """Set ``logger_name`` to ``level`` and return this collection.
+
+        Raises:
+            ValueError: If a string level is not registered.
+        """
+        self.levels[logger_name] = resolve_level(level)
+        return self
+
+    def update(self, mapping: Mapping[str, LevelLike]) -> LoggerOverrides:
+        """Apply several logger-level overrides and return this collection."""
+        for k, v in mapping.items():
+            self.set(k, v)
+        return self
+
+
+@dataclass(frozen=True, slots=True)
+class ConsoleConfig:
+    """Configuration for YAPL's default console output.
+
+    Attributes:
+        enabled: Whether a console sink is created when no explicit outputs exist.
+        stream: Standard stream used by the console sink.
+        level: Optional sink-level override; the root level is used by default.
+        color: Colour policy for text output.
+        theme_name: Optional registered colour theme name.
+    """
+
+    enabled: bool = True
+    stream: ConsoleStream = "stdout"
+    level: LevelLike | None = None
+    color: ColorMode = "never"
+    theme_name: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class OutputConfig:
+    """Describe one built-in output sink.
+
+    Attributes:
+        destination: ``"stdout"``, ``"stderr"``, ``"file"``, or ``"webhook"``.
+        format: Built-in formatter used by the sink.
+        level: Optional minimum level for this sink.
+        color: Colour policy; supported only by text console outputs.
+        file_path: UTF-8 file path required for ``destination="file"``.
+        theme_name: Optional registered colour theme name.
+
+    Raises:
+        ValueError: If colour is requested for an unsupported sink or format.
+    """
+
+    destination: OutputDestination
+    format: OutputFormat = "text"
+    level: LevelLike | None = None
+    color: ColorMode = "never"
+    file_path: str | None = None
+    theme_name: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.destination not in {"stdout", "stderr"} and self.color != "never":
+            raise ValueError("color is only supported for stdout and stderr outputs")
+        if self.color != "never" and self.format not in {"text", "plain"}:
+            raise ValueError("color is only supported with text or plain output")
+
+
+@dataclass(frozen=True, slots=True)
+class StackConfig:
+    """Control the stack metadata collected by YAPL formatters.
+
+    ``"record"`` preserves the record callsite; ``"full"`` additionally
+    captures a rendered stack when requested by the configured stack helpers.
+    """
+
+    mode: StackMode = "record"
+
+
+@dataclass(slots=True)
+class YaplConfig:
+    """Top-level configuration accepted by :func:`yapl.setup_logging`.
+
+    Most applications only need ``level`` and the default console settings.
+    When queueing is enabled (the default), built-in sinks run in a background
+    worker and queue insertion does not intentionally wait. Queue capacity is
+    measured in records, not bytes, so large arguments or ``extra`` values can
+    still retain substantial memory while queued.
+
+    Attributes:
+        level: Root logging level; defaults to ``logging.INFO`` (20).
+        console: Default console-sink settings.
+        stack: Stack metadata policy.
+        outputs: Legacy shorthand output destinations used when ``sinks`` is empty.
+        format: Formatter for shorthand outputs.
+        sinks: Explicit built-in output definitions.
+        queue_enabled: Put configured sinks behind a bounded queue.
+        queue_max_size: Maximum queued records, not a byte limit.
+        queue_overflow_policy: Action on a full queue; ``"block"`` may wait.
+        processors: Structured-event processors run by compatible formatters.
+        resource: Static fields added to structured log events.
+        webhook: Optional configuration for a ``"webhook"`` output.
+        file_path: File used by shorthand ``"file"`` output.
+        overrides: Per-logger level overrides.
+        suppression: Rules applied to configured handlers.
+    """
+
+    level: int = 20
+    console: ConsoleConfig = field(default_factory=ConsoleConfig)
+    stack: StackConfig = field(default_factory=StackConfig)
+
+    outputs: tuple[OutputDestination, ...] = ()
+    format: OutputFormat = "text"
+    sinks: tuple[OutputConfig, ...] = ()
+    queue_enabled: bool = True
+    queue_max_size: int = 10_000
+    queue_overflow_policy: QueueOverflowPolicy = "drop_debug_only"
+    processors: tuple[LogEventProcessor, ...] = field(default_factory=tuple)
+    resource: Mapping[str, Any] = field(default_factory=dict)
+    webhook: WebhookConfig | None = None
+    file_path: str | None = None
+
+    overrides: LoggerOverrides = field(default_factory=LoggerOverrides)
+    suppression: SuppressionRules = field(default_factory=SuppressionRules)
+
+    def with_level(self, level: LevelLike) -> YaplConfig:
+        """Set the root level and return this configuration.
+
+        Raises:
+            ValueError: If a string level is not registered.
+        """
+        self.level = resolve_level(level)
+        return self
+
+    def with_console_level(self, level: LevelLike | None) -> YaplConfig:
+        """Set the default console sink level and return this configuration."""
+        self.console = ConsoleConfig(
+            enabled=self.console.enabled,
+            stream=self.console.stream,
+            level=level,
+            color=self.console.color,
+            theme_name=self.console.theme_name,
+        )
+        return self
+
+    def with_console(
+        self,
+        *,
+        enabled: bool | None = None,
+        stream: ConsoleStream | None = None,
+        color: ColorMode | None = None,
+        theme_name: str | None = None,
+    ) -> YaplConfig:
+        """Update selected default console options and return this configuration."""
+        self.console = ConsoleConfig(
+            enabled=self.console.enabled if enabled is None else enabled,
+            stream=self.console.stream if stream is None else stream,
+            level=self.console.level,
+            color=self.console.color if color is None else color,
+            theme_name=self.console.theme_name if theme_name is None else theme_name,
+        )
+        return self
+
+    def with_stack(self, mode: StackMode) -> YaplConfig:
+        """Set the stack metadata policy and return this configuration."""
+        self.stack = StackConfig(mode=mode)
+        return self

yapl/extensions/buffering/__init__.py

@@ -0,0 +1,24 @@
+"""Context-local capture and replay of standard logging records."""
+
+from .capture import BufferCaptureFilter
+from .context import BufferedLogs, BufferingFilter, install_buffering
+from .models import (
+    BufferedLogEntry,
+    BufferedLogStore,
+    BufferExitBehavior,
+    BufferFlushMode,
+    BufferingConfig,
+)
+
+
+__all__ = [
+    "BufferCaptureFilter",
+    "BufferExitBehavior",
+    "BufferFlushMode",
+    "BufferedLogEntry",
+    "BufferedLogStore",
+    "BufferedLogs",
+    "BufferingConfig",
+    "BufferingFilter",
+    "install_buffering",
+]

yapl/extensions/buffering/capture.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from copy import copy
+import logging
+
+from .models import BufferedLogEntry, BufferingState
+
+
+_active_buffer_state: ContextVar[BufferingState | None] = ContextVar(
+    "yapl_buffering_active_state",
+    default=None,
+)
+
+_capture_enabled: ContextVar[bool] = ContextVar(
+    "yapl_buffering_capture_enabled",
+    default=True,
+)
+
+
+def get_active_buffer_state() -> BufferingState | None:
+    return _active_buffer_state.get()
+
+
+def set_active_buffer_state(state: BufferingState | None) -> Token[BufferingState | None]:
+    return _active_buffer_state.set(state)
+
+
+def reset_active_buffer_state(token: Token[BufferingState | None]) -> None:
+    _active_buffer_state.reset(token)
+
+
+def is_capture_enabled() -> bool:
+    return _capture_enabled.get()
+
+
+def set_capture_enabled(enabled: bool) -> Token[bool]:
+    return _capture_enabled.set(enabled)
+
+
+def reset_capture_enabled(token: Token[bool]) -> None:
+    _capture_enabled.reset(token)
+
+
+class BufferCaptureFilter(logging.Filter):
+    """Copy records into the active context-local buffer exactly once."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Capture ``record`` when buffering is active, then allow it onward."""
+        if not is_capture_enabled():
+            return True
+
+        if getattr(record, "_yapl_buffer_capture_seen", False):
+            return True
+
+        state = get_active_buffer_state()
+        if state is None:
+            return True
+
+        buffered_record = copy(record)
+        state.store.add(
+            BufferedLogEntry(record=buffered_record),
+            max_entries=state.config.max_entries,
+        )
+        record._yapl_buffer_capture_seen = True
+        return True

yapl/extensions/buffering/context.py

@@ -0,0 +1,162 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+import logging
+from types import TracebackType
+from typing import Self
+
+from .capture import (
+    BufferCaptureFilter,
+    get_active_buffer_state,
+    is_capture_enabled,
+    reset_active_buffer_state,
+    reset_capture_enabled,
+    set_active_buffer_state,
+    set_capture_enabled,
+)
+from .flush import discard_buffer_store, flush_buffer_store
+from .models import BufferedLogStore, BufferingConfig, BufferingState
+
+
+class BufferedLogs:
+    """Capture records in a context and replay or discard them on exit.
+
+    Context state uses :mod:`contextvars`, so independent asyncio tasks and
+    threads do not share buffers accidentally. Nested contexts share the outer
+    buffer by default; set ``include_nested_contexts=False`` for isolation.
+    """
+
+    def __init__(self, config: BufferingConfig | None = None) -> None:
+        """Create an inactive context with the supplied buffering policy."""
+        self._cfg = config or BufferingConfig()
+        self._store = BufferedLogStore()
+        self._state = BufferingState(store=self._store, config=self._cfg)
+
+        self._token = None
+        self._previous_state: BufferingState | None = None
+        self._owns_state: bool = False
+
+    @property
+    def store(self) -> BufferedLogStore:
+        """Return the mutable store owned by this context."""
+        return self._store
+
+    @property
+    def config(self) -> BufferingConfig:
+        """Return the active buffering configuration."""
+        return self._cfg
+
+    @property
+    def records(self) -> list[logging.LogRecord]:
+        """Return a snapshot list of records currently retained by the context."""
+        return [entry.record for entry in self._store.entries]
+
+    def __len__(self) -> int:
+        return len(self._store.entries)
+
+    def __iter__(self) -> Iterator[logging.LogRecord]:
+        """Iterate over currently buffered records in capture order."""
+        for entry in self._store.entries:
+            yield entry.record
+
+    def __enter__(self) -> Self:
+        """Activate this buffer for the current context."""
+        return self._enter()
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> bool:
+        """Flush or discard records according to the configured exit policy."""
+        return self._exit(exc_type)
+
+    async def __aenter__(self) -> Self:
+        """Activate this buffer for an asynchronous context manager block."""
+        return self._enter()
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> bool:
+        """Flush or discard records when leaving an async context manager block."""
+        return self._exit(exc_type)
+
+    def _enter(self) -> Self:
+        self._previous_state = get_active_buffer_state()
+
+        if self._previous_state is not None and self._cfg.include_nested_contexts:
+            self._state = self._previous_state
+            self._store = self._state.store
+            self._cfg = self._state.config
+            self._token = None
+            self._owns_state = False
+            return self
+
+        self._token = set_active_buffer_state(self._state)
+        self._owns_state = True
+        return self
+
+    def _exit(self, exc_type: type[BaseException] | None) -> bool:
+        if not self._owns_state:
+            return False
+
+        capture_token = set_capture_enabled(False)
+
+        try:
+            if self._should_flush(exc_type):
+                flush_buffer_store(
+                    self._store,
+                    flush_mode=self._cfg.flush_mode,
+                )
+            else:
+                discard_buffer_store(self._store)
+        finally:
+            if capture_token is not None:
+                reset_capture_enabled(capture_token)
+
+            if self._token is not None:
+                reset_active_buffer_state(self._token)
+
+        return False
+
+    def _should_flush(self, exc_type: type[BaseException] | None) -> bool:
+        if exc_type is None:
+            return self._cfg.on_success == "flush"
+        return self._cfg.on_error == "flush"
+
+
+class BufferingFilter(logging.Filter):
+    """Suppress direct sink delivery while records are being captured."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        """Allow records only when capture is inactive for this context."""
+        return (not is_capture_enabled()) or get_active_buffer_state() is None
+
+
+def install_buffering(*, stream_handlers_only: bool = False) -> int:
+    """Install buffering filters on root handlers and return the count updated.
+
+    Install once after configuring handlers. Repeated installation adds another
+    filter, so retain the result of setup rather than calling it per request.
+    """
+    root = logging.getLogger()
+
+    capture_filter = BufferCaptureFilter()
+    root.addFilter(capture_filter)
+
+    buffering_filter = BufferingFilter()
+    updated = 0
+
+    for handler in root.handlers:
+        if stream_handlers_only and not isinstance(handler, logging.StreamHandler):
+            continue
+
+        handler.addFilter(capture_filter)
+        handler.addFilter(buffering_filter)
+        updated += 1
+
+    return updated

yapl/extensions/buffering/flush.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import logging
+
+from .models import BufferedLogEntry, BufferedLogStore, BufferFlushMode
+
+
+def _replay_record(record: logging.LogRecord) -> None:
+    logger = logging.getLogger(record.name)
+    logger.handle(record)
+
+
+def flush_buffer_store(
+    store: BufferedLogStore,
+    *,
+    flush_mode: BufferFlushMode = "ordered",
+) -> int:
+    """Replay retained records through their named stdlib loggers.
+
+    Returns the number of replayed records. Replaying may invoke configured
+    handlers synchronously unless those handlers are queue-backed.
+    """
+    if store.is_empty():
+        return 0
+
+    entries = _prepare_entries_for_flush(store.entries, flush_mode=flush_mode)
+
+    for entry in entries:
+        _replay_record(entry.record)
+
+    flushed = len(entries)
+    store.clear()
+    return flushed
+
+
+def discard_buffer_store(store: BufferedLogStore) -> int:
+    """Discard all retained records and return their count."""
+    discarded = len(store)
+    store.clear()
+    return discarded
+
+
+def _prepare_entries_for_flush(
+    entries: list[BufferedLogEntry],
+    *,
+    flush_mode: BufferFlushMode,
+) -> list[BufferedLogEntry]:
+    if flush_mode == "ordered":
+        return list(entries)
+
+    if flush_mode == "grouped":
+        return _group_entries(entries)
+
+    return list(entries)
+
+
+def _group_entries(entries: list[BufferedLogEntry]) -> list[BufferedLogEntry]:
+    grouped: dict[int, list[BufferedLogEntry]] = {}
+
+    for entry in entries:
+        level = entry.record.levelno
+        grouped.setdefault(level, []).append(entry)
+
+    ordered_levels = sorted(grouped.keys(), reverse=True)
+
+    result: list[BufferedLogEntry] = []
+
+    for level in ordered_levels:
+        result.extend(grouped[level])
+
+    return result