ezpy_logs 0.2.0__py3-none-any.whl

ezpy_logs/LoggerFactory.py

@@ -0,0 +1,108 @@
+# ABOUTME: Compatibility shim for the 0.1 API (LoggerFactory.getLogger / setup_LoggerFactory).
+# ABOUTME: Keeps the old implicit setup until 0.3; a new-style ezpy_logs.setup() always replaces it.
+import logging
+import typing
+import warnings
+
+from ezpy_logs._core import (
+    DEFAULT_LOG_DIR,
+    LevelFilter,
+    TqdmToLogger,
+    _configure,
+    _resolve,
+    current_files,
+    delete_old_logs,
+)
+from ezpy_logs import _core
+
+__all__ = ["BASE_LOG_DIR", "LevelFilter", "LoggerFactory", "TqdmToLogger", "remove_logs_older_than_n_days"]
+
+MIN_LEVEL_FOR_LOGGERS = logging.DEBUG
+BASE_LOG_DIR = DEFAULT_LOG_DIR
+_LEGACY_RETENTION_DAYS = 30
+
+
+def remove_logs_older_than_n_days(root_dir: str, n_days: int = 30) -> int:
+    return delete_old_logs(root_dir, n_days)
+
+
+class _LegacyState(type):
+    """Class-level read-only views of the live setup, so they never go stale."""
+
+    @property
+    def is_setup(cls) -> bool:
+        return _core._state is not None
+
+    @property
+    def base_logging_directory(cls) -> str | None:
+        return _core._state.config.log_dir.as_posix() if _core._state else None
+
+    @property
+    def output_files(cls) -> list[tuple[str, int, int, str]]:
+        """(path, min_level, max_level, mode) of the files currently written, as in 0.1."""
+        return [(p.as_posix(), low, high, mode) for p, low, high, mode in current_files()]
+
+
+class LoggerFactory(metaclass=_LegacyState):
+    """Deprecated: use `ezpy_logs.setup()` and `ezpy_logs.get_logger()`.
+
+    Legacy setups never fight a new-style one: `setup()` replaces them, and a legacy setup
+    after `setup()` is a no-op. Between themselves, the first legacy setup wins (0.1 behaviour).
+    """
+
+    setup_loggers: typing.ClassVar[list[str]] = []
+    _warned: typing.ClassVar[bool] = False
+
+    @classmethod
+    def setup_LoggerFactory(cls, log_dir: str = BASE_LOG_DIR, clean_old_logs: bool = True):
+        if _core._state is None:
+            config = _resolve(
+                log_dir=log_dir,
+                level=None,
+                app_loggers=(),
+                app_level=logging.DEBUG,
+                run_id=None,
+                json=None,
+                tz=None,
+                latest=None,
+                retention_days=_LEGACY_RETENTION_DAYS if clean_old_logs else None,
+                redact_values=(),
+            )
+            _configure(config, legacy=True)
+
+    @classmethod
+    def getLogger(
+        cls,
+        name: str = "should be __name__",
+        level=MIN_LEVEL_FOR_LOGGERS,
+    ) -> logging.Logger:
+        if _core._state is None:
+            if not cls._warned:
+                cls._warned = True
+                warnings.warn(
+                    "LoggerFactory.getLogger() set up logging implicitly in ./.logs; this "
+                    "implicit setup goes away in ezpy_logs 0.3. Call ezpy_logs.setup() "
+                    "from your application and use ezpy_logs.get_logger().",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            cls.setup_LoggerFactory()
+        logger = logging.getLogger(name)
+        logger.setLevel(level)
+        if name not in cls.setup_loggers:
+            cls.setup_loggers.append(name)
+        return logger
+
+    @classmethod
+    def get_TqdmToLogger(cls, logger: logging.Logger, level=MIN_LEVEL_FOR_LOGGERS) -> TqdmToLogger:
+        return TqdmToLogger(logger, level)
+
+    @classmethod
+    def change_level_of_all_loggers(cls, level):
+        for name in cls.setup_loggers:
+            logging.getLogger(name).setLevel(level)
+
+    @classmethod
+    def _reset(cls) -> None:
+        cls.setup_loggers = []
+        cls._warned = False

ezpy_logs/__init__.py

@@ -0,0 +1,5 @@
+# ABOUTME: Public API of ezpy_logs: setup() once from the application, get_logger() everywhere.
+# ABOUTME: LoggerFactory stays importable from ezpy_logs.LoggerFactory as a deprecated alias until 0.3.
+from ezpy_logs._core import TqdmToLogger, delete_old_logs, get_logger, is_setup, setup
+
+__all__ = ["TqdmToLogger", "delete_old_logs", "get_logger", "is_setup", "setup"]

ezpy_logs/_core.py

@@ -0,0 +1,298 @@
+# ABOUTME: setup() / get_logger(): one set of handlers on the root logger, configured explicitly once.
+# ABOUTME: Also owns file naming, retention of the library's own archive files, and the tqdm adapter.
+import io
+import logging
+import os
+import sys
+import time
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from ezpy_logs._format import FILE_FORMAT, TERMINAL_FORMAT, JsonFormatter, TextFormatter, file_stamp
+from ezpy_logs._redact import Redactor
+
+DEFAULT_LOG_DIR = ".logs"
+DEFAULT_ROOT_LEVEL = logging.WARNING
+_OWN_SUFFIXES = (".log", ".jsonl")
+_OWN_DIRS = ("archive", "archive_ERRORS")
+
+_logger = logging.getLogger(__name__)
+
+
+class LevelFilter(logging.Filter):
+    def __init__(self, low=logging.DEBUG, high=logging.CRITICAL) -> None:
+        """Filters by logging level.
+
+        Args:
+            low : Lowest passing level (** Included **)
+            high : Highest passing level (** Included **)
+        """
+        self._low = low
+        self._high = high
+        logging.Filter.__init__(self)
+
+    def filter(self, record):
+        return self._low <= record.levelno <= self._high
+
+
+@dataclass(frozen=True)
+class Config:
+    log_dir: Path
+    level: int
+    app_loggers: tuple[str, ...]
+    app_level: int
+    run_id: str | None
+    json: bool
+    tz: str
+    latest: bool
+    retention_days: float | None
+    redact_values: tuple[str, ...] = field(repr=False)
+
+
+@dataclass
+class _State:
+    config: Config
+    legacy: bool
+    handlers: list[logging.Handler]
+    files: list[tuple[Path, int, int, str]]  # (path, min_level, max_level, "append"|"replace")
+
+
+_state: _State | None = None
+
+
+def _env_level(value: str | int | None) -> int:
+    if value is None:
+        value = os.environ.get("EZPY_LOGS_LEVEL") or DEFAULT_ROOT_LEVEL
+    if isinstance(value, int):
+        return value
+    level = logging.getLevelName(value.upper())
+    if not isinstance(level, int):
+        raise ValueError(f"unknown log level: {value!r}")
+    return level
+
+
+def _resolve(
+    log_dir, level, app_loggers, app_level, run_id, json, tz, latest, retention_days, redact_values
+) -> Config:
+    tz = (tz or os.environ.get("EZPY_LOGS_TZ") or "utc").lower()
+    if tz not in ("utc", "local"):
+        raise ValueError(f"tz must be 'utc' or 'local', not {tz!r}")
+    if json is None:
+        json = os.environ.get("EZPY_LOGS_JSON") == "1"
+    if latest is None:
+        latest = run_id is None
+    return Config(
+        log_dir=Path(log_dir or os.environ.get("EZPY_LOGS_DIR") or DEFAULT_LOG_DIR).absolute(),
+        level=_env_level(level),
+        app_loggers=tuple(app_loggers),
+        app_level=_env_level(app_level),
+        run_id=run_id,
+        json=bool(json),
+        tz=tz,
+        latest=bool(latest),
+        retention_days=retention_days,
+        redact_values=tuple(redact_values),
+    )
+
+
+def setup(
+    log_dir: str | os.PathLike | None = None,
+    *,
+    level: str | int | None = None,
+    app_loggers: Iterable[str] = (),
+    app_level: str | int = logging.DEBUG,
+    run_id: str | None = None,
+    json: bool | None = None,
+    tz: str | None = None,
+    latest: bool | None = None,
+    retention_days: float | None = None,
+    redact_values: Iterable[str] = (),
+) -> None:
+    """Configures logging for the whole process. Call it once, from the application.
+
+    Args:
+        log_dir: where files go. Default: $EZPY_LOGS_DIR, else `.logs` in the cwd.
+        level: root level, i.e. the level of every logger you don't own (third-party
+            libraries). Default: $EZPY_LOGS_LEVEL, else WARNING.
+        app_loggers: names of your own loggers (usually your package name); they are set
+            to `app_level` so your DEBUG lines show without the libraries' DEBUG flood.
+        run_id: names the files `<log_dir>/<run_id>.log` / `.jsonl` instead of timestamped
+            archives, and turns `latest` off by default.
+        json: also write JSON lines. Default: $EZPY_LOGS_JSON == "1".
+        tz: "utc" (default, or $EZPY_LOGS_TZ) or "local" for file names and text lines.
+            JSON `ts` is always UTC.
+        latest: also write `Latest.log` / `Latest_ERRORS.log`, overwritten by each run.
+            Default: on, unless run_id is given.
+        retention_days: delete this library's own archive files older than this.
+            Default None: never delete anything.
+        redact_values: literal secret values to redact (shorter than 8 chars are ignored).
+
+    Calling setup again with the same arguments is a no-op; with different arguments it
+    raises. It always replaces a legacy `LoggerFactory` setup.
+    """
+    config = _resolve(
+        log_dir, level, app_loggers, app_level, run_id, json, tz, latest, retention_days, redact_values
+    )
+    if _state is not None and not _state.legacy:
+        if _state.config == config:
+            return
+        raise RuntimeError(
+            f"ezpy_logs is already set up with {_state.config}; refusing to reconfigure to {config}"
+        )
+    _configure(config, legacy=False)
+
+
+def get_logger(name: str) -> logging.Logger:
+    """Returns `logging.getLogger(name)`. Never configures anything or creates files."""
+    return logging.getLogger(name)
+
+
+def is_setup() -> bool:
+    return _state is not None
+
+
+def current_files() -> list[tuple[Path, int, int, str]]:
+    """The files the current setup writes to, as (path, min_level, max_level, mode)."""
+    return list(_state.files) if _state else []
+
+
+def _configure(config: Config, legacy: bool) -> None:
+    global _state
+    _teardown()
+    redactor = Redactor(config.redact_values)
+    root = logging.getLogger()
+    handlers: list[logging.Handler] = []
+    files: list[tuple[Path, int, int, str]] = []
+
+    def add(handler: logging.Handler, low: int, high: int) -> None:
+        handler.setLevel(logging.DEBUG)
+        handler.addFilter(LevelFilter(low, high))
+        root.addHandler(handler)
+        handlers.append(handler)
+
+    def add_file(path: Path, low: int, high: int, mode: str = "a", as_json: bool = False) -> None:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handler = logging.FileHandler(path, mode=mode, encoding="utf8")
+        handler.setFormatter(JsonFormatter(redactor) if as_json else TextFormatter(FILE_FORMAT, config.tz, redactor))
+        add(handler, low, high)
+        files.append((path, low, high, "replace" if mode == "w" else "append"))
+
+    try:
+        _add_all_handlers(config, redactor, add, add_file)
+    except BaseException:
+        # A half-built setup must not stay on root, untracked: a retry would double every line.
+        for handler in handlers:
+            root.removeHandler(handler)
+            handler.close()
+        raise
+
+    root.setLevel(config.level)
+    # The library's own records (retention count) stay visible under a WARNING root.
+    logging.getLogger("ezpy_logs").setLevel(logging.INFO)
+    for name in config.app_loggers:
+        logging.getLogger(name).setLevel(config.app_level)
+    _state = _State(config=config, legacy=legacy, handlers=handlers, files=files)
+
+    if redactor.ignored_literals:
+        _logger.debug(f"{redactor.ignored_literals} redact value(s) ignored: shorter than 8 characters")
+    if config.retention_days is not None:
+        delete_old_logs(config.log_dir, config.retention_days, keep=[f[0] for f in files])
+    _logger.debug(f"Logging setup complete ! log_dir = {config.log_dir}")
+
+
+def _add_all_handlers(config: Config, redactor: Redactor, add, add_file) -> None:
+    # stdout takes everything below WARNING, custom levels (SUCCESS=25) included.
+    for stream, low, high in ((sys.stdout, logging.DEBUG, logging.WARNING - 1), (sys.stderr, logging.WARNING, logging.CRITICAL)):
+        handler = logging.StreamHandler(stream)
+        handler.setFormatter(TextFormatter(TERMINAL_FORMAT, config.tz, redactor, color=_use_color(stream)))
+        add(handler, low, high)
+
+    d = config.log_dir
+    if config.run_id is not None:
+        add_file(d / f"{config.run_id}.log", logging.DEBUG, logging.CRITICAL)
+        if config.json:
+            add_file(d / f"{config.run_id}.jsonl", logging.DEBUG, logging.CRITICAL, as_json=True)
+    else:
+        name = f"{file_stamp(time.time(), config.tz)}_{os.getpid()}"
+        add_file(d / "archive" / f"{name}.log", logging.DEBUG, logging.CRITICAL)
+        add_file(d / "archive_ERRORS" / f"{name}.log", logging.WARNING, logging.CRITICAL)
+        if config.json:
+            add_file(d / "archive" / f"{name}.jsonl", logging.DEBUG, logging.CRITICAL, as_json=True)
+    if config.latest:
+        add_file(d / "Latest.log", logging.DEBUG, logging.CRITICAL, mode="w")
+        add_file(d / "Latest_ERRORS.log", logging.WARNING, logging.CRITICAL, mode="w")
+
+
+def _use_color(stream) -> bool:
+    if "NO_COLOR" in os.environ:
+        return False
+    try:
+        return stream.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def _teardown() -> None:
+    """Removes and closes the handlers of the current setup, if any."""
+    global _state
+    if _state is None:
+        return
+    root = logging.getLogger()
+    for handler in _state.handlers:
+        root.removeHandler(handler)
+        handler.close()
+    _state = None
+
+
+def delete_old_logs(log_dir: str | os.PathLike, n_days: float, keep: Iterable[Path] = ()) -> int:
+    """Deletes `*.log` / `*.jsonl` files older than n_days inside `<log_dir>/archive/` and
+    `<log_dir>/archive_ERRORS/`.
+
+    Only regular files directly inside the library's own archive directories are touched:
+    never directories, never symlinks, never anything else in log_dir, never `keep` (the
+    live files of the current setup). Returns the count.
+    """
+    cutoff = time.time() - n_days * 86400
+    keep = {Path(p).absolute() for p in keep}
+    deleted = 0
+    for archive in (Path(log_dir) / name for name in _OWN_DIRS):
+        if not archive.is_dir() or archive.is_symlink():
+            continue
+        for path in archive.iterdir():
+            if path.suffix not in _OWN_SUFFIXES or path.is_symlink() or not path.is_file():
+                continue
+            if path.absolute() in keep:
+                continue
+            try:
+                if path.stat().st_mtime <= cutoff:
+                    path.unlink()
+                    deleted += 1
+            except FileNotFoundError:
+                # Protect against race condition, ie: multiple cron jobs using ezpy_logs
+                pass
+    # INFO only when something went: a count of 0 on every startup is noise.
+    _logger.log(
+        logging.INFO if deleted else logging.DEBUG,
+        f"Retention: deleted {deleted} log file(s) older than {n_days} days in {log_dir}",
+    )
+    return deleted
+
+
+class TqdmToLogger(io.StringIO):
+    """Output stream for TQDM which will output to logger module instead of the StdOut."""
+
+    def __init__(self, logger: logging.Logger, level: int | None = None) -> None:
+        super().__init__()
+        self.logger = logger
+        self.level = level or logging.INFO
+        self.buf = ""
+
+    def write(self, buf: str) -> int:
+        self.buf = buf.strip("\r\n\t ")
+        return len(buf)
+
+    def flush(self) -> None:
+        if self.buf:
+            self.logger.log(self.level, self.buf)
+            self.buf = ""

ezpy_logs/_format.py

@@ -0,0 +1,97 @@
+# ABOUTME: Formatters for ezpy_logs sinks: terminal (optionally coloured), text file, JSON lines.
+# ABOUTME: Each one redacts its output; timestamps are ISO 8601 with milliseconds and an explicit zone.
+import json
+import logging
+from datetime import datetime, timezone
+
+from ezpy_logs._redact import Redactor
+
+TERMINAL_FORMAT = "%(levelname)-7s : %(asctime)s %(relativeCreated)7d ms [Thread %(thread)-5d] %(pathname)50s:%(lineno)-4s ||  %(message)s"
+FILE_FORMAT = "%(levelname)s %(asctime)s | [%(relativeCreated)d] Thread %(thread)-5d || [%(pathname)s:%(lineno)s] %(funcName)s || %(message)s"
+
+_RESET = "\x1b[39m"
+_COLORS = {
+    logging.DEBUG: "\x1b[32m",  # green
+    logging.INFO: "\x1b[34m",  # blue
+    logging.WARNING: "\x1b[33m",  # yellow
+    logging.ERROR: "\x1b[35m",  # magenta
+    logging.CRITICAL: "\x1b[31m",  # red
+}
+
+# Every attribute a bare LogRecord carries; anything else on a record came from extra={...}.
+_RECORD_ATTRS = frozenset(vars(logging.LogRecord("", 0, "", 0, "", None, None))) | {
+    "message",
+    "asctime",
+    "taskName",
+}
+
+
+def iso_time(created: float, tz: str) -> str:
+    """ISO 8601 with milliseconds: `...Z` in UTC mode, `...-07:00` in local mode."""
+    if tz == "local":
+        return datetime.fromtimestamp(created).astimezone().isoformat(timespec="milliseconds")
+    stamp = datetime.fromtimestamp(created, timezone.utc).isoformat(timespec="milliseconds")
+    return stamp.replace("+00:00", "Z")
+
+
+def file_stamp(created: float, tz: str) -> str:
+    """File-name-safe timestamp: `2026-09-28T21-31-28Z` or `2026-09-28T14-31-28-0700`."""
+    if tz == "local":
+        return datetime.fromtimestamp(created).astimezone().strftime("%Y-%m-%dT%H-%M-%S%z")
+    return datetime.fromtimestamp(created, timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
+
+
+class TextFormatter(logging.Formatter):
+    """Plain or coloured text; the whole formatted line (traceback included) is redacted."""
+
+    def __init__(self, fmt: str, tz: str, redactor: Redactor, color: bool = False) -> None:
+        super().__init__(fmt)
+        self._tz = tz
+        self._redact = redactor
+        self._color = color
+
+    def formatTime(self, record: logging.LogRecord, datefmt: str | None = None) -> str:
+        return iso_time(record.created, self._tz)
+
+    def format(self, record: logging.LogRecord) -> str:
+        line = self._redact(super().format(record))
+        if self._color and record.levelno in _COLORS:
+            head, sep, tail = line.partition("||")
+            if sep:
+                return f"{_COLORS[record.levelno]}{head}{sep}{_RESET}{tail}"
+        return line
+
+
+class JsonFormatter(logging.Formatter):
+    """One JSON object per record. `ts` is always UTC, whatever the text sinks use.
+
+    Values are redacted BEFORE serialisation: in the serialised line a newline is the two
+    characters `\\n`, which multi-line patterns (PEM blocks) would not match.
+    """
+
+    def __init__(self, redactor: Redactor) -> None:
+        super().__init__()
+        self._redact = redactor
+
+    def format(self, record: logging.LogRecord) -> str:
+        entry: dict[str, object] = {
+            "ts": iso_time(record.created, "utc"),
+            "level": record.levelname,
+            "logger": record.name,
+            "msg": record.getMessage(),
+            "file": record.pathname,
+            "line": record.lineno,
+            "func": record.funcName,
+            "pid": record.process,
+            "thread": record.thread,
+        }
+        if record.exc_info:
+            entry["exc"] = self.formatException(record.exc_info)
+        elif record.exc_text:
+            entry["exc"] = record.exc_text
+        if record.stack_info:
+            entry["stack"] = self.formatStack(record.stack_info)
+        for key, value in vars(record).items():
+            if key not in _RECORD_ATTRS and key not in entry:
+                entry[key] = value
+        return json.dumps(self._redact.value(entry), ensure_ascii=False)

ezpy_logs/_redact.py

@@ -0,0 +1,85 @@
+# ABOUTME: Best-effort secret redaction applied by every ezpy_logs formatter.
+# ABOUTME: Replaces known token shapes and caller-given literal values with [REDACTED:<kind>].
+import math
+import re
+from collections.abc import Iterable
+
+# Literal values shorter than this are ignored: redacting "1" or "true" everywhere
+# would destroy the logs without protecting anything.
+MIN_LITERAL_LENGTH = 8
+
+_KV_KEYS = r"password|passwd|token|secret|api_key|apikey"
+
+# Order matters: longer, more specific shapes first (sk-ant- before sk-).
+_PATTERNS: list[tuple[str, re.Pattern[str]]] = [
+    (
+        "private_key",
+        re.compile(
+            r"-----BEGIN [A-Z ]*PRIVATE KEY-----(?:.*?-----END [A-Z ]*PRIVATE KEY-----|.*)",
+            re.DOTALL,
+        ),
+    ),
+    ("bearer", re.compile(r"(?i)\bbearer\s+[A-Za-z0-9\-._~+/]+=*")),
+    ("google_oauth", re.compile(r"\bya29\.[0-9A-Za-z\-_]+")),
+    ("github", re.compile(r"\b(?:gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,})")),
+    ("huggingface", re.compile(r"\bhf_[A-Za-z0-9]{20,}")),
+    ("anthropic", re.compile(r"\bsk-ant-[A-Za-z0-9\-_]{20,}")),
+    ("openai", re.compile(r"\bsk-[A-Za-z0-9\-_]{20,}")),
+    ("aws_key", re.compile(r"\b(?:AKIA|ASIA)[0-9A-Z]{16}\b")),
+    ("basic_auth", re.compile(r"(?i)\bbasic\s+[A-Za-z0-9+/]{8,}=*")),
+]
+
+# A sensitive key name, alone or inside a longer one: GITHUB_TOKEN, access_token,
+# client_secret, AWS_SECRET_ACCESS_KEY, db-password. `_` counts as a separator.
+# The only suffix allowed is _KEY / _ACCESS_KEY: token_count=512 is not a secret.
+_KEY_NAME = rf"(?:[A-Za-z0-9]+[_-])*(?:{_KV_KEYS})(?:[_-](?:access[_-])?key)?"
+_SENSITIVE_KEY = re.compile(rf"(?i){_KEY_NAME}")
+
+# key=value / key: value / 'key': 'value' / key="quoted value with spaces".
+# The key name is kept, the value never is.
+_KV = re.compile(
+    rf"(?i)(?<![A-Za-z0-9])({_KEY_NAME})(?![A-Za-z0-9])(['\"]?\s*[=:]\s*)"
+    rf"(?!['\"]?\[REDACTED)(?:\"[^\"\n]*\"?|'[^'\n]*'?|[^\s,;&'\"}}\]]+)"
+)
+
+
+class Redactor:
+    def __init__(self, literals: Iterable[str] = ()) -> None:
+        kept = sorted(
+            {v for v in literals if isinstance(v, str) and len(v) >= MIN_LITERAL_LENGTH},
+            key=len,
+            reverse=True,
+        )
+        self.ignored_literals = sum(
+            1 for v in literals if not isinstance(v, str) or len(v) < MIN_LITERAL_LENGTH
+        )
+        self._literals = re.compile("|".join(map(re.escape, kept))) if kept else None
+
+    def __call__(self, text: str) -> str:
+        if self._literals is not None:
+            text = self._literals.sub("[REDACTED:value]", text)
+        for kind, pattern in _PATTERNS:
+            text = pattern.sub(f"[REDACTED:{kind}]", text)
+        return _KV.sub(lambda m: f"{m.group(1)}{m.group(2)}[REDACTED:{m.group(1).lower()}]", text)
+
+    def value(self, obj: object) -> object:
+        """Redacts a JSON-bound value: strings directly, containers recursively,
+        anything else through its str() so nothing reaches json.dumps unredacted."""
+        if obj is None or isinstance(obj, (bool, int)):
+            return obj
+        if isinstance(obj, float):
+            # NaN / inf are not JSON: strict parsers reject the line.
+            return obj if math.isfinite(obj) else str(obj)
+        if isinstance(obj, str):
+            return self(obj)
+        if isinstance(obj, dict):
+            return {self(str(k)): self._keyed(str(k), v) for k, v in obj.items()}
+        if isinstance(obj, (list, tuple, set, frozenset)):
+            return [self.value(v) for v in obj]
+        return self(str(obj))
+
+    def _keyed(self, key: str, value: object) -> object:
+        """A value under a sensitive key name (extra={"password": ...}) is redacted whole."""
+        if value is not None and not isinstance(value, (dict, list, tuple)) and _SENSITIVE_KEY.fullmatch(key):
+            return f"[REDACTED:{key.lower()}]"
+        return self.value(value)

ezpy_logs-0.2.0.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.5
+Name: ezpy_logs
+Version: 0.2.0
+Summary: EzPy Logs: swiss knife logging for personal use
+Project-URL: Homepage, https://github.com/ezalos/ezpy_logs
+Project-URL: Repository, https://github.com/ezalos/ezpy_logs
+Author-email: ezalos <ezalos@github.com>
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Logging
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# EZPY Logs
+
+Package for my personal use, swiss knife logging :
+- When logging, has a nice formatter with file line and datetime (ISO 8601, UTC by default)
+- Colorful logger (only on a terminal; `NO_COLOR` turns it off)
+- Easy import / use: `setup()` once, `get_logger()` everywhere
+- Save to files, with errors, and optionally JSON lines for machines
+- Best-effort secret redaction in every sink
+- Opt-in deletion of its own old logs
+
+No runtime dependencies.
+
+## Install
+
+```
+uv add ezpy-logs
+```
+
+## Usage
+
+```py
+import ezpy_logs
+
+logger = ezpy_logs.get_logger(__name__)  # safe at module level: creates nothing
+
+def main():
+    ezpy_logs.setup(app_loggers=["my_package"])  # once, from the application
+    logger.info("Hello from ezpy-logs!")
+
+if __name__ == "__main__":
+    main()
+```
+
+```sh
+uv run python hello.py
+```
+
+Library code only calls `get_logger`. Nothing is configured and no file is written until
+the application calls `setup()`.
+
+### `setup()` arguments
+
+| Argument | Default | Meaning |
+|---|---|---|
+| `log_dir` | `$EZPY_LOGS_DIR`, else `.logs` | Where files go. |
+| `level` | `$EZPY_LOGS_LEVEL`, else `WARNING` | Root level: every logger you don't own (urllib3, botocore...). |
+| `app_loggers` | `()` | Your own logger names (usually your package); set to `app_level`. |
+| `app_level` | `DEBUG` | Level of `app_loggers`. |
+| `run_id` | `None` | Write `<log_dir>/<run_id>.log` (+ `.jsonl`) instead of timestamped archives. |
+| `json` | `$EZPY_LOGS_JSON == "1"` | Also write JSON lines. |
+| `tz` | `$EZPY_LOGS_TZ`, else `"utc"` | `"utc"` or `"local"` (with offset) for file names and text lines. JSON `ts` is always UTC. |
+| `latest` | on, off with `run_id` | Also write `Latest.log` / `Latest_ERRORS.log`, overwritten by each run. |
+| `retention_days` | `None` (never delete) | Delete this library's own `archive*/*.log`/`*.jsonl` older than N days. |
+| `redact_values` | `()` | Literal secrets to redact (values under 8 characters are ignored). |
+
+Calling `setup()` again with the same arguments does nothing; with different arguments it
+raises `RuntimeError`.
+
+Environment variables: `EZPY_LOGS_DIR`, `EZPY_LOGS_LEVEL`, `EZPY_LOGS_JSON=1`,
+`EZPY_LOGS_TZ`, `NO_COLOR`.
+
+### What each sink looks like
+
+Terminal (DEBUG/INFO on stdout, WARNING and above on stderr):
+
+```
+INFO    : 2026-09-28T21:46:49.393Z      14 ms [Thread 138181901391680]                          hello.py:12   ||  Hello from ezpy-logs!
+WARNING : 2026-09-28T21:46:49.393Z      14 ms [Thread 138181901391680]                          hello.py:13   ||  token=[REDACTED:token] never reaches a sink
+```
+
+Files, by default:
+
+```
+.logs/archive/2026-09-28T21-46-49Z_1428568.log          everything
+.logs/archive/2026-09-28T21-46-49Z_1428568.jsonl        everything, when json is on
+.logs/archive_ERRORS/2026-09-28T21-46-49Z_1428568.log   WARNING and above
+.logs/Latest.log / Latest_ERRORS.log                    this run only
+```
+
+A text file line:
+
+```
+INFO 2026-09-28T21:46:49.393Z | [14] Thread 138181901391680 || [/path/hello.py:12] main || Hello from ezpy-logs!
+```
+
+A JSON line (`extra={...}` fields are merged in; `exc` holds the traceback when there is one):
+
+```json
+{"ts": "2026-09-28T21:46:49.393Z", "level": "WARNING", "logger": "__main__", "msg": "token=[REDACTED:token] never reaches a sink", "file": "/path/hello.py", "line": 13, "func": "main", "pid": 1428568, "thread": 138181901391680, "job": 7}
+```
+
+### Secret redaction is best effort
+
+Every ezpy_logs sink redacts bearer tokens, `ya29.` Google OAuth tokens, `ghp_`/`github_pat_`,
+`hf_`, `sk-`/`sk-ant-`, `AKIA` AWS keys, PEM private-key blocks, `password=`/`token=`/`secret=`
+values, and the literal `redact_values`. Regexes cannot catch every secret, and a handler someone
+else adds (Sentry, pytest's caplog) bypasses it: do not rely on it as a security boundary.
+
+### With tqdm
+
+```py
+from tqdm import tqdm
+import ezpy_logs
+
+logger = ezpy_logs.get_logger(__name__)
+for name in tqdm(files, file=ezpy_logs.TqdmToLogger(logger), miniters=1e4, maxinterval=float("inf")):
+    ...
+```
+
+### Migrating from 0.1
+
+`from ezpy_logs.LoggerFactory import LoggerFactory` still works until 0.3, including its
+implicit setup in `./.logs` (it emits a `DeprecationWarning` once). A `setup()` call always
+replaces a `LoggerFactory` setup. See `CHANGELOG.md` for every behaviour change.
+
+## Dev
+
+### Local env setup
+
+```sh
+uv sync
+source .venv/bin/activate
+```
+
+### TESTING
+
+```sh
+uv run pytest -v
+```
+
+### Publishing
+
+Change version in `pyproject.toml`, add a `CHANGELOG.md` entry. `UV_PUBLISH_TOKEN` in `.envrc`
+is a `pass://` ref (Agent vault, item `PIPY_TOKEN`), so publish through `secrets run`:
+
+```sh
+rip dist
+uv build && secrets run -- uv publish
+```

ezpy_logs-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+ezpy_logs/LoggerFactory.py,sha256=kitRzml3LP-ghYjRWZhz5MJTSHvzkK5z-uAegD5MxsQ,3640
+ezpy_logs/__init__.py,sha256=73G0n9VTabN37tYFRR058E1tr8_g0upAUTxssf0OvLM,369
+ezpy_logs/_core.py,sha256=hojIRas4Tkb2n5q_oYWki2flOTYk3va-25zlBQH_tBI,11226
+ezpy_logs/_format.py,sha256=-arupWZcVO-QcUdC1o0fwwSrve0rX1XqPvv0dgoWS9c,3938
+ezpy_logs/_redact.py,sha256=FEp7RDzIOTcS8WCihc0nb7101z8MlSWYBygjkqU3XcM,3890
+ezpy_logs/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ezpy_logs-0.2.0.dist-info/METADATA,sha256=Y-mhBQd4Sl861ldOdYya8LuxjxxPuwFbSHPXlsAbVuc,5391
+ezpy_logs-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+ezpy_logs-0.2.0.dist-info/RECORD,,

ezpy_logs-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any