cells-log 0.2.2__py3-none-any.whl

cells/log/__init__.py

@@ -0,0 +1,47 @@
+"""cells-log public API."""
+
+from .config import FieldProcessor, JsonDumps, LogConfig, config_from_env
+from .context import (
+    bind_log_context,
+    get_log_context,
+    get_trace_id,
+    reset_log_context,
+    reset_trace_id,
+    set_trace_id,
+)
+from .levels import TRACE_LEVEL_NUM, parse_log_level
+from .logger import BoundLogger
+from .manager import (
+    LogStage,
+    bootstrap_logging,
+    configure_logging,
+    configure_logging_from_env,
+    get_logger,
+    get_queue_stats,
+    shutdown_logging,
+)
+from .timings import TimingCollector
+
+__all__ = [
+    "BoundLogger",
+    "FieldProcessor",
+    "JsonDumps",
+    "LogConfig",
+    "LogStage",
+    "TRACE_LEVEL_NUM",
+    "TimingCollector",
+    "bind_log_context",
+    "bootstrap_logging",
+    "config_from_env",
+    "configure_logging",
+    "configure_logging_from_env",
+    "get_log_context",
+    "get_logger",
+    "get_queue_stats",
+    "get_trace_id",
+    "parse_log_level",
+    "reset_log_context",
+    "reset_trace_id",
+    "set_trace_id",
+    "shutdown_logging",
+]

cells/log/config.py

