wait-for2

What it is and what it does

wait_for2 is a drop-in replacement for asyncio.wait_for() that addresses a family of race conditions present in Python's builtin implementation across versions 3.7–3.11. When a timeout fires and the inner future completes simultaneously, or when cancellation and completion occur at the same time, the builtin asyncio.wait_for() can either lose the future's result or ignore the cancellation request, depending on the Python version. wait_for2 instead raises a CancelledWithResultError that contains both the cancellation signal and the result, allowing caller code to decide how to handle the edge case. Alternatively, a callback-based race_handler can be provided to process the result without raising an exception.

The package is explicitly designed as a compatibility shim: on Python 3.12+, where the builtin asyncio.wait_for was fixed, wait_for2 delegates to the standard library unless a race_handler is explicitly passed. For Python 3.7–3.11, it provides consistent, predictable behavior across all versions and implementations (CPython and PyPy). It has no runtime dependencies and installs as a pure Python wheel.

Use it for:

• Ensuring timeout and cancellation safety in asyncio code that must support Python 3.7–3.11 without losing results or cancellation signals.
• Handling edge cases where a task completes and is cancelled in the same event-loop cycle, using either exception handling or a callback.
• Migrating legacy asyncio code from Python 3.7–3.10 to newer versions while maintaining consistent race-condition semantics.
• Building robust async libraries that need predictable timeout behavior across multiple Python versions and implementations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides an alternate implementation of asyncio.wait_for() that handles race conditions between simultaneous cancellation and future completion consistently across Python 3.7–3.13.

Yes, if you support Python 3.7–3.11 and need bulletproof timeout and cancellation semantics in asyncio code. The package is low-friction to install and has no dependencies. On Python 3.12+, it transparently uses the builtin implementation, so it is safe to leave in place during version upgrades. If you only target Python 3.12+, the builtin asyncio.wait_for is sufficient and this package is unnecessary.

Install

wait-for2 on PyPI

pip install wait-for2

uv add wait-for2

poetry add wait-for2

Installing wait-for2

Before you install

Low install friction; pure Python wheel with no runtime dependencies. Maintenance status is aging (last release June 2025, 427 days old), but the repository remains active and the package is explicitly designed to become unnecessary on Python 3.12+, where the builtin asyncio.wait_for was fixed.

License in practice

Licensed under Apache-2.0 (permissive), imposing no significant restrictions on use or redistribution in most contexts.

Quickstart

import asyncio
import wait_for2

task = asyncio.create_task(...)

try:
    result = await wait_for2.wait_for(task, 5.0)
except wait_for2.CancelledWithResultError as e:
    # Handle simultaneous cancellation and result
    result = e.result
    raise asyncio.CancelledError()

Requires Python 3.7 or later; on Python 3.12+ the package delegates to the builtin asyncio.wait_for unless a race_handler is explicitly provided.

Verify before relying

• Whether the package's race-condition handling callbacks (race_handler parameter) are thread-safe or have any async-context limitations.
• Performance overhead of wait_for2 compared to builtin asyncio.wait_for on Python 3.10–3.11.

Package facts

Evidence: wait_for2-0.4.1-py3-none-any.whl

Tags

More Software Development packages