logistro

library2.0.1pypypi✓ verified 24d ago

Logistro is an extremely light wrapper over Python's standard `logging` module, providing sensible defaults for logging configuration. It simplifies common logging setups and includes specialized functionality like `getPipeLogger()` for piping subprocess stderr to the main logger. The library is currently at version 2.0.1 and maintains an active development status, with recent releases focused on minor fixes and metadata updates.

observability

pip install logistro

github ↗package ↗

INSTALL

IMPORT

SIG · LOGISTRO

logistro

observabilitypythonv2.0.1

Install

1.5s avg

Import

56ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.0.1 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.058s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.054s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getLogger

✓ import logistro logger = logistro.getLogger(__name__)

This is the primary way to obtain a logger, and it ensures Logistro's default configuration is applied.

getPipeLogger

✓ import logistro pipe, logger = logistro.getPipeLogger(__name__ + '-subprocess')

Used for routing subprocess stderr to the Logistro logger.

set_structured

✓ import logistro logistro.set_structured()

Configures all loggers to output in JSON format. Must be called before any logging output.

set_human

✓ import logistro logistro.set_human()

Configures all loggers to output in human-readable format (default). Must be called before any logging output.

This quickstart demonstrates how to initialize Logistro, use its custom logging levels (`debug2`), integrate with subprocesses using `getPipeLogger()`, and dynamically switch between human-readable and structured (JSON) output formats.

import logistro import os import subprocess # Basic logger setup (automatically configured by getLogger) logger = logistro.getLogger(__name__) logger.debug2("This is a custom debug level (more verbose)") logger.debug("This is a standard debug message") logger.info("Application started") try: # Example with getPipeLogger for subprocesses # Note: In a real app, manage 'cli_command' securely (e.g., using shlex.split) cli_command = [os.environ.get('EXAMPLE_SUBPROCESS_COMMAND', 'ls'), '-l'] pipe, sub_logger = logistro.getPipeLogger(__name__ + '-subprocess') process = subprocess.Popen(cli_command, stderr=pipe) process.wait() # Wait for the subprocess to finish os.close(pipe) # Crucial to close the pipe after use sub_logger.info("Subprocess finished with exit code: %s", process.returncode) raise ValueError("Something went wrong") except ValueError as e: logger.exception("An error occurred: %s", e) # Switch to structured logging mid-execution (affects subsequent logs) logistro.set_structured() logger.info("This message is now structured (JSON)", user_id="123", event="test_event")

Debug

Known issues

gotchaWhen switching between human-readable (`set_human()`) and structured (`set_structured()`) logging formats, these functions must be called *before* any other logging calls. Calling them mid-execution with an existing logger requires an additional step (`logistro.coerce_logger(logistro.getLogger())`) to ensure the formatter is updated.

fix

Call `logistro.set_structured()` or `logistro.set_human()` early in your application's lifecycle, ideally before `logistro.getLogger()` is first called for the root logger. If changing mid-execution, re-coerce the logger: `logistro.set_structured(); logistro.coerce_logger(logistro.getLogger())`.

affects: 2.0.0+

gotchaThe `logistro.betterConfig()` function, which is implicitly called by `logistro.getLogger()`, accepts most arguments identical to Python's standard `logging.basicConfig()` but *ignores* the `format` argument. This is because Logistro manages its own formatting based on `set_human()` or `set_structured()`.

fix

Do not pass a `format` argument to `logistro.betterConfig()`. Instead, use `logistro.set_human()` (default) or `logistro.set_structured()` to control the output format globally.

affects: 2.0.0+

gotchaWhen using `logistro.getPipeLogger()` to capture subprocess output, it returns a pipe file descriptor. It is crucial to manually close this pipe using `os.close(pipe)` after the subprocess has completed to prevent resource leaks.

fix

Always ensure `os.close(pipe)` is called after the subprocess that uses the pipe has terminated and its output has been consumed or is no longer needed.

affects: 2.0.0+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'logistro'

The 'logistro' package has not been installed in the current Python environment.

fix

pip install logistro

AttributeError: module 'logistro' has no attribute 'getLogger'

The 'logistro' library uses 'get_logger' (with an underscore) to retrieve a logger instance, not 'getLogger' (camelCase).

fix

logger = logistro.get_logger(__name__)

AttributeError: 'NoneType' object has no attribute 'readline'

The `subprocess.Popen` object passed to `logistro.getPipeLogger()` was not configured with `stderr=subprocess.PIPE`, causing its `stderr` attribute to be `None`.

fix

import subprocess
import logistro

logistro.basicConfig()
logger = logistro.get_logger(__name__)

# Ensure stderr is piped
process = subprocess.Popen(
    ['your_command_here'],
    stderr=subprocess.PIPE # This is the crucial part
)
logistro.getPipeLogger(logger, process)
process.wait()

logistro debug messages not showing

The log level set in `logistro.basicConfig()` is higher than the level of the messages being logged (e.g., `INFO` is configured, but `DEBUG` messages are called).

fix

import logistro

# Set the basic configuration level to DEBUG or lower to see debug messages
logistro.basicConfig(level=logistro.DEBUG)
logger = logistro.get_logger(__name__)

logger.debug("This debug message will now be shown.")
logger.info("This is an info message.")

Upgrade

Version history

2.0.1latest on PyPI · released Nov 1, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

11 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/geopozo/logistro ↗

packagehttps://pypi.org/project/logistro/ ↗