@@ -0,0 +1,293 @@
+"""Configuration model for cells-log."""
+
+from __future__ import annotations
+
+import json as std_json
+import os
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, replace
+from pathlib import Path
+from typing import Any, Literal
+
+from cells.log.env import (
+    env_bool,
+    env_int,
+    env_key,
+    env_path,
+    env_size,
+    warn_config_fallback,
+)
+
+LogFormat = Literal["json", "text"]
+RotationMode = Literal["daily", "size"]
+QueueFullPolicy = Literal["drop", "block", "sync_fallback"]
+# Transform merged structured fields without processing the message or exception text.
+FieldProcessor = Callable[[dict[str, Any]], Mapping[str, Any] | dict[str, Any]]
+# Return str; accept either the ensure_ascii keyword or just the object to serialize.
+JsonDumps = Callable[..., str]
+
+
+def _default_json_dumps(obj: Any, **kwargs: Any) -> str:
+    """Default JSON dumper with safe fallback for non-primitive objects."""
+    kwargs.setdefault("ensure_ascii", False)
+    kwargs.setdefault("default", str)
+    return std_json.dumps(obj, **kwargs)
+
+
+@dataclass(slots=True)
+class LogConfig:
+    """Configure output, file rotation, queueing and context extensions.
+
+    Defaults apply to explicit production configuration: console JSON with an
+    in-process queue, no files, no root ownership and no warnings capture.
+    Bootstrap always disables files and the queue. Callers map application
+    settings to this object; changing it does not reconfigure active handlers.
+    Call configure_logging() again to apply changes.
+
+    Fields merge in context < bind < call order; later values win. Field hooks
+    receive shallow copies and may run repeatedly per record, once per sink,
+    in the listener or caller thread. JSON hooks must return str and handle
+    non-JSON objects. They receive ensure_ascii=False, with one retry without
+    that keyword on TypeError; they also encode text output's field suffixes.
+    """
+
+    # Options: <str>. "app" (default) is the fallback logger name and aggregate filename prefix.
+    app_name: str = "app"
+    # Options: <"TRACE", "DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL", "NOTSET", int>.
+    # "INFO" (default); WARN/FATAL aliases accepted. Unknown names warn and use INFO.
+    level: str | int = "INFO"
+    # Options: <"json", "text">. "json" (default) for single-line JSON;
+    # "text" for human-readable output. Applies to console and files.
+    format: LogFormat = "json"
+    # Options: <Path, str, None>. None (default); required for any file output, even
+    # with an absolute total_file. Expands ~; the manager creates the directory.
+    log_dir: Path | str | None = None
+
+    # Options: <True, False>. True (default) enables console output; False disables it.
+    # Independent of module and aggregate file output.
+    enable_console: bool = True
+    # Options: <True, False>. True (default) writes to stderr; False writes to stdout.
+    # Configuration diagnostics always use stderr.
+    console_to_stderr: bool = True
+    # Options: <True, False>. False (default) hides console fields; True includes them.
+    # Files always include fields; simplified text errors omit them on the console.
+    console_include_fields: bool = False
+    # Options: <True, False>. False (default) hides console tracebacks; True includes them.
+    # Files retain available exceptions; simplified text errors omit console tracebacks.
+    console_include_exception: bool = False
+    # Options: <True, False>. True (default) shows only a summary and "details in log file"
+    # for console text errors >= ERROR when files are enabled; False keeps normal detail.
+    simplify_console_errors: bool = True
+
+    # Options: <True, False>. False (default) disables module files; True routes by logger name.
+    # Each file is created lazily on its first record; bootstrap always disables this option.
+    enable_module_file: bool = False
+    # Options: <str>. "modules" (default) is the module file subdirectory under log_dir.
+    # An absolute path selects a directory independently of log_dir.
+    module_dir_name: str = "modules"
+    # Options: <int >= 1>. 128 (default) cached module handlers; new paths beyond the limit
+    # use overflow.log, adding at most one handler without evicting existing handlers.
+    max_module_handlers: int = 128
+    # Options: <tuple[str, ...]>. () (default) accepts all names; otherwise str.startswith
+    # matches prefixes, without package boundaries. Unmatched names use external.log.
+    module_name_prefixes: tuple[str, ...] = ()
+
+    # Options: <True, False>. False (default) disables the aggregate file; True writes all records.
+    # Independent of module files; bootstrap always disables this option.
+    enable_total_file: bool = False
+    # Options: <Path, str, None>. None (default) selects log_dir/<app_name>.log;
+    # relative paths use log_dir, absolute paths stand alone. Expands ~.
+    total_file: Path | str | None = None
+
+    # Options: <"daily", "size">. "daily" (default) rotates on the first write after local
+    # midnight; "size" uses size_limit. timestamp_utc does not change the rotation timezone.
+    rotation: RotationMode = "daily"
+    # Options: <int >= 0>. 14 (default) backups per file, not days. With 0, daily keeps all
+    # backups; size creates none and the active file may keep growing. Zero does not delete logs.
+    retention: int = 14
+    # Options: <int bytes, str bytes/B/KB/MB/GB>. "100MB" (default) = 104857600 bytes.
+    # Size rotation only; units use powers of 1024. A per-file threshold, not a total disk quota.
+    size_limit: str | int = "100MB"
+
+    # Options: <True, False>. True (default) uses a process-local listener; False writes in caller.
+    # No crash delivery guarantee; bootstrap always disables the queue.
+    use_queue: bool = True
+    # Options: <int >= 1>. 10_000 (default) queued records, excluding in-flight writes.
+    # Applies only with use_queue=True and active output sinks.
+    queue_capacity: int = 10_000
+    # Options: <"drop", "block", "sync_fallback">. "drop" (default) discards and counts on full;
+    # "block" waits or drops on timeout; "sync_fallback" writes in caller, risking delay/reordering.
+    queue_full_policy: QueueFullPolicy = "drop"
+    # Options: <float >= 0>. 0.1 (default) seconds to wait for space under "block", then drop/count.
+    # Zero does not wait; this is not a file I/O, handover or shutdown timeout.
+    queue_block_timeout: float = 0.1
+    # Options: <True, False>. False (default) stops propagation; True also uses parent loggers,
+    # potentially duplicating output. manage_root_logger=True forces False on owned loggers.
+    propagate: bool = False
+    # Options: <True, False>. False (default) leaves warnings unmanaged; True captures them as logs.
+    # Capture stays active across reconfiguration; disabling or shutdown restores prior state.
+    capture_warnings: bool = False
+    # Options: <True, False>. False (default) leaves root unmanaged; True captures records at root.
+    # Records stopped upstream are excluded; disabling or shutdown restores prior handlers/state.
+    manage_root_logger: bool = False
+    # Options: <True, False>. True (default) emits ISO timestamps with UTC timezone;
+    # False emits local ISO timestamps without a timezone offset.
+    timestamp_utc: bool = True
+
+    # Options: <str>. "system" (default) is the fallback for an empty or unset context trace ID.
+    # Updated only after configuration activation succeeds.
+    default_trace_id: str = "system"
+    # Options: <None, callable>. None (default) keeps merged fields; callable returns new fields.
+    # On failure, retain original fields and add _field_processor_error. See hook rules above.
+    field_processor: FieldProcessor | None = None
+    # Options: <callable>. _default_json_dumps (default) uses ensure_ascii=False and default=str.
+    # Custom encoders must return str; see hook rules above for invocation and retry behavior.
+    json_dumps: JsonDumps = _default_json_dumps
+
+    def normalized(self) -> LogConfig:
+        """Return a normalized copy without creating directories or activating logging.
+
+        Expand ~ in paths, lowercase format/rotation and enforce numeric minima.
+        Unknown format, rotation and queue_full_policy warn and fall back to
+        json, size and drop respectively. Nonconvertible numbers still raise
+        TypeError/ValueError. Level, size and directory validation is delegated
+        to the level parser, file handler and manager respectively.
+        """
+        log_dir = Path(self.log_dir).expanduser() if self.log_dir is not None else None
+        total_file = Path(self.total_file).expanduser() if self.total_file is not None else None
+        rotation: RotationMode = "daily" if str(self.rotation).lower() == "daily" else "size"
+        fmt: LogFormat = "text" if str(self.format).lower() == "text" else "json"
+        queue_full_policy: QueueFullPolicy = (
+            self.queue_full_policy
+            if self.queue_full_policy in {"drop", "block", "sync_fallback"}
+            else "drop"
+        )
+        normalized = replace(
+            self,
+            format=fmt,
+            log_dir=log_dir,
+            total_file=total_file,
+            rotation=rotation,
+            retention=max(0, int(self.retention)),
+            max_module_handlers=max(1, int(self.max_module_handlers)),
+            queue_capacity=max(1, int(self.queue_capacity)),
+            queue_full_policy=queue_full_policy,
+            queue_block_timeout=max(0.0, float(self.queue_block_timeout)),
+        )
+        for name, valid, allowed, risk in (
+            (
+                "format",
+                str(self.format).lower() in {"json", "text"},
+                "json, text",
+                "log output may not match the expected parser",
+            ),
+            (
+                "rotation",
+                str(self.rotation).lower() in {"daily", "size"},
+                "daily, size",
+                "rotation may not follow the intended policy",
+            ),
+            (
+                "queue_full_policy",
+                self.queue_full_policy in {"drop", "block", "sync_fallback"},
+                "drop, block, sync_fallback",
+                "records may be discarded when the queue is full",
+            ),
+            (
+                "retention",
+                int(self.retention) >= 0,
+                "an integer >= 0",
+                "disk usage may grow without the intended retention limit",
+            ),
+            (
+                "max_module_handlers",
+                int(self.max_module_handlers) >= 1,
+                "an integer >= 1",
+                "more logger names may be routed to the overflow file",
+            ),
+            (
+                "queue_capacity",
+                int(self.queue_capacity) >= 1,
+                "an integer >= 1",
+                "the queue may fill more often and trigger its full policy",
+            ),
+            (
+                "queue_block_timeout",
+                float(self.queue_block_timeout) >= 0,
+                "a number >= 0 (seconds)",
+                "queue insertion may time out immediately when full",
+            ),
+        ):
+            if not valid:
+                warn_config_fallback(
+                    name,
+                    getattr(self, name),
+                    getattr(normalized, name),
+                    allowed=allowed,
+                    risk=risk,
+                )
+        return normalized
+
+
+def config_from_env(
+    *,
+    app_name: str = "app",
+    default_log_dir: Path | str | None = None,
+    env_prefix: str = "CELLS_LOG",
+    base: LogConfig | None = None,
+) -> LogConfig:
+    """Return normalized environment overrides on base without activating logging.
+
+    Args:
+        app_name: Application name overriding base.app_name unless empty.
+        default_log_dir: Directory fallback taking precedence over base.log_dir.
+        env_prefix: Variable prefix; generated names are uppercased.
+        base: Baseline config; fields without environment overrides are retained.
+
+    Returns:
+        A normalized copy with applicable environment overrides.
+
+    Environment names use <PREFIX>_<NAME>. Supported names are LEVEL, FORMAT,
+    DIR, FILE, ENABLE_CONSOLE, ENABLE_MODULE_FILE, ENABLE_TOTAL_FILE, ROTATION,
+    RETENTION, SIZE_LIMIT, USE_QUEUE, QUEUE_CAPACITY, QUEUE_FULL_POLICY,
+    CAPTURE_WARNINGS and MANAGE_ROOT_LOGGER. Set other fields through base or
+    LogConfig. Booleans accept 1/true/yes/y/on and 0/false/no/n/off regardless of
+    case. Invalid booleans or integers warn and retain baseline values; empty
+    DIR/FILE retain path fallbacks. LEVEL is parsed by name, so numeric strings
+    are not converted to numeric levels. Pass custom integers via LogConfig.level.
+    """
+    cfg = base or LogConfig(app_name=app_name, log_dir=default_log_dir)
+
+    log_dir = env_path(
+        env_key(env_prefix, "DIR"),
+        Path(default_log_dir).expanduser() if default_log_dir else cfg.log_dir,
+    )
+    total_file = env_path(env_key(env_prefix, "FILE"), cfg.total_file)
+
+    return replace(
+        cfg,
+        app_name=app_name or cfg.app_name,
+        level=os.getenv(env_key(env_prefix, "LEVEL"), str(cfg.level)),
+        format=os.getenv(env_key(env_prefix, "FORMAT"), str(cfg.format)).lower(),  # type: ignore[arg-type]
+        log_dir=log_dir,
+        total_file=total_file,
+        enable_console=env_bool(env_key(env_prefix, "ENABLE_CONSOLE"), cfg.enable_console),
+        enable_module_file=env_bool(
+            env_key(env_prefix, "ENABLE_MODULE_FILE"), cfg.enable_module_file
+        ),
+        enable_total_file=env_bool(env_key(env_prefix, "ENABLE_TOTAL_FILE"), cfg.enable_total_file),
+        rotation=os.getenv(env_key(env_prefix, "ROTATION"), str(cfg.rotation)).lower(),  # type: ignore[arg-type]
+        retention=env_int(env_key(env_prefix, "RETENTION"), cfg.retention),
+        size_limit=env_size(env_key(env_prefix, "SIZE_LIMIT"), cfg.size_limit),
+        use_queue=env_bool(env_key(env_prefix, "USE_QUEUE"), cfg.use_queue),
+        queue_capacity=env_int(env_key(env_prefix, "QUEUE_CAPACITY"), cfg.queue_capacity),
+        queue_full_policy=os.getenv(
+            env_key(env_prefix, "QUEUE_FULL_POLICY"),
+            cfg.queue_full_policy,
+        ).lower(),  # type: ignore[arg-type]
+        capture_warnings=env_bool(env_key(env_prefix, "CAPTURE_WARNINGS"), cfg.capture_warnings),
+        manage_root_logger=env_bool(
+            env_key(env_prefix, "MANAGE_ROOT_LOGGER"),
+            cfg.manage_root_logger,
+        ),
+    ).normalized()

