Waiting for Stuff

1.5.0 · active · verified Sat Apr 11

The 'waiting' library provides a simple utility for busy-waiting, where the program pauses execution until a specified predicate function returns `True`. It supports various modes, including timeouts, custom sleep intervals, exponential backoff, and aggregation of multiple predicates (ANY/ALL). The current version is 1.5.0, released in August 2024, with a sporadic but recently updated release cadence.

Warnings

gotcha The `wait` function is a blocking operation. In asynchronous Python applications (e.g., using `asyncio`), directly calling `wait` will block the entire event loop, potentially freezing your application.
Fix: For asynchronous contexts, consider `asyncio.sleep()` or async-compatible polling libraries. If `waiting` must be used, run it in a separate thread or process to avoid blocking the main event loop.
gotcha By default, the `TimeoutExpired` exception provides a generic message. When dealing with complex waiting conditions, this can make debugging difficult.
Fix: Always use the `waiting_for` argument in `wait()` calls to provide a descriptive message. This message will be included in the `TimeoutExpired` exception, greatly aiding debugging. Example: `wait(predicate, timeout_seconds=..., waiting_for="database to be ready")`.
gotcha When using `ANY` or `ALL` with multiple predicates, the library's documentation notes that it does not call a predicate once it has been satisfied (for efficiency). If a predicate has side effects that are expected to occur on every poll, this behavior for `ANY`/`ALL` could be unexpected.
Fix: Ensure that predicates used with `ANY` or `ALL` are idempotent or that their side effects are not critical to occur on every single poll once satisfied. For predicates requiring continuous side effects, wrap them in a single predicate or handle side effects outside the predicate function.

Install

pip install waiting Install stable version

Imports

wait
```
from waiting import wait
```
The primary function to wait for a predicate to become true.
TimeoutExpired
```
from waiting import wait, TimeoutExpired
```
Exception raised when a wait operation exceeds its specified timeout.
ANY
```
from waiting import wait, ANY
```
Used with 'wait' to pause until any of a list of predicates returns true.
ALL
```
from waiting import wait, ALL
```
Used with 'wait' to pause until all of a list of predicates return true.

Quickstart

This quickstart demonstrates the core `wait` function, showing how to wait for a predicate to become true, handling timeouts, and customizing polling intervals. It also highlights the benefit of the `waiting_for` argument for clearer error messages.

import time
from waiting import wait, TimeoutExpired

def check_condition():
    # Simulate a condition that eventually becomes true
    if not hasattr(check_condition, 'counter'):
        check_condition.counter = 0
    check_condition.counter += 1
    print(f"Checking condition (attempt {check_condition.counter})...")
    return check_condition.counter >= 3

print("Starting to wait...")
try:
    # Wait for the condition for a maximum of 5 seconds, polling every 0.5 seconds
    # Use 'waiting_for' for more descriptive timeout messages
    result = wait(
        check_condition,
        timeout_seconds=5,
        sleep_seconds=0.5,
        waiting_for="the counter to reach 3"
    )
    print(f"Condition met! Result: {result}")
except TimeoutExpired as e:
    print(f"Wait timed out: {e}")

print("--- Demonstrating TimeoutExpired without waiting_for ---")
try:
    wait(lambda: False, timeout_seconds=0.1)
except TimeoutExpired as e:
    print(f"TimeoutExpired message (less descriptive): {e}")

view raw JSON →