liblaf-logging 0.1.0

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: Development and prerelease code 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.

⌨️ 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.