cpython/Doc/library/asyncio-api-index.rst

243 lines
5.5 KiB
ReStructuredText
Raw Normal View History

.. currentmodule:: asyncio
====================
High-level API Index
====================
This page lists all high-level async/await enabled asyncio APIs.
Tasks
=====
Utilities to run asyncio programs, create Tasks, and
await on multiple things with timeouts.
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - :func:`run`
- Create event loop, run a coroutine, close the loop.
* - :func:`create_task`
- Start an asyncio Task.
* - ``await`` :func:`sleep`
- Sleep for a number of seconds.
* - ``await`` :func:`gather`
- Schedule and wait for things concurrently.
* - ``await`` :func:`wait_for`
- Run with a timeout.
* - ``await`` :func:`shield`
- Shield from cancellation.
* - ``await`` :func:`wait`
- Monitor for completion.
* - :func:`current_task`
- Return the current Task.
* - :func:`all_tasks`
- Return all tasks for an event loop.
* - :class:`Task`
- Task object.
* - :func:`run_coroutine_threadsafe`
- Schedule a coroutine from another OS thread.
* - ``for in`` :func:`as_completed`
- Monitor for completion with a ``for`` loop.
.. rubric:: Examples
* :ref:`Using asyncio.gather() to run things in parallel
<asyncio_example_gather>`.
* :ref:`Using asyncio.wait_for() to enforce a timeout
<asyncio_example_waitfor>`.
* :ref:`Cancellation <asyncio_example_task_cancel>`.
* :ref:`Using asyncio.sleep() <asyncio_example_sleep>`.
* See also the main :ref:`Tasks documentation page <coroutine>`.
Queues
======
Queues should be used to distribute work amongst multiple asyncio Tasks,
implement connection pools, and pub/sub patterns.
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - :class:`Queue`
- A FIFO queue.
* - :class:`PriorityQueue`
- A priority queue.
* - :class:`LifoQueue`
- A LIFO queue.
.. rubric:: Examples
* :ref:`Using asyncio.Queue to distribute workload between several
Tasks <asyncio_example_queue_dist>`.
* See also the :ref:`Queues documentation page <asyncio-queues>`.
Subprocesses
============
Utilities to spawn subprocesses and run shell commands.
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - ``await`` :func:`create_subprocess_exec`
- Create a subprocess.
* - ``await`` :func:`create_subprocess_shell`
- Run a shell command.
.. rubric:: Examples
* :ref:`Executing a shell command <asyncio_example_subprocess_shell>`.
* See also the :ref:`subprocess APIs <asyncio-subprocess>`
documentation.
Streams
=======
High-level APIs to work with network IO.
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - ``await`` :func:`connect`
- Establish a TCP connection to send and receive data.
* - ``await`` :func:`open_connection`
- Establish a TCP connection. (Deprecated in favor of :func:`connect`)
* - ``await`` :func:`connect_unix`
- Establish a Unix socket connection to send and receive data.
* - ``await`` :func:`open_unix_connection`
- Establish a Unix socket connection. (Deprecated in favor of :func:`connect_unix`)
* - :class:`StreamServer`
- Start a TCP server.
* - ``await`` :func:`start_server`
- Start a TCP server. (Deprecated in favor of :class:`StreamServer`)
* - :class:`UnixStreamServer`
- Start a Unix socket server.
* - ``await`` :func:`start_unix_server`
- Start a Unix socket server. (Deprecated in favor of :class:`UnixStreamServer`)
* - :func:`connect_read_pipe`
- Establish a connection to :term:`file-like object <file object>` *pipe*
to receive data.
* - :func:`connect_write_pipe`
- Establish a connection to :term:`file-like object <file object>` *pipe*
to send data.
* - :class:`Stream`
- Stream is a single object combining APIs of :class:`StreamReader` and
:class:`StreamWriter`.
* - :class:`StreamReader`
- High-level async/await object to receive network data. (Deprecated in favor of :class:`Stream`)
* - :class:`StreamWriter`
- High-level async/await object to send network data. (Deprecated in favor of :class:`Stream`)
.. rubric:: Examples
* :ref:`Example TCP client <asyncio_example_stream>`.
* See also the :ref:`streams APIs <asyncio-streams>`
documentation.
Synchronization
===============
Threading-like synchronization primitives that can be used in Tasks.
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - :class:`Lock`
- A mutex lock.
* - :class:`Event`
- An event object.
* - :class:`Condition`
- A condition object.
* - :class:`Semaphore`
- A semaphore.
* - :class:`BoundedSemaphore`
- A bounded semaphore.
.. rubric:: Examples
* :ref:`Using asyncio.Event <asyncio_example_sync_event>`.
* See also the documentation of asyncio
:ref:`synchronization primitives <asyncio-sync>`.
Exceptions
==========
.. list-table::
2018-09-14 20:57:11 -03:00
:widths: 50 50
:class: full-width-table
* - :exc:`asyncio.TimeoutError`
- Raised on timeout by functions like :func:`wait_for`.
Keep in mind that ``asyncio.TimeoutError`` is **unrelated**
to the built-in :exc:`TimeoutError` exception.
* - :exc:`asyncio.CancelledError`
- Raised when a Task is cancelled. See also :meth:`Task.cancel`.
.. rubric:: Examples
* :ref:`Handling CancelledError to run code on cancellation request
<asyncio_example_task_cancel>`.
* See also the full list of
:ref:`asyncio-specific exceptions <asyncio-exceptions>`.