asyncio (PyPI backport)

Warnings

• breaking The `asyncio` package on PyPI is an obsolete backport for Python versions prior to 3.4. Installing it on modern Python (3.4+) can conflict with and break the standard library `asyncio` due to `sys.path` order. Version 4.0.0 and above of the PyPI package contain no code and exist solely to prevent accidental installation of outdated backports; it *should not be installed*.
  Fix: Do not install `asyncio` from PyPI. Remove it if already installed (`pip uninstall asyncio`) and rely on Python's standard library version.
• deprecated The `@asyncio.coroutine` decorator for defining coroutines was deprecated in Python 3.8 and completely removed in Python 3.10. Using it will result in `SyntaxError` or `DeprecationWarning` depending on the Python version.
  Fix: Always use the `async def` syntax for defining coroutines (e.g., `async def my_coroutine(): ...`).
• gotcha A very common mistake is calling an `async def` function without `await`ing it. This creates a coroutine object but does not schedule or run it, leading to silent bugs or unexpected behavior (e.g., the code inside the coroutine never executes).
  Fix: Always use `await` when calling an awaitable from within a coroutine (e.g., `await my_coroutine()`). If scheduling a task concurrently, use `asyncio.create_task()` or `asyncio.TaskGroup` and then await the task/group.
• gotcha `asyncio.run()` cannot be called when an event loop is already running in the current thread. This is a common issue in interactive environments like Jupyter notebooks or when attempting to nest `asyncio.run()` calls.
  Fix: In interactive shells or environments with a running event loop, `await` coroutines directly or use a mechanism like `nest_asyncio` (with caution in Python 3.14+). Avoid nested `asyncio.run()` calls; structure your application to have a single top-level entry point.
• breaking Python 3.12 introduced significant changes to `asyncio` affecting task management, exception handling within `TaskGroup`, and cancellation behavior. The `asyncio.get_event_loop()` function became stricter, and `asyncio.run()` now explicitly ensures the event loop and associated resources (like executors and async generators) are properly shut down by default. Code relying on low-level event loop interactions or specific task behavior might encounter breaking changes.
  Fix: Review and update code that interacts directly with event loop policies, relies on implicit loop creation, or has specific exception/cancellation handling, especially when upgrading from Python 3.11 or older. Adopt `asyncio.TaskGroup` for improved structural concurrency and error handling.
• breaking Python 3.14 changed `asyncio`'s internal implementation in ways that break previous workarounds for nested event loops, notably affecting libraries like `nest_asyncio`. This primarily impacts environments like Jupyter notebooks where an event loop is already active, preventing the automatic async-to-sync conversion previously offered by such workarounds.
  Fix: In Jupyter/IPython notebooks on Python 3.14+, use `await` directly for async methods. Synchronous wrappers relying on `nest_asyncio` may fail with `RuntimeError`. Migrate to explicit `await` calls for asynchronous operations.
• gotcha Using `asyncio.Lock` (or other synchronization primitives like `Semaphore`, `Event`) in a global scope and then repeatedly calling `asyncio.run()` can lead to `RuntimeError`. This happens because `asyncio.run()` creates a new event loop each time, and the global lock object might retain a stale reference to a previously closed loop.
  Fix: Initialize `asyncio` synchronization primitives within the scope of your `asyncio.run()` execution or pass them explicitly between coroutines to ensure they are associated with the correct, currently active event loop.

Install

• pip install asyncio Do NOT install; use stdlib instead

Imports

• asyncio

  import asyncio

  This imports the standard library `asyncio` module. The PyPI `asyncio` package should not be installed, as it can conflict with the standard library.

Quickstart

This quickstart demonstrates basic usage of the standard library `asyncio` module, showing how to define asynchronous functions (coroutines) with `async def`, pause execution with `await asyncio.sleep()`, and run the top-level coroutine using `asyncio.run()`.

import asyncio
import time

async def say_after(delay, what):
    await asyncio.sleep(delay)
    print(what)

async def main():
    print(f"started at {time.strftime('%X')}")

    await say_after(1, 'hello')
    await say_after(2, 'world')

    print(f"finished at {time.strftime('%X')}")

if __name__ == "__main__":
    # The recommended way to run the top-level async function.
    asyncio.run(main())