tqdm-loggable

0.4.1 · active · verified Sun Apr 12

tqdm-loggable is a petite Python package (current version 0.4.1) that provides logging-friendly TQDM progress bars. It automatically converts standard tqdm progress bars into periodic log messages when running in non-interactive or headless environments (e.g., Docker, CI/CD, background workers), ensuring that progress is visible in logs rather than being hidden by a lack of a TTY. This prevents applications from appearing frozen during long-running tqdm operations by sending regular progress reports to the configured logging backend. The project has low activity on GitHub, suggesting an infrequent release cadence.

Warnings

gotcha Do not confuse `tqdm-loggable` with `tqdm.contrib.logging`. They address different problems: `tqdm-loggable` converts progress bars to log messages in headless environments, while `tqdm.contrib.logging` redirects console log output to `tqdm.write()` to prevent interference with interactive bars.
Fix: Ensure you understand the distinct use cases. Use `tqdm-loggable` for headless logging; use `tqdm.contrib.logging` within interactive sessions to manage log output alongside progress bars.
gotcha tqdm-loggable automatically detects interactive vs. non-interactive sessions to determine whether to show an interactive bar or log messages. This auto-detection can be overridden by setting the `TQDM_LOGGABLE_FORCE` environment variable to `stdout` (force interactive), `logging` (force log output), or `auto` (restore default behavior).
Fix: If unexpected behavior occurs, check or explicitly set the `TQDM_LOGGABLE_FORCE` environment variable to control the output mode.
gotcha The GitHub repository for `tqdm-loggable` indicates low activity. This means new feature requests or bug reports might experience slower response times.
Fix: For feature requests or pull requests, the maintainers suggest poking them on Discord first to ensure visibility.
breaking When migrating from standard `tqdm` to `tqdm-loggable` in a headless environment, the expected output will change from no visible progress (or broken output) to periodic log messages. While this is the library's intended function, it is a significant behavioral change from `tqdm`'s default in non-interactive contexts.
Fix: Be aware of this behavioral shift. The `set_log_rate` function in `tqdm_loggable.tqdm_logging` can be used to control the frequency of log updates to suit your monitoring needs.

Install

pip install tqdm-loggable Install stable version

Imports

tqdm
```
from tqdm_loggable.auto import tqdm
```
To leverage tqdm-loggable's features, you must import its `tqdm` wrapper instead of the original `tqdm.auto.tqdm` or `tqdm.tqdm`.
tqdm_logging
```
from tqdm_loggable.tqdm_logging import tqdm_logging
```
Provides utilities for configuring tqdm-loggable's logging behavior, such as setting the log level and rate.

Quickstart

This quickstart demonstrates how to integrate `tqdm-loggable`. It configures standard Python logging, then uses `tqdm_loggable.auto.tqdm` to wrap an iterable. In an interactive terminal, this will show a normal progress bar. When run in a headless environment, or if `TQDM_LOGGABLE_FORCE=logging` is set, it will emit periodic log messages instead of an interactive bar, like 'Progress on: Processing items 10/20 rate:X it/s remaining:Y elapsed:Z'. The `set_log_rate` controls how frequently these log messages appear.

import datetime
import logging
import time
import os
from tqdm_loggable.auto import tqdm
from tqdm_loggable.tqdm_logging import tqdm_logging

# Configure basic logging
logger = logging.getLogger()
logger.setLevel(logging.INFO)
formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
handler = logging.StreamHandler()
handler.setFormatter(formatter)
logger.addHandler(handler)

# Optional: Set tqdm-loggable's log level and update rate
tqdm_logging.set_level(logging.INFO)
tqdm_logging.set_log_rate(datetime.timedelta(seconds=2))

# You can force logging mode by setting an environment variable:
# os.environ['TQDM_LOGGABLE_FORCE'] = 'logging' # Forcing log output
# os.environ['TQDM_LOGGABLE_FORCE'] = 'stdout'  # Forcing console bar
# os.environ['TQDM_LOGGABLE_FORCE'] = 'auto'   # Restore auto-detection

print("Starting a simulated task...")
for i in tqdm(range(20), desc="Processing items", unit="item"):
    time.sleep(0.5)
    if i == 5:
        logger.info("Mid-task progress report")

print("Task completed.")

view raw JSON →