waiter

library1.5.1pypypi✓ verified 88d ago

Waiter is a lightweight Python library providing utilities for delayed iteration, polling, and retrying operations. It's particularly useful for waiting for external resources, services, or conditions to become ready. The current version is 1.5.1, and it maintains an active release cadence with regular updates.

http-networking workflow testing

pip install waiter

github ↗package ↗docs ↗changelog ↗

INSTALL

IMPORT

SIG · WAITER

waiter

http-networkingpythonv1.5.1

Install

1.5s avg

Import

202ms

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 v1.5.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.920 runs

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

glibc

py 3.10–3.920 runs

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

16MB installed

● package 16MB

Code

Verified usage

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

wait

✓ from waiter import wait

Use for delayed iteration over an iterable.

until

✓ from waiter import until

Use for polling until a callable returns a truthy value.

until_successful

✓ from waiter import until_successful

Use for retrying a callable until it stops raising exceptions.

This quickstart demonstrates using `waiter.until_successful` to poll a function that initially fails but eventually succeeds. It illustrates how to define a retriable operation and handle potential `TimeoutError`.

import time from waiter import until_successful # Define a function that simulates checking a service or condition class ServiceChecker: def __init__(self): self.attempts = 0 def check_status(self): self.attempts += 1 if self.attempts < 3: # Simulate a temporary failure by raising an exception print(f"Attempt {self.attempts}: Service not ready yet...") raise ConnectionError("Service not available") else: # Simulate success after a few attempts print(f"Attempt {self.attempts}: Service is ready!") return f"Service ready after {self.attempts} attempts" checker = ServiceChecker() result = None try: # Use until_successful to retry calling the check_status method. # It will keep retrying until the callable succeeds (doesn't raise an exception) # or the timeout is reached. result = until_successful( checker.check_status, timeout=5, # Max time to wait in seconds pause=0.5 # Time to wait between retries in seconds ) print(f"Polling successful: {result}") except TimeoutError as e: print(f"Polling failed: {e}") except Exception as e: print(f"An unexpected error occurred: {e}")

Debug

Known issues

breakingThe `sleep_seconds` argument in `waiter.wait`, `until`, and `until_successful` was renamed to `pause` in version 1.3.0.

fix

Update your code to use `pause` instead of `sleep_seconds`. For example, `waiter.until(my_func, pause=1)`.

affects: >=1.3.0

gotcha`waiter.wait` expects an *iterable* (e.g., `range`, a list, or a generator) as its first argument, not a callable function. Passing a function will result in a `TypeError`.

fix

Ensure you provide an iterable object to `waiter.wait`. If you intend to poll a function, use `waiter.until` or `waiter.until_successful` instead. Example: `for _ in waiter.wait(range(10), pause=0.5): ...`

affects: All versions

gotcha`waiter.until_successful` only retries when the target callable *raises an exception*. It does *not* retry if the callable returns a falsy value (e.g., `None` or `False`). For that, you should use `waiter.until`.

fix

If your condition for retrying is a falsy return value, use `waiter.until`. If it's an exception, use `waiter.until_successful`. For example, `until(check_condition, timeout=10)` will retry if `check_condition()` returns `False` or `None`.

affects: All versions

gotchaIf the polling condition is not met within the specified `timeout`, `waiter` functions will raise a `TimeoutError`. Forgetting to handle this can lead to unhandled exceptions.

fix

Always wrap your `waiter` calls in a `try...except TimeoutError` block to gracefully handle scenarios where the condition isn't met in time.

affects: All versions

Errors

Common errors & fixes

TypeError: 'function' object is not iterable

You are passing a callable function to `waiter.wait`, which expects an iterable (like `range(N)` or a list).

fix

Provide an iterable object to `waiter.wait`. If you intended to poll a function for success, use `waiter.until` or `waiter.until_successful`. Correct example: `for _ in waiter.wait(range(5), pause=1): print('Waiting...')`

TypeError: '<callable_name>' object is not callable

You are passing the *result* of a function call to `waiter.until` or `waiter.until_successful` instead of the function object itself, or passing a non-callable object.

fix

Ensure you pass the function reference (the function name without parentheses) to `until` or `until_successful`. Correct example: `until_successful(my_function, timeout=5)` instead of `until_successful(my_function(), timeout=5)`.

TimeoutError: Callable did not return a truthy value or stop raising exceptions within X seconds

The target callable for `waiter.until` or `waiter.until_successful` did not meet its success condition (returned a truthy value/stopped raising exceptions) within the `timeout` period.

fix

Increase the `timeout` parameter if the operation genuinely takes longer, or decrease `pause` if more frequent checks are needed. Review the logic of your callable to ensure it eventually succeeds. Always catch `TimeoutError` to handle the failure gracefully.

Upgrade

Version history

1.5.1latest on PyPI · released Nov 2, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

45 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/coady/waiter ↗

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

docshttps://coady.github.io/waiter ↗

changeloghttps://github.com/coady/waiter/blob/main/CHANGELOG.md ↗