liblaf-logging 0.1.2

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: liblaf.logging.info() and friends attribute shared helper logs to the first visible caller frame.
• Rich console and file output: Handlers render compact time, level, location, highlighted messages, Rich renderables, pretty objects, and tracebacks.
• Per-record rate limits: Add extra={"limits": "1/minute"} or a LimitOptions object to suppress noisy repeat logs.
• Process hooks: init() captures warnings, uncaught exceptions, and unraisable exceptions through the standard logging pipeline.
• Release-aware defaults: Development and prerelease distributions can get louder logger defaults while stable installed modules stay at NOTSET.

📦 Installation

uv add liblaf-logging

🚀 Quick Start

import liblaf.logging

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

init() configures the root logger at INFO by default, installs Rich output, registers TRACE and ICECREAM level names, captures warnings, and adds exception hooks. When it creates handlers itself, each managed handler receives a LimitsFilter.

Use the module-level helpers when library or framework glue should log as the application code that called it.

import liblaf.logging


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

🚦 Rate Limits

Attach a limits value to an individual record.

import liblaf.logging

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

For shared buckets, custom identifiers, or non-default 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

Settings use the LOG_ environment prefix through liblaf-conf. The most common options are LOG_LEVEL, LOG_FILE, LOG_TIME_RELATIVE, LOG_HIDE_FRAME, and LOG_HIDE_STABLE_RELEASE.

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

🧭 Release-Aware Defaults

SanitizedLogger checks module files against selected installed distributions when a logger is created without an explicit level. .devN distributions use the development level, prerelease distributions use the prerelease level, and stable distributions keep the normal NOTSET logger default.

The classifier expands metadata only for those selected distributions. Exact files are matched directly, and .pth files from selected distributions add source-tree prefixes for editable-style layouts. Stable distribution metadata is not expanded, and direct_url.json is not followed.

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