liblaf-logging 0.1.1

Caller-aware Rich logging for Python with rate limits, file output, warning hooks, and release-aware defaults.

Explore the docs »

Documentation · Source · Issues · Releases

✨ Features

• Caller-aware helpers: Module-level helpers resolve the first visible caller so log records keep useful logger names, functions, and line numbers.
• Rich output everywhere: Console and file handlers share Rich rendering, compact columns, highlighted messages, and Rich tracebacks.
• Per-record rate limits: Add extra={"limits": "1/minute"} or LimitOptions to suppress noisy repeated records.
• Process hooks: init() captures warnings and installs hooks for uncaught and unraisable exceptions.
• Release-aware defaults: .devN and prerelease distributions can log more verbosely while stable installed packages stay quiet.

📦 Installation

uv add liblaf-logging

🚀 Quick Start

import liblaf.logging

liblaf.logging.init(force=True)
liblaf.logging.info("ready")

init() configures process-wide logging. When it manages handlers itself, it creates a Rich console handler, optionally creates a Rich-formatted file handler, and attaches LimitsFilter to those managed handlers.

Use the module-level helpers when shared helpers should log as their caller.

import liblaf.logging


def announce() -> None:
    liblaf.logging.info("starting")

🚦 Rate-Limited Records

import liblaf.logging

liblaf.logging.warning(
    "still waiting",
    extra={"limits": "1/minute"},
)

For shared buckets or custom costs, pass LimitOptions.

from liblaf.logging.filters import LimitOptions

liblaf.logging.warning(
    "sync retry",
    extra={
        "limits": LimitOptions(
            "5/minute",
            namespace=("sync",),
            identifiers=("account-42",),
            cost=1,
        )
    },
)

⚙️ Configuration

Runtime settings are backed by liblaf-conf and the LOG_ environment prefix.

LOG_LEVEL=INFO LOG_FILE=logs/app.log python app.py

Settings control the default level, optional file path, timestamp format, relative timestamp display, hidden-frame prefixes, and release-aware traceback or warning filtering.

🧭 Release-Aware Defaults

SanitizedLogger raises the default level for modules that belong to selected installed distributions. .devN distributions use the development level, prerelease distributions use the prerelease level, and stable distributions keep the standard NOTSET logger default.

Only metadata from selected .devN or prerelease distributions is expanded. Exact files are matched directly, and .pth files in those distributions add source-tree prefixes. direct_url.json is intentionally not followed, so stable editable installs stay stable unless their distribution version is marked as development or prerelease.

⌨️ Local Development

git clone https://github.com/liblaf/logging.git
cd logging
uv sync
uv run pytest
mise run docs:build

📝 License

Copyright © 2026 liblaf.
This project is MIT licensed.