cells/log/context.py

@@ -0,0 +1,67 @@
+"""Context propagation for structured logs."""
+
+from __future__ import annotations
+
+from contextvars import ContextVar, Token
+from typing import Any
+
+_trace_id_var: ContextVar[str | None] = ContextVar("cells_log_trace_id", default=None)
+_context_fields_var: ContextVar[dict[str, Any] | None] = ContextVar(
+    "cells_log_context_fields",
+    default=None,
+)
+_default_trace_id = "system"
+
+
+def set_default_trace_id(default_trace_id: str) -> None:
+    """Set the process-wide fallback used when a context has no trace id."""
+    global _default_trace_id
+    _default_trace_id = default_trace_id
+
+
+def get_default_trace_id() -> str:
+    """Return the process fallback independently of the calling context."""
+    return _default_trace_id
+
+
+def get_trace_id() -> str:
+    """Return the context's nonempty trace ID or the last activated process fallback."""
+    return _trace_id_var.get() or _default_trace_id
+
+
+def set_trace_id(trace_id: str) -> Token[str | None]:
+    """Set the current context's trace ID and return a token to restore its old value.
+
+    Call reset_trace_id(token) in finally when the request or task ends; reset
+    nested assignments in reverse order. ContextVar isolates async task assignments;
+    callers manage propagation across threads. An empty string makes get_trace_id()
+    use the configured fallback.
+    """
+    return _trace_id_var.set(trace_id)
+
+
+def reset_trace_id(token: Token[str | None]) -> None:
+    """Restore the prior trace ID using a token from this context exactly once."""
+    _trace_id_var.reset(token)
+
+
+def bind_log_context(**fields: Any) -> Token[dict[str, Any] | None]:
+    """Merge request or task fields and return a reset token; new values win.
+
+    Restore with reset_log_context(token) in finally. Only the field dictionary
+    is copied; nested objects remain shared. Fields from logger.bind() and the
+    individual log call take precedence over these context fields.
+    """
+    current = dict(_context_fields_var.get() or {})
+    current.update(fields)
+    return _context_fields_var.set(current)
+
+
+def reset_log_context(token: Token[dict[str, Any] | None]) -> None:
+    """Restore prior fields using the bind_log_context token once in its original context."""
+    _context_fields_var.reset(token)
+
+
+def get_log_context() -> dict[str, Any]:
+    """Return a shallow copy whose key changes do not affect the context dictionary."""
+    return dict(_context_fields_var.get() or {})

