Skip to main content

kloggy

Logging helper: nice zero-config output for libraries, without fighting the app's logging setup. It started as a shared helper for HPI, promnesia, orger, cachew and data exporters like rexport, but nothing in it is specific to them.

It's developed requirements-first: see requirements, linked to the tests validating them. Work in progress, only the requirements listed there are implemented so far.

Install with pip install kloggy (or uv add kloggy).

Library code gets plain stdlib loggers:

# mypkg/parse.py
from kloggy import get_logger

logger = get_logger(__name__)


def parse(paths: list[str]) -> None:
    for i, path in enumerate(paths, start=1):
        logger.info('processing [%d/%d] %s', i, len(paths), path)
        logger.debug('not shown by default')

Without any logging setup, parse(['a.json', 'b.json']) prints to stderr (F1):

[INFO    2026-10-11 20:20:01,730 mypkg.parse parse.py:8   ] processing [1/2] a.json
[INFO    2026-10-11 20:20:01,730 mypkg.parse parse.py:8   ] processing [2/2] b.json

Plain stdlib would print nothing here, since INFO is below its default WARNING.

  • if logging isn't configured, records are never printed as bare messages (Z1), and INFO is shown, e.g. for progress (L2)
  • if the app configures logging later (e.g. basicConfig(level=logging.DEBUG) in main()), kloggy steps aside for good: no duplicates (Z2), and the app's levels apply (L3)
  • a stray logging.warning(...) (which implicitly calls basicConfig()) doesn't make kloggy step aside (Z3). Neither does a bare basicConfig() in the app, since kloggy can't tell it apart from a stray one: pass some non-default argument, e.g. level=logging.INFO or format=..., or use kloggy.setup() instead (see below)
  • if the app already configured logging, kloggy doesn't touch it (L1)

Using kloggy in a package

Create a module-level logger in each module with get_logger(__name__), same as the usual stdlib convention logging.getLogger(__name__).

kloggy attaches its handler to the top-level package logger, i.e. the first dotted component of the name (pkg for pkg.sub.module). Levels can be configured for the whole package or for individual modules as usual:

logging.getLogger('pkg').setLevel(logging.DEBUG)  # all of pkg.*
logging.getLogger('pkg.module').setLevel(logging.WARNING)  # just this module

A module whose INFO is too chatty can pick its own default instead, e.g. get_logger(__name__, default_level='warning') (L6). Unlike setLevel() in the module, it's only kloggy's default, so levels set by the app or via KLOGGY_LEVEL still win.

Recommendations

  • use get_logger(__name__), not get_logger(__package__):
    • records would lose their module name (pkg.sub instead of pkg.sub.module), so individual modules can't be configured
    • __package__ is '' under python -m (i.e. the root logger) and None in a script run directly
  • outside except blocks, pass the exception explicitly, e.g. logger.error('while parsing %s', path, exc_info=e), so the traceback is kept with any logging setup (kloggy's output adds it for logger.error(e) anyway, X1)
  • log via the module logger, not the root logger (logging.warning(...) etc.), ruff rule LOG015 catches these. Such calls implicitly call basicConfig(). kloggy copes with that (Z3), but an app's own basicConfig(...) called later is then silently ignored.

Using kloggy in an app

Call kloggy.setup() in main() instead of logging.basicConfig() (A1):

import kloggy


def main() -> None:
    kloggy.setup()  # or e.g. kloggy.setup(level='debug')

Every logger then gets kloggy's output, also in libraries not using kloggy. Like with basicConfig(), root's level (INFO by default) applies to every logger, unless it or an ancestor has its own level set, e.g. via logging.getLogger('pkg').setLevel(...). KLOGGY_LEVEL still only applies to packages using kloggy: e.g. KLOGGY_LEVEL=vendor=off doesn't silence a vendor library which doesn't use kloggy, use logging.getLogger('vendor').setLevel(...) for that.

setup() does nothing if logging is already configured, e.g. by an earlier setup() call. The exception is root's default handler from a bare basicConfig(), e.g. a stray logging.warning(...): setup() replaces it.

datefmt works as in basicConfig(), e.g. datefmt='%Y-%m-%d %H:%M:%S' drops the milliseconds.

Environment variables

Users running a program can adjust kloggy's behaviour without changing any code:

  • KLOGGY_LEVEL sets levels for packages using kloggy, e.g. KLOGGY_LEVEL=warning,pkg.sub=debug,pkg.noisy=off (V1). The syntax follows Rust's RUST_LOG: off silences a logger completely, and the most specific entry wins. These levels apply even if the app configures logging.
  • KLOGGY_DISABLE=1 disables kloggy completely, so logging behaves exactly as plain stdlib, e.g. if kloggy causes problems (L5)
  • NO_COLOR and FORCE_COLOR: output is coloured by level on a terminal, via colorlog, which honours these to disable or force colour (F2)

KLOGGY_LEVEL and KLOGGY_DISABLE are read once, on the first get_logger() call (KLOGGY_DISABLE also on setup()), so set them before the program starts: setting os.environ in main() is usually too late, since imports have already called get_logger().

Development

The tooling follows pymplate. Install tox with its uv plugin once:

uv tool install --with tox-uv tox

Run the local checks with:

tox -e ruff,format,tests,mypy,ty

For a targeted test run, use tox -e tests -- -k <pattern>.

The requirements doc is rendered from doc/requirements.qmd with Quarto, run tox -e quarto after changing it or the tests. The rendered doc/requirements.md is committed, and CI checks it's up to date.

Releases

Pushes to the default branch publish to TestPyPI, and version tags such as v0.1.20261010 publish to PyPI, via GitHub Actions. The setup (Trusted Publishing, release scripts in .ci/) follows pymplate.

Metadata

Release files for kloggy 0.1.20261011

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kloggy 0.1.20261011
File Size Uploaded Provenance Actions
kloggy-0.1.20261011.tar.gz 71.1 kB Without provenance Details for kloggy-0.1.20261011.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kloggy 0.1.20261011
File Interpreter ABI Platform Actions
kloggy-0.1.20261011-py3-none-any.whl Python 3 none any Details for kloggy-0.1.20261011-py3-none-any.whl

Total release size: 113.5 kB

Release files / kloggy-0.1.20261011.tar.gz

Download URL kloggy-0.1.20261011.tar.gz
Size 71.1 kB
Tags Source
SHA-256 checksum
How to use checksums
7deb8c94f9223ac96907cffa893f5f0fb25f9c6fa894e3d1d8bcd49093a8b4a2
BLAKE2b-256 checksum
How to use checksums
878ca9bec112fe8f72973f3a1ddfd8bb968a6b8e6a8203d58fb45ecc243b68d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / kloggy-0.1.20261011-py3-none-any.whl

Download URL kloggy-0.1.20261011-py3-none-any.whl
Size 42.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eb7aff23b5f50cbbcabf7939e4fb1188a26503688d35db2c6d2720e6b2f64dd0
BLAKE2b-256 checksum
How to use checksums
27bbc64548e76d880be60e8c43212f792ebf5d58dca9f749017462de6898dacc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for kloggy 0.1.20261011

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page