ezpy_logs 0.2.0__tar.gz

ezpy_logs-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+.envrc
+
+.logs
+__pycache__
+.venv
+.pytest_cache
+dist
+
+*.pyc
+*.pyo
+*.log

ezpy_logs-0.2.0/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## 0.2.0 (unreleased)
+
+New API: `ezpy_logs.setup(...)` once from the application, `ezpy_logs.get_logger(name)` everywhere.
+
+Behaviour changes:
+
+- **Files are written only after `setup()`.** `get_logger` never configures anything or creates
+  files. `LoggerFactory` keeps the old implicit setup in `./.logs` until 0.3, with a one-time
+  `DeprecationWarning`.
+- **`setup()` replaces a `LoggerFactory` setup**; a second `setup()` with different arguments raises
+  instead of being silently ignored.
+- **Handlers live on the root logger only**, and named loggers propagate. Third-party records now
+  reach the files; each record is written once.
+- **The root level defaults to WARNING** (`level=` / `EZPY_LOGS_LEVEL`). Your own loggers go to
+  DEBUG through `app_loggers=[...]`. `LoggerFactory.getLogger(name)` still sets `name` to DEBUG.
+- **UTC by default**: file names `2026-09-28T21-31-28Z_<pid>.log`, lines `2026-09-28T21:31:28.412Z`.
+  `tz="local"` keeps the machine's zone with its offset. (0.1 meant Paris time but used an invalid
+  zone name, so it was machine-local time.)
+- **The pid is in archive file names**: parallel workers no longer share a file.
+- **No colour when the stream is not a terminal**, or when `NO_COLOR` is set.
+- **stdout takes every level below WARNING**, so custom levels such as SUCCESS=25 reach the terminal.
+- **Old-log deletion is opt-in** (`retention_days=None` by default) and only touches `*.log` /
+  `*.jsonl` directly inside `<log_dir>/archive/` and `<log_dir>/archive_ERRORS/`: never symlinks,
+  never the current run's files, never anything else. It logs the count (INFO when non-zero). `LoggerFactory` keeps 0.1's 30-day retention, now with that narrower scope.
+- **`Latest.log` / `Latest_ERRORS.log` are written on every run** (`latest=True`), not only under
+  pytest; off by default with `run_id`.
+- `TqdmToLogger.flush` no longer logs empty lines.
+
+New:
+
+- JSON-lines sink (`json=True` / `EZPY_LOGS_JSON=1`).
+- Run-scoped files: `setup(run_id="job-42")` writes `<log_dir>/job-42.log` and `.jsonl`.
+- Best-effort secret redaction in every sink, plus `redact_values=[...]`. Key/value pairs are
+  caught under prefixed names (`GITHUB_TOKEN=`, `client_secret:`, `AWS_SECRET_ACCESS_KEY=`) and
+  quoted values with spaces; JSON extras under a sensitive key (`extra={"password": ...}`) are
+  redacted whole. `token_count=512` is left alone.
+- Env configuration: `EZPY_LOGS_DIR`, `EZPY_LOGS_LEVEL`, `EZPY_LOGS_JSON`, `EZPY_LOGS_TZ`, `NO_COLOR`.
+
+Packaging: no runtime dependencies (`colorama`, `python-dateutil` and `pytest` removed; pytest is a
+dev dependency); ships `py.typed`; `hello.py` is no longer packaged.
+
+Removed from `LoggerFactory`: `add_output_file`, `setup_logger` and the `replaced` attribute.
+`is_setup`, `base_logging_directory` and `output_files` are now read-only views of the live setup.

ezpy_logs-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,139 @@
+# 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/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-0.2.0/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"]