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)inmain()), kloggy steps aside for good: no duplicates (Z2), and the app's levels apply (L3) - a stray
logging.warning(...)(which implicitly callsbasicConfig()) doesn't make kloggy step aside (Z3). Neither does a barebasicConfig()in the app, since kloggy can't tell it apart from a stray one: pass some non-default argument, e.g.level=logging.INFOorformat=..., or usekloggy.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__), notget_logger(__package__):- records would lose their module name (
pkg.subinstead ofpkg.sub.module), so individual modules can't be configured __package__is''underpython -m(i.e. the root logger) andNonein a script run directly
- records would lose their module name (
- outside
exceptblocks, 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 forlogger.error(e)anyway, X1) - log via the module logger, not the root logger (
logging.warning(...)etc.), ruff ruleLOG015catches these. Such calls implicitly callbasicConfig(). kloggy copes with that (Z3), but an app's ownbasicConfig(...)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_LEVELsets levels for packages using kloggy, e.g.KLOGGY_LEVEL=warning,pkg.sub=debug,pkg.noisy=off(V1). The syntax follows Rust'sRUST_LOG:offsilences a logger completely, and the most specific entry wins. These levels apply even if the app configures logging.KLOGGY_DISABLE=1disables kloggy completely, so logging behaves exactly as plain stdlib, e.g. if kloggy causes problems (L5)NO_COLORandFORCE_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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.