Text of peps.python.org › pep-3156 as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

PEP 3156 – Asynchronous IO Support Rebooted: the “asyncio” Module | peps.python.org

PEP 3156 – Asynchronous IO Support Rebooted: the “asyncio” Module PEP 3156 – Asynchronous IO Support Rebooted: the “asyncio” Module Author : Guido van Rossum <guido at python.org> BDFL-Delegate : Antoine Pitrou <antoine at python.org> Discussions-To : python-tulip@googlegroups.com Status : Final Type : Standards Track Created : 12-Dec-2012 Python-Version : 3.3 Post-History : 21-Dec-2012 Replaces : 3153 Resolution : Python-Dev message Table of Contents Abstract Introduction Status Dependencies Module Namespace Interoperability Transports and Protocols Event Loop Interface Specification Event Loop Policy: Getting and Setting the Current Event Loop Passing an Event Loop Around Explicitly Specifying Times Embedded Event Loops Event Loop Classes Event Loop Methods Overview Event Loop Methods Starting, Stopping and Closing Basic Callbacks Thread interaction Internet name lookups Internet connections Wrapped Socket Methods I/O Callbacks Pipes and Subprocesses Signal callbacks Mutual Exclusion of Callbacks Exceptions Debug Mode Handles Servers Futures Transports Methods For All Transports Bidirectional Stream Transports Unidirectional Stream Transports Datagram Transports Subprocess Transports Protocols Stream Protocols Datagram Protocols Subprocess Protocol Callback Style Coroutines and the Scheduler Coroutines Waiting for Multiple Coroutines Sleeping Tasks The Scheduler Convenience Utilities Synchronization Locks Queues Miscellaneous Logging SIGCHLD handling on UNIX Wish List Open Issues References Acknowledgments Copyright Abstract This is a proposal for asynchronous I/O in Python 3, starting at Python 3.3.

Consider this the concrete proposal that is missing from PEP 3153 . The proposal includes a pluggable event loop, transport and protocol abstractions similar to those in Twisted, and a higher-level scheduler based on yield from ( PEP 380 ). The proposed package name is asyncio . Introduction Status A reference implementation exists under the code name Tulip. The Tulip repo is linked from the References section at the end.

Packages based on this repo will be provided on PyPI (see References) to enable using the asyncio package with Python 3.3 installations. As of October 20th 2013, the asyncio package has been checked into the Python 3.4 repository and released with Python 3.4-alpha-4, with “provisional” API status. This is an expression of confidence and intended to increase early feedback on the API, and not intended to force acceptance of the PEP.

The expectation is that the package will keep provisional status in Python 3.4 and progress to final status in Python 3.5. Development continues to occur primarily in the Tulip repo, with changes occasionally merged into the CPython repo. Dependencies Python 3.3 is required for many of the proposed features. The reference implementation (Tulip) requires no new language or standard library features beyond Python 3.3, no third-party modules or packages, and no C code, except for the (optional) IOCP support on Windows.

Module Namespace The specification here lives in a new top-level package, asyncio . Different components live in separate submodules of the package. The package will import common APIs from their respective submodules and make them available as package attributes (similar to the way the email package works). For such common APIs, the name of the submodule that actually defines them is not part of the specification. Less common APIs may have to explicitly be imported from their respective submodule, and in this case the submodule name is part of the specification.

Classes and functions defined without a submodule name are assumed to live in the namespace of the top-level package. (But do not confuse these with methods of various classes, which for brevity are also used without a namespace prefix in certain contexts.) Interoperability The event loop is the place where most interoperability occurs. It should be easy for (Python 3.3 ports of) frameworks like Twisted, Tornado, or even gevents to either adapt the default event loop implementation to their needs using a lightweight adapter or proxy, or to replace the default event loop implementation with an adaptation of their own event loop implementation. (Some frameworks, like Twisted, have multiple event loop implementations.

This should not be a problem since these all have the same interface.) In most cases it should be possible for two different third-party frameworks to interoperate, either by sharing the default event loop implementation (each using its own adapter), or by sharing the event loop implementation of either framework. In the latter case two levels of adaptation would occur (from framework A’s event loop to the standard event loop interface, and from there to framework B’s event loop).

Which event loop implementation is used should be under control of the main program (though a default policy for event loop selection is provided). For this interoperability to be effective, the preferred direction of adaptation in third party frameworks is to keep the default event loop and adapt it to the framework’s API. Ideally all third party frameworks would give up their own event loop implementation in favor of the standard implementation.

But not all frameworks may be satisfied with the functionality provided by the standard implementation. In order to support both directions of adaptation, two separate APIs are specified: An interface for managing the current event loop The interface of a conforming event loop An event loop implementation may provide additional methods and guarantees, as long as these are called out in the documentation as non-standard.

An event loop implementation may also leave certain methods unimplemented if they cannot be implemented in the given environment; however, such deviations from the standard API should be considered only as a last resort, and only if the platform or environment forces the issue. (An example would be a platform where there is a system event loop that cannot be started or stopped; see “Embedded Event Loops” below.) The event loop API does not depend on await/yield from .

Rather, it uses a combination of callbacks, additional interfaces (transports and protocols), and Futures. The latter are similar to those defined in PEP 3148 , but have a different implementation and are not tied to threads. In particular, the result() method raises an exception instead of blocking when a result is not yet ready; the user is expected to use callbacks (or await/yield from ) to wait for the result. All event loop methods specified as returning a coroutine are allowed to return either a Future or a coroutine, at the implementation’s choice (the standard implementation always returns coroutines).

All event loop methods documented as accepting coroutine arguments must accept both Futures and coroutines for such arguments. (A convenience function, ensure_future() , exists to convert an argument that is either a coroutine or a Future into a Future.) For users (like myself) who don’t like using callbacks, a scheduler is provided for writing asynchronous I/O code as coroutines using the PEP 380 yield from or PEP 492 await expressions.

The scheduler is not pluggable; pluggability occurs at the event loop level, and the standard scheduler implementation should work with any conforming event loop implementation. (In fact this is an important litmus test for conforming implementations.) For interoperability between code written using coroutines and other async frameworks, the scheduler defines a Task class that behaves like a Future. A framework that interoperates at the event loop level can wait for a Future to complete by adding a callback to the Future.

Likewise, the scheduler offers an operation to suspend a coroutine until a callback is called. If such a framework cannot use the Future and Task classes as-is, it may reimplement the loop.create_future() and loop.create_task() methods. T

The rest of this page is on the live site.