cells/log/env.py

@@ -0,0 +1,131 @@
+"""Environment parsing utilities for cells-log."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any
+
+_TRUE_VALUES = {"1", "true", "yes", "y", "on"}
+_FALSE_VALUES = {"0", "false", "no", "n", "off"}
+
+
+def warn_config_fallback(name: str, value: Any, fallback: Any, *, allowed: str, risk: str) -> None:
+    """Report invalid configuration risks, accepted values and the actual fallback."""
+    try:
+        sys.stderr.write(
+            f"cells-log: WARNING {name}={value!r} is invalid; "
+            f"the effective value is {fallback!r}, so {risk}. "
+            f"Valid values: {allowed}.\n"
+        )
+    except Exception:
+        pass  # A diagnostic failure must not prevent the configured fallback.
+
+
+def env_key(prefix: str, key: str) -> str:
+    """Build an uppercase environment variable name such as CELLS_LOG_QUEUE_CAPACITY."""
+    return f"{prefix}_{key}".upper()
+
+
+def env_bool(name: str, default: bool) -> bool:
+    """Read a boolean, using the default when unset and warning on invalid values."""
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+
+    value = raw.strip().lower()
+    if value in _TRUE_VALUES:
+        return True
+    if value in _FALSE_VALUES:
+        return False
+    warn_config_fallback(
+        name,
+        raw,
+        default,
+        allowed="true: 1, true, yes, y, on; false: 0, false, no, n, off (case-insensitive)",
+        risk="the feature state may differ from the intended setting",
+    )
+    return default
+
+
+def env_int(name: str, default: int) -> int:
+    """Read an integer, warning and using the default if invalid; do not check ranges."""
+    raw = os.getenv(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw.strip())
+    except (TypeError, ValueError):  # fmt: skip
+        warn_config_fallback(
+            name,
+            raw,
+            default,
+            allowed="an integer",
+            risk="the numeric setting may differ from the intended limit",
+        )
+        return default
+
+
+def env_path(name: str, default: Path | None = None) -> Path | None:
+    """Expand ~ in a nonblank path or retain the default, without creating directories."""
+    raw = os.getenv(name)
+    if raw is None or not raw.strip():
+        return default
+    return Path(raw.strip()).expanduser()
+
+
+def parse_size_limit(raw_value: str | int) -> int:
+    """Parse integer bytes or B/KB/MB/GB strings using powers of 1024.
+
+    Ignore case and surrounding whitespace. Clamp the numeric part to at least 1;
+    fractions are unsupported. For example, 0MB becomes 1MB. Unparseable strings
+    warn and fall back to 100MB.
+    """
+    if isinstance(raw_value, int):
+        return max(1, raw_value)
+
+    value = str(raw_value).strip().upper()
+    units = [
+        ("GB", 1024 * 1024 * 1024),
+        ("MB", 1024 * 1024),
+        ("KB", 1024),
+        ("B", 1),
+    ]
+
+    for unit, multiplier in units:
+        if value.endswith(unit):
+            number = value[: -len(unit)].strip()
+            try:
+                return max(1, int(number)) * multiplier
+            except ValueError:
+                warn_config_fallback(
+                    "size_limit",
+                    raw_value,
+                    "100MB",
+                    allowed="an integer byte count or an integer followed by B, KB, MB, GB",
+                    risk="files may rotate at an unintended size threshold",
+                )
+                return 100 * 1024 * 1024
+
+    try:
+        return max(1, int(value))
+    except ValueError:
+        warn_config_fallback(
+            "size_limit",
+            raw_value,
+            "100MB",
+            allowed="an integer byte count or an integer followed by B, KB, MB, GB",
+            risk="files may rotate at an unintended size threshold",
+        )
+        return 100 * 1024 * 1024
+
+
+def env_size(name: str, default: str | int) -> str | int:
+    """Read the raw size string; parsing is deferred until a size file handler is created."""
+    return os.getenv(name, str(default))
+
+
+def coalesce(value: Any, fallback: Any) -> Any:
+    """Replace only None with the fallback, preserving False, zero and empty strings."""
+    return fallback if value is None else value