Install & Compatibility
Where this runs
tested against v0.4.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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 17.8MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.5s · import 0.000s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
wait_for
✓ from wait_for2 import wait_for
✗ from wait_for2 import wait_for2
This quickstart demonstrates the basic usage of `wait_for2` with a timeout, and then showcases the `race_handler` callback, including its 2-argument signature introduced in v0.3.0. The `race_handler` allows custom logic for outcomes where a task either completes or times out/gets cancelled.
import asyncio
from wait_for2 import wait_for2
async def task_that_might_timeout():
"""A mock async task that takes some time to complete."""
await asyncio.sleep(0.6)
return "Task completed!"
async def main():
print("--- Basic Timeout Example ---")
try:
# Attempt to run the task with a timeout shorter than its execution time
result = await wait_for2(task_that_might_timeout(), timeout=0.5)
print(f"Success: {result}")
except asyncio.TimeoutError:
print("Timeout: Task did not complete in time.")
print("\n--- Race Handler Example (v0.3.0+ signature) ---")
async def fast_task():
await asyncio.sleep(0.1)
return "Fast result"
async def slow_task():
await asyncio.sleep(1.0)
return "Slow result"
# Define a custom race handler that inspects the result and exception status
async def custom_race_handler(result, is_exception):
if is_exception:
print(f" Handler caught exception: {result.__class__.__name__}")
return "Handled exception scenario"
print(f" Handler caught completion: {result}")
return f"Handled: {result}"
# Scenario 1: Task completes within timeout, handler gets completion result
result_complete = await wait_for2(fast_task(), timeout=0.5, race_handler=custom_race_handler)
print(f" wait_for2 result (completion): {result_complete}")
# Scenario 2: Task times out, handler gets TimeoutError
result_timeout = await wait_for2(slow_task(), timeout=0.2, race_handler=custom_race_handler)
print(f" wait_for2 result (timeout): {result_timeout}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingThe `race_handler` callback signature changed in v0.3.0. It now receives two arguments: `(result, is_exception)`, where `is_exception` is a boolean indicating if the `result` is an exception.fixUpdate your `race_handler` function to accept two arguments: `async def my_handler(result, is_exception): ...`
affects: >=0.3.0
gotchaFor Python 3.12 and newer, `wait-for2`'s implementation internally prefers the builtin `asyncio.wait_for` where possible. While the API remains consistent, subtle behavioral differences might arise in extremely complex cancellation scenarios due to changes in the underlying asyncio primitives.fixGenerally no fix required as API compatibility is maintained. If encountering unexpected behavior in advanced cancellation logic, test carefully or consider previous Python versions for comparison if 3.12+ specific.
affects: >=0.4.0 (Python 3.12+)
gotchaIf you don't provide a `race_handler`, `wait_for2` will raise an `asyncio.TimeoutError` on timeout. This needs to be explicitly handled with a `try...except asyncio.TimeoutError` block, similar to the standard `asyncio.wait_for`.fixWrap calls to `wait_for2` in a `try...except asyncio.TimeoutError` block or provide a `race_handler` callback to manage timeout outcomes.
affects: All versions
Upgrade
Version history
0.4.1latest on PyPI · released Jun 13, 2025
Audit
Dependencies
No dependency data recorded yet.