Skip to content

C
cpython
Commit 1fa2ec49 authored by Elvis Pranskevichus's avatar Elvis Pranskevichus Committed by Yury Selivanov
Browse files
Options

bpo-33649: A copy-editing pass on asyncio documentation (GH-9376)

parent 3085534c
Show whitespace changes
Inline Side-by-side
Showing with 347 additions and 349 deletions
Doc/library/asyncio-dev.rst
View file @ 1fa2ec49
......@@ -6,7 +6,7 @@
Developing with asyncio
=======================
Asynchronous programming is different from classical "sequential"
Asynchronous programming is different from classic "sequential"
programming.
This page lists common mistakes and traps and explains how
......@@ -21,19 +21,17 @@ Debug Mode
By default asyncio runs in production mode. In order to ease
the development asyncio has a *debug mode*.
To enable debugging for an application:
There are several ways to enable asyncio debug mode:
* Enable the debug mode globally by setting the environment variable
:envvar:`PYTHONASYNCIODEBUG` to ``1``.
* Setting the :envvar:`PYTHONASYNCIODEBUG` environment variable to ``1``.
* Alternatively, the debug mode can be enabled by using the ``-X dev``
command line option for Python (see the :option:`-X` option).
* Using the :option:`-X` ``dev`` Python command line option.
* Yet another way to enable the debug mode is by calling
:meth:`loop.set_debug` or by passing ``debug=True`` to
:func:`asyncio.run`.
* Passing ``debug=True`` to :func:`asyncio.run`.
In addition to enabling debug mode, consider also:
* Calling :meth:`loop.set_debug`.
In addition to enabling the debug mode, consider also:
* setting the log level of the :ref:`asyncio logger <asyncio-logger>` to
:py:data:`logging.DEBUG`, for example the following snippet of code
......@@ -43,25 +41,25 @@ In addition to enabling debug mode, consider also:
* configuring the :mod:`warnings` module to display
:exc:`ResourceWarning` warnings. One way of doing that is by
using the ``-Wdefault`` command line option.
using the :option:`-W` ``default`` command line option.
In asyncio debug mode the following checks are performed:
When the debug mode is enabled:
* Log :ref:`coroutines that were not awaited
<asyncio-coroutine-not-scheduled>`; this mitigates the "forgotten
await" pitfall.
* asyncio checks for :ref:`coroutines that were not awaited
<asyncio-coroutine-not-scheduled>` and logs them; this mitigates
the "forgotten await" pitfall.
* Many non-treadsafe asyncio APIs (such as :meth:`loop.call_soon` and
:meth:`loop.call_at` methods) raise an exception if they are called
from a wrong thread.
* Log the execution time of the IO selector if it takes too long to
perform an IO operation.
* The execution time of the I/O selector is logged if it takes too long to
perform an I/O operation.
* Log callbacks taking longer than 100 ms to be executed. The
:attr:`loop.slow_callback_duration` attribute is the minimum
duration in seconds of "slow" callbacks.
* Callbacks taking longer than 100ms are logged. The
:attr:`loop.slow_callback_duration` attribute can be used to set the
minimum execution duration in seconds that is considered "slow".
.. _asyncio-multithreading:
......@@ -134,7 +132,7 @@ Logging
asyncio uses the :mod:`logging` module and all logging is performed
via the ``"asyncio"`` logger.
The default log level is :py:data:`logging.INFO`, which can easily be
The default log level is :py:data:`logging.INFO`, which can be easily
adjusted::
logging.getLogger("asyncio").setLevel(logging.WARNING)
......@@ -142,12 +140,13 @@ adjusted::
.. _asyncio-coroutine-not-scheduled:
Detect never awaited coroutines
Detect never-awaited coroutines
===============================
When a coroutine is called (e.g. ``coro()`` instead of ``await coro()``)
the call is not wrapped with :meth:`asyncio.create_task`, the execution
of the coroutine object will never be scheduled. For example::
When a coroutine function is called, but not awaited
(e.g. ``coro()`` instead of ``await coro()``)
or the coroutine is not scheduled with :meth:`asyncio.create_task`, asyncio
will emit a :exc:`RuntimeWarning`::
import asyncio
......@@ -184,8 +183,8 @@ The usual fix is to either await the coroutine or call the
await test()
Detect never consumed exceptions
================================
Detect never-retrieved exceptions
=================================
If a :meth:`Future.set_exception` is called but the Future object is
never awaited on, the exception would never be propagated to the
......
Doc/library/asyncio-eventloop.rst
View file @ 1fa2ec49
......@@ -8,20 +8,17 @@ Event Loop
.. rubric:: Preface
The event loop is a central component of every asyncio application.
The event loop is the core of every asyncio application.
Event loops run asynchronous tasks and callbacks, perform network
IO operations, and run subprocesses.
Application developers will typically use high-level asyncio functions
to interact with the event loop. In general, high-level asyncio applications
should not need to work directly with event loops and, instead, should use
the :func:`asyncio.run` function to initialize, manage the event loop, and
run asynchronous code.
Application developers should typically use the high-level asyncio functions,
such as :func:`asyncio.run`, and should rarely need to reference the loop
object or call its methods. This section is intended mostly for authors
of lower-level code, libraries, and frameworks, who need finer control over
the event loop behavior.
Alternatively, developers of low-level code, such as libraries and
framework, may need access to the event loop.
.. rubric:: Accessing Event Loop
.. rubric:: Obtaining the Event Loop
The following low-level functions can be used to get, set, or create
an event loop:
......@@ -68,16 +65,16 @@ and :func:`new_event_loop` functions can be altered by
This documentation page contains the following sections:
* The `Event Loop Methods`_ section is the reference documentation of
event loop APIs;
the event loop APIs;
* The `Callback Handles`_ section documents the :class:`Handle` and
:class:`TimerHandle`, instances which are returned from functions, such
as :meth:`loop.call_soon` and :meth:`loop.call_later`;
:class:`TimerHandle` instances which are returned from scheduling
methods such as :meth:`loop.call_soon` and :meth:`loop.call_later`;
* The `Server Objects`_ sections document types returned from
* The `Server Objects`_ section documents types returned from
event loop methods like :meth:`loop.create_server`;
* The `Event Loops Implementations`_ section documents the
* The `Event Loop Implementations`_ section documents the
:class:`SelectorEventLoop` and :class:`ProactorEventLoop` classes;
* The `Examples`_ section showcases how to work with some event
......@@ -101,11 +98,11 @@ Running and stopping the loop
.. method:: loop.run_until_complete(future)
Run until the *future* (an instance of :class:`Future`) is
Run until the *future* (an instance of :class:`Future`) has
completed.
If the argument is a :ref:`coroutine object <coroutine>` it
is implicitly wrapped into an :class:`asyncio.Task`.
is implicitly scheduled to run as a :class:`asyncio.Task`.
Return the Future's result or raise its exception.
......@@ -120,7 +117,7 @@ Running and stopping the loop
If :meth:`stop` is called while :meth:`run_forever` is running,
the loop will run the current batch of callbacks and then exit.
Note that callbacks scheduled by callbacks will not run in this
Note that new callbacks scheduled by callbacks will not run in this
case; instead, they will run the next time :meth:`run_forever` or
:meth:`run_until_complete` is called.
......@@ -167,8 +164,6 @@ Running and stopping the loop
.. versionadded:: 3.6
.. _asyncio-pass-keywords:
Scheduling callbacks
^^^^^^^^^^^^^^^^^^^^
......@@ -201,18 +196,19 @@ Scheduling callbacks
The *context* keyword-only parameter was added. See :pep:`567`
for more details.
.. _asyncio-pass-keywords:
.. note::
Most :mod:`asyncio` scheduling functions don't allow passing
keyword arguments. To do that, use :func:`functools.partial`,
e.g.::
keyword arguments. To do that, use :func:`functools.partial`::
# will schedule "print("Hello", flush=True)"
loop.call_soon(
functools.partial(print, "Hello", flush=True))
Using partial objects is usually more convenient than using lambdas,
as asyncio can better render partial objects in debug and error
as asyncio can render partial objects better in debug and error
messages.
......@@ -235,8 +231,8 @@ clocks to track time.
be used to cancel the callback.
*callback* will be called exactly once. If two callbacks are
scheduled for exactly the same time, it is undefined which one will
be called first.
scheduled for exactly the same time, the order in which they
are called is undefined.
The optional positional *args* will be passed to the callback when
it is called. If you want the callback to be called with keyword
......@@ -250,6 +246,11 @@ clocks to track time.
The *context* keyword-only parameter was added. See :pep:`567`
for more details.
.. versionchanged:: 3.8
In Python 3.7 and earlier with the default event loop implementation,
the *delay* could not exceed one day.
This has been fixed in Python 3.8.
.. method:: loop.call_at(when, callback, *args, context=None)
Schedule *callback* to be called at the given absolute timestamp
......@@ -265,6 +266,11 @@ clocks to track time.
The *context* keyword-only parameter was added. See :pep:`567`
for more details.
.. versionchanged:: 3.8
In Python 3.7 and earlier with the default event loop implementation,
the difference between *when* and the current time could not exceed
one day. This has been fixed in Python 3.8.
.. method:: loop.time()
Return the current time, as a :class:`float` value, according to
......@@ -314,11 +320,10 @@ Creating Futures and Tasks
:meth:`loop.create_task`.
If *factory* is ``None`` the default task factory will be set.
If *factory* is a *callable*, it should have a signature matching
``(loop, coro)``, where *loop* will be a reference to the active
event loop, *coro* will be a coroutine object. The callable
must return an :class:`asyncio.Future` compatible object.
Otherwise, *factory* must be a *callable* with the signature matching
``(loop, coro)``, where *loop* is a reference to the active
event loop, and *coro* is a coroutine object. The callable
must return a :class:`asyncio.Future`-compatible object.
.. method:: loop.get_task_factory()
......@@ -365,28 +370,23 @@ Opening network connections
The created transport is an implementation-dependent bidirectional
stream.
.. note::
*protocol_factory* can be any kind of callable, not necessarily
a class. For example, if you want to use a pre-created
protocol instance, you can pass ``lambda: my_protocol``.
Other arguments:
* *ssl*: if given and not false, an SSL/TLS transport is created
* *ssl*: if given and not false, a SSL/TLS transport is created
(by default a plain TCP transport is created). If *ssl* is
a :class:`ssl.SSLContext` object, this context is used to create
the transport; if *ssl* is :const:`True`, a context with some
unspecified default settings is used.
the transport; if *ssl* is :const:`True`, a default context returned
from :func:`ssl.create_default_context` is used.
.. seealso:: :ref:`SSL/TLS security considerations <ssl-security>`
* *server_hostname*, is only for use together with *ssl*,
and sets or overrides the hostname that the target server's certificate
will be matched against. By default the value of the *host* argument
* *server_hostname* sets or overrides the hostname that the target
server's certificate will be matched against. Should only be passed
if *ssl* is not ``None``. By default the value of the *host* argument
is used. If *host* is empty, there is no default and you must pass a
value for *server_hostname*. If *server_hostname* is an empty
string, hostname matching is disabled (which is a serious security
risk, allowing for man-in-the-middle-attacks).
risk, allowing for potential man-in-the-middle attacks).
* *family*, *proto*, *flags* are the optional address family, protocol
and flags to be passed through to getaddrinfo() for *host* resolution.
......@@ -402,8 +402,8 @@ Opening network connections
to bind the socket to locally. The *local_host* and *local_port*
are looked up using ``getaddrinfo()``, similarly to *host* and *port*.
* *ssl_handshake_timeout* is (for an SSL connection) the time in seconds
to wait for the SSL handshake to complete before aborting the connection.
* *ssl_handshake_timeout* is (for a TLS connection) the time in seconds
to wait for the TLS handshake to complete before aborting the connection.
``60.0`` seconds if ``None`` (default).
.. versionadded:: 3.7
......@@ -417,7 +417,7 @@ Opening network connections
.. versionchanged:: 3.5
Added support for SSL/TLS for :class:`ProactorEventLoop`.
Added support for SSL/TLS in :class:`ProactorEventLoop`.
.. seealso::
......@@ -462,12 +462,12 @@ Opening network connections
* *reuse_address* tells the kernel to reuse a local socket in
``TIME_WAIT`` state, without waiting for its natural timeout to
expire. If not specified will automatically be set to ``True`` on
UNIX.
Unix.
* *reuse_port* tells the kernel to allow this endpoint to be bound to the
same port as other existing endpoints are bound to, so long as they all
set this flag when being created. This option is not supported on Windows
and some UNIX's. If the :py:data:`~socket.SO_REUSEPORT` constant is not
and some Unixes. If the :py:data:`~socket.SO_REUSEPORT` constant is not
defined then this capability is unsupported.
* *allow_broadcast* tells the kernel to allow this endpoint to send
......@@ -478,7 +478,7 @@ Opening network connections
transport. If specified, *local_addr* and *remote_addr* should be omitted
(must be :const:`None`).
On Windows with :class:`ProactorEventLoop`, this method is not supported.
On Windows, with :class:`ProactorEventLoop`, this method is not supported.
See :ref:`UDP echo client protocol <asyncio-udp-echo-client-protocol>` and
:ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
......@@ -491,22 +491,22 @@ Opening network connections
path=None, \*, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Create UNIX connection.
Create a Unix connection.
The socket family will be :py:data:`~socket.AF_UNIX`; socket
type will be :py:data:`~socket.SOCK_STREAM`.
A tuple of ``(transport, protocol)`` is returned on success.
*path* is the name of a UNIX domain socket and is required,
unless a *sock* parameter is specified. Abstract UNIX sockets,
*path* is the name of a Unix domain socket and is required,
unless a *sock* parameter is specified. Abstract Unix sockets,
:class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths are
supported.
See the documentation of the :meth:`loop.create_connection` method
for information about arguments to this method.
Availability: UNIX.
Availability: Unix.
.. versionadded:: 3.7
......@@ -529,7 +529,7 @@ Creating network servers
ssl_handshake_timeout=None, start_serving=True)
Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) listening
on the *host* and *port* address.
on *port* of the *host* address.
Returns a :class:`Server` object.
......@@ -538,10 +538,15 @@ Creating network servers
* *protocol_factory* must be a callable returning a
:ref:`protocol <asyncio-protocol>` implementation.
* The *host* parameter can be set to several types which determine behavior:
- If *host* is a string, the TCP server is bound to *host* and *port*.
- if *host* is a sequence of strings, the TCP server is bound to all
hosts of the sequence.
* The *host* parameter can be set to several types which determine where
the server would be listening:
- If *host* is a string, the TCP server is bound to a single network
interface specified by *host*.
- If *host* is a sequence of strings, the TCP server is bound to all
network interfaces specified by the sequence.
- If *host* is an empty string or ``None``, all interfaces are
assumed and a list of multiple sockets will be returned (most likely
one for IPv4 and another one for IPv6).
......@@ -554,27 +559,26 @@ Creating network servers
* *flags* is a bitmask for :meth:`getaddrinfo`.
* *sock* can optionally be specified in order to use a preexisting
socket object. If specified, *host* and *port* should be omitted (must be
:const:`None`).
socket object. If specified, *host* and *port* must not be specified.
* *backlog* is the maximum number of queued connections passed to
:meth:`~socket.socket.listen` (defaults to 100).
* *ssl* can be set to an :class:`~ssl.SSLContext` to enable SSL over the
accepted connections.
* *ssl* can be set to an :class:`~ssl.SSLContext` instance to enable
TLS over the accepted connections.
* *reuse_address* tells the kernel to reuse a local socket in
``TIME_WAIT`` state, without waiting for its natural timeout to
expire. If not specified will automatically be set to ``True`` on
UNIX.
Unix.
* *reuse_port* tells the kernel to allow this endpoint to be bound to the
same port as other existing endpoints are bound to, so long as they all
set this flag when being created. This option is not supported on
Windows.
* *ssl_handshake_timeout* is (for an SSL server) the time in seconds to wait
for the SSL handshake to complete before aborting the connection.
* *ssl_handshake_timeout* is (for a TLS server) the time in seconds to wait
for the TLS handshake to complete before aborting the connection.
``60.0`` seconds if ``None`` (default).
* *start_serving* set to ``True`` (the default) causes the created server
......@@ -594,8 +598,7 @@ Creating network servers
.. versionchanged:: 3.5
Added support for SSL/TLS on Windows with
:class:`ProactorEventLoop`.
Added support for SSL/TLS in :class:`ProactorEventLoop`.
.. versionchanged:: 3.5.1
......@@ -615,15 +618,15 @@ Creating network servers
Similar to :meth:`loop.create_server` but works with the
:py:data:`~socket.AF_UNIX` socket family.
*path* is the name of a UNIX domain socket, and is required,
unless a *sock* argument is provided. Abstract UNIX sockets,
*path* is the name of a Unix domain socket, and is required,
unless a *sock* argument is provided. Abstract Unix sockets,
:class:`str`, :class:`bytes`, and :class:`~pathlib.Path` paths
are supported.
See the documentation of the :meth:`loop.create_server` method
for information about arguments to this method.
Availability: UNIX.
Availability: Unix.
.. versionadded:: 3.7
......@@ -680,17 +683,17 @@ Transferring files
*offset* tells from where to start reading the file. If specified,
*count* is the total number of bytes to transmit as opposed to
sending the file until EOF is reached. File position is updated on
return or also in case of error in which case :meth:`file.tell()
<io.IOBase.tell>` can be used to figure out the number of bytes
which were sent.
sending the file until EOF is reached. File position is always updated,
even when this method raises an error, and
:meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
number of bytes sent.
*fallback* set to ``True`` makes asyncio to manually read and send
the file when the platform does not support the sendfile system call
(e.g. Windows or SSL socket on Unix).
Raise :exc:`SendfileNotAvailableError` if the system does not support
*sendfile* syscall and *fallback* is ``False``.
the *sendfile* syscall and *fallback* is ``False``.
.. versionadded:: 3.7
......@@ -722,8 +725,8 @@ TLS Upgrade
* *server_hostname*: sets or overrides the host name that the target
server's certificate will be matched against.
* *ssl_handshake_timeout* is (for an SSL connection) the time in seconds to
wait for the SSL handshake to complete before aborting the connection.
* *ssl_handshake_timeout* is (for a TLS connection) the time in seconds to
wait for the TLS handshake to complete before aborting the connection.
``60.0`` seconds if ``None`` (default).
.. versionadded:: 3.7
......@@ -734,24 +737,26 @@ Watching file descriptors
.. method:: loop.add_reader(fd, callback, \*args)
Start watching the file descriptor *fd* for read availability and
call the *callback* with specified arguments.
Start monitoring the *fd* file descriptor for read availability and
invoke *callback* with the specified arguments once *fd* is available for
reading.
.. method:: loop.remove_reader(fd)
Stop watching the file descriptor *fd* for read availability.
Stop monitoring the *fd* file descriptor for read availability.
.. method:: loop.add_writer(fd, callback, \*args)
Start watching the file descriptor *fd* for write availability and then
call the *callback* with specified arguments.
Start monitoring the *fd* file descriptor for write availability and
invoke *callback* with the specified arguments once *fd* is available for
writing.
Use :func:`functools.partial` :ref:`to pass keywords
<asyncio-pass-keywords>` to *func*.
.. method:: loop.remove_writer(fd)
Stop watching the file descriptor *fd* for write availability.
Stop monitoring the *fd* file descriptor for write availability.
See also :ref:`Platform Support <asyncio-platform-support>` section
for some limitations of these methods.
......@@ -769,13 +774,12 @@ convenient.
.. coroutinemethod:: loop.sock_recv(sock, nbytes)
Receive data. Asynchronous version of
Receive up to *nbytes* from *sock*. Asynchronous version of
:meth:`socket.recv() <socket.socket.recv>`.
The received data is returned as a bytes object. The maximum amount
of data to be received is specified by the *nbytes* argument.
Return the received data as a bytes object.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionchanged:: 3.7
Even though this method was always documented as a coroutine
......@@ -784,27 +788,27 @@ convenient.
.. coroutinemethod:: loop.sock_recv_into(sock, buf)
Receive data into a buffer. Modeled after the blocking
Receive data from *sock* into the *buf* buffer. Modeled after the blocking
:meth:`socket.recv_into() <socket.socket.recv_into>` method.
Return the number of bytes written to the buffer.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionadded:: 3.7
.. coroutinemethod:: loop.sock_sendall(sock, data)
Send data to the socket. Asynchronous version of
Send *data* to the *sock* socket. Asynchronous version of
:meth:`socket.sendall() <socket.socket.sendall>`.
This method continues to send data from *data* to the socket until either
all data in *data* has been sent or an error occurs. ``None`` is returned
This method continues to send to the socket until either all data
in *data* has been sent or an error occurs. ``None`` is returned
on success. On error, an exception is raised. Additionally, there is no way
to determine how much data, if any, was successfully processed by the
receiving end of the connection.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionchanged:: 3.7
Even though the method was always documented as a coroutine
......@@ -813,11 +817,11 @@ convenient.
.. coroutinemethod:: loop.sock_connect(sock, address)
Connect to a remote socket at *address*.
Connect *sock* to a remote socket at *address*.
Asynchronous version of :meth:`socket.connect() <socket.socket.connect>`.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionchanged:: 3.5.2
``address`` no longer needs to be resolved. ``sock_connect``
......@@ -843,7 +847,7 @@ convenient.
and *address* is the address bound to the socket on the other end of the
connection.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionchanged:: 3.7
Even though the method was always documented as a coroutine
......@@ -858,21 +862,21 @@ convenient.
\*, fallback=True)
Send a file using high-performance :mod:`os.sendfile` if possible.
Return the total number of bytes which were sent.
Return the total number of bytes sent.
Asynchronous version of :meth:`socket.sendfile() <socket.socket.sendfile>`.
*sock* must be non-blocking :class:`~socket.socket` of
:const:`socket.SOCK_STREAM` type.
*sock* must be a non-blocking :const:`socket.SOCK_STREAM`
:class:`~socket.socket`.
*file* must be a regular file object opened in binary mode.
*file* must be a regular file object open in binary mode.
*offset* tells from where to start reading the file. If specified,
*count* is the total number of bytes to transmit as opposed to
sending the file until EOF is reached. File position is updated on
return or also in case of error in which case :meth:`file.tell()
<io.IOBase.tell>` can be used to figure out the number of bytes
which were sent.
sending the file until EOF is reached. File position is always updated,
even when this method raises an error, and
:meth:`file.tell() <io.IOBase.tell>` can be used to obtain the actual
number of bytes sent.
*fallback*, when set to ``True``, makes asyncio manually read and send
the file when the platform does not support the sendfile syscall
......@@ -881,7 +885,7 @@ convenient.
Raise :exc:`SendfileNotAvailableError` if the system does not support
*sendfile* syscall and *fallback* is ``False``.
The socket *sock* must be non-blocking.
*sock* must be a non-blocking socket.
.. versionadded:: 3.7
......@@ -910,7 +914,7 @@ Working with pipes
.. coroutinemethod:: loop.connect_read_pipe(protocol_factory, pipe)
Register a read-pipe in the event loop.
Register the read end of *pipe* in the event loop.
*protocol_factory* must be a callable returning an
:ref:`asyncio protocol <asyncio-protocol>` implementation.
......@@ -926,7 +930,7 @@ Working with pipes
.. coroutinemethod:: loop.connect_write_pipe(protocol_factory, pipe)
Register a write-pipe in the event loop.
Register the write end of *pipe* in the event loop.
*protocol_factory* must be a callable returning an
:ref:`asyncio protocol <asyncio-protocol>` implementation.
......@@ -951,12 +955,12 @@ Working with pipes
:meth:`loop.subprocess_shell` methods.
UNIX signals
Unix signals
^^^^^^^^^^^^
.. method:: loop.add_signal_handler(signum, callback, \*args)
Add a handler for a signal.
Set *callback* as the handler for the *signum* signal.
Raise :exc:`ValueError` if the signal number is invalid or uncatchable.
Raise :exc:`RuntimeError` if there is a problem setting up the handler.
......@@ -966,11 +970,12 @@ UNIX signals
.. method:: loop.remove_signal_handler(sig)
Remove a handler for a signal.
Remove the handler for the *sig* signal.
Return ``True`` if a signal handler was removed, ``False`` if not.
Return ``True`` if the signal handler was removed, or ``False`` if
no handler was set for the given signal.
Availability: UNIX.
Availability: Unix.
.. seealso::
......@@ -982,7 +987,7 @@ Executing code in thread or process pools
.. coroutinemethod:: loop.run_in_executor(executor, func, \*args)
Arrange for a *func* to be called in the specified executor.
Arrange for *func* to be called in the specified executor.
The *executor* argument should be an :class:`concurrent.futures.Executor`
instance. The default executor is used if *executor* is ``None``.
......@@ -1024,18 +1029,17 @@ Allows customizing how exceptions are handled in the event loop.
Set *handler* as the new event loop exception handler.
If *handler* is ``None``, the default exception handler will
be set.
If *handler* is a callable object, it should have a
matching signature to ``(loop, context)``, where ``loop``
will be a reference to the active event loop, ``context``
will be a ``dict`` object (see :meth:`call_exception_handler`
documentation for details about context).
be set. Otherwise, *handler* must be a callable with the signature
matching ``(loop, context)``, where ``loop``
is a reference to the active event loop, and ``context``
is a ``dict`` object containing the details of the exception
(see :meth:`call_exception_handler` documentation for details
about context).
.. method:: loop.get_exception_handler()
Return the exception handler, or ``None`` if the default one
is in use.
Return the current exception handler, or ``None`` if no custom
exception handler was set.
.. versionadded:: 3.5.2
......@@ -1055,7 +1059,7 @@ Allows customizing how exceptions are handled in the event loop.
Call the current event loop exception handler.
*context* is a ``dict`` object containing the following keys
(new keys may be introduced later):
(new keys may be introduced in future Python versions):
* 'message': Error message;
* 'exception' (optional): Exception object;
......@@ -1068,8 +1072,8 @@ Allows customizing how exceptions are handled in the event loop.
.. note::
This method should not be overloaded in subclassed
event loops. For any custom exception handling, use
:meth:`set_exception_handler()` method.
event loops. For custom exception handling, use
the :meth:`set_exception_handler()` method.
Enabling debug mode
^^^^^^^^^^^^^^^^^^^
......@@ -1099,17 +1103,16 @@ Enabling debug mode
Running Subprocesses
^^^^^^^^^^^^^^^^^^^^
Methods described in this subsections are low-level. In an
async/await code consider using high-level convenient
Methods described in this subsections are low-level. In regular
async/await code consider using the high-level
:func:`asyncio.create_subprocess_shell` and
:func:`asyncio.create_subprocess_exec` functions instead.
:func:`asyncio.create_subprocess_exec` convenience functions instead.
.. note::
The default event loop that asyncio is pre-configured
to use on **Windows** does not support subprocesses.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
The default asyncio event loop on **Windows** does not support
subprocesses. See :ref:`Subprocess Support on Windows
<asyncio-windows-subprocess>` for details.
.. coroutinemethod:: loop.subprocess_exec(protocol_factory, \*args, \
stdin=subprocess.PIPE, stdout=subprocess.PIPE, \
......@@ -1124,7 +1127,7 @@ async/await code consider using high-level convenient
* or :class:`bytes`, encoded to the
:ref:`filesystem encoding <filesystem-encoding>`.
The first string specifies the program to execute,
The first string specifies the program executable,
and the remaining strings specify the arguments. Together, string
arguments form the ``argv`` of the program.
......@@ -1134,7 +1137,7 @@ async/await code consider using high-level convenient
a single argument which is list of strings, *subprocess_exec*
takes multiple string arguments.
The *protocol_factory* must instantiate a subclass of the
The *protocol_factory* must be a callable returning a subclass of the
:class:`asyncio.SubprocessProtocol` class.
Other parameters:
......@@ -1185,7 +1188,7 @@ async/await code consider using high-level convenient
This is similar to the standard library :class:`subprocess.Popen`
class called with ``shell=True``.
The *protocol_factory* must instantiate a subclass of the
The *protocol_factory* must be a callable returning a subclass of the
:class:`SubprocessProtocol` class.
See :meth:`~loop.subprocess_exec` for more details about
......@@ -1197,10 +1200,10 @@ async/await code consider using high-level convenient
.. note::
It is the application's responsibility to ensure that all whitespace
and metacharacters are quoted appropriately to avoid `shell injection
and special characters are quoted appropriately to avoid `shell injection
<https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
vulnerabilities. The :func:`shlex.quote` function can be used to
properly escape whitespace and shell metacharacters in strings that
properly escape whitespace and special characters in strings that
are going to be used to construct shell commands.
......@@ -1214,12 +1217,12 @@ Callback Handles
.. method:: cancel()
Cancel the call. If the callback is already canceled or executed,
this method has no effect.
Cancel the callback. If the callback has already been canceled
or executed, this method has no effect.
.. method:: cancelled()
Return ``True`` if the call was cancelled.
Return ``True`` if the callback was cancelled.
.. versionadded:: 3.7
......@@ -1228,7 +1231,7 @@ Callback Handles
A callback wrapper object returned by :meth:`loop.call_later`,
and :meth:`loop.call_at`.
The class is inherited from :class:`Handle`.
This class is a subclass of :class:`Handle`.
.. method:: when()
......@@ -1280,7 +1283,7 @@ Do not instantiate the class directly.
.. method:: get_loop()
Gives the event loop associated with the server object.
Return the event loop associated with the server object.
.. versionadded:: 3.7
......@@ -1291,12 +1294,12 @@ Do not instantiate the class directly.
This method is idempotent, so it can be called when
the server is already being serving.
The new *start_serving* keyword-only parameter to
The *start_serving* keyword-only parameter to
:meth:`loop.create_server` and
:meth:`asyncio.start_server` allows to create a Server object
that is not accepting connections right away. In which case
this method, or :meth:`Server.serve_forever` can be used
to make the Server object to start accepting connections.
:meth:`asyncio.start_server` allows creating a Server object
that is not accepting connections initially. In this case
``Server.start_serving()``, or :meth:`Server.serve_forever` can be used
to make the Server start accepting connections.
.. versionadded:: 3.7
......@@ -1338,19 +1341,19 @@ Do not instantiate the class directly.
.. attribute:: sockets
List of :class:`socket.socket` objects the server is listening to,
List of :class:`socket.socket` objects the server is listening on,
or ``None`` if the server is closed.
.. versionchanged:: 3.7
Prior to Python 3.7 ``Server.sockets`` used to return the
internal list of server's sockets directly. In 3.7 a copy
Prior to Python 3.7 ``Server.sockets`` used to return an
internal list of server sockets directly. In 3.7 a copy
of that list is returned.
.. _asyncio-event-loops:
Event Loops Implementations
===========================
Event Loop Implementations
==========================
asyncio ships with two different event loop implementations:
:class:`SelectorEventLoop` and :class:`ProactorEventLoop`.
......@@ -1364,8 +1367,8 @@ on all platforms.
An event loop based on the :mod:`selectors` module.
Uses the most efficient *selector* available for the given
platform. It is also possible to manually configure what
exact selector implementation should be used::
platform. It is also possible to manually configure the
exact selector implementation to be used::
import asyncio
import selectors
......@@ -1375,7 +1378,7 @@ on all platforms.
asyncio.set_event_loop(loop)
Availability: UNIX, Windows.
Availability: Unix, Windows.
.. class:: ProactorEventLoop
......@@ -1412,9 +1415,9 @@ Examples
========
Note that all examples in this section **purposefully** show how
to use low-level event loop APIs such as :meth:`loop.run_forever`
to use the low-level event loop APIs, such as :meth:`loop.run_forever`
and :meth:`loop.call_soon`. Modern asyncio applications rarely
need to be written this way; consider using high-level functions
need to be written this way; consider using the high-level functions
like :func:`asyncio.run`.
......@@ -1456,9 +1459,9 @@ event loop::
Display the current date with call_later()
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
An example of callback displaying the current date every second. The
An example of a callback displaying the current date every second. The
callback uses the :meth:`loop.call_later` method to reschedule itself
during 5 seconds, and then stops the event loop::
after 5 seconds, and then stops the event loop::
import asyncio
import datetime
......@@ -1545,7 +1548,7 @@ Wait until a file descriptor received some data using the
Set signal handlers for SIGINT and SIGTERM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(This ``signals`` example only works on UNIX.)
(This ``signals`` example only works on Unix.)
Register handlers for signals :py:data:`SIGINT` and :py:data:`SIGTERM`
using the :meth:`loop.add_signal_handler` method::
......
Doc/library/asyncio-exceptions.rst
View file @ 1fa2ec49
......@@ -23,12 +23,12 @@ Exceptions
This exception can be caught to perform custom operations
when asyncio Tasks are cancelled. In almost all situations the
exception must always be re-raised.
exception must be re-raised.
.. important::
This exception is a subclass of :exc:`Exception`, so it can be
accidentally suppressed by ``try..except`` block::
accidentally suppressed by an overly broad ``try..except`` block::
try:
await operation
......@@ -65,27 +65,27 @@ Exceptions
.. exception:: IncompleteReadError
Incomplete read error.
The requested read operation did not complete fully.
Raised by :ref:`asyncio streams <asyncio-streams>` APIs.
Raised by the :ref:`asyncio stream APIs<asyncio-streams>`.
This exception is a subclass of :exc:`EOFError`.
.. attribute:: expected
Total number (:class:`int`) of expected bytes.
The total number (:class:`int`) of expected bytes.
.. attribute:: partial
Read :class:`bytes` string before the end of stream was reached.
A string of :class:`bytes` read before the end of stream was reached.
.. exception:: LimitOverrunError
Reached the buffer limit while looking for a separator.
Reached the buffer size limit while looking for a separator.
Raised by :ref:`asyncio streams <asyncio-streams>` APIs.
Raised by the :ref:`asyncio stream APIs <asyncio-streams>`.
.. attribute:: consumed
Total number of to be consumed bytes.
The total number of to be consumed bytes.
Doc/library/asyncio-platforms.rst
View file @ 1fa2ec49
......@@ -4,11 +4,11 @@
.. _asyncio-platform-support:
=================
Platforms Support
=================
================
Platform Support
================
The :mod:`asyncio` module has been designed to be portable,
The :mod:`asyncio` module is designed to be portable,
but some platforms have subtle differences and limitations
due to the platforms' underlying architecture and capabilities.
......@@ -17,7 +17,7 @@ All Platforms
=============
* :meth:`loop.add_reader` and :meth:`loop.add_writer`
cannot be used to monitor file IO.
cannot be used to monitor file I/O.
Windows
......@@ -27,7 +27,7 @@ All event loops on Windows do not support the following methods:
* :meth:`loop.create_unix_connection` and
:meth:`loop.create_unix_server` are not supported.
The :data:`socket.AF_UNIX` socket family is specific to UNIX.
The :data:`socket.AF_UNIX` socket family is specific to Unix.
* :meth:`loop.add_signal_handler` and
:meth:`loop.remove_signal_handler` are not supported.
......
Doc/library/asyncio-policy.rst
View file @ 1fa2ec49
......@@ -7,9 +7,9 @@
Policies
========
An event loop policy, a global per-process object, controls
management of the event loop. Each event loop has a default
policy, which can be changed and customized using the API.
An event loop policy is a global per-process object that controls
the management of the event loop. Each event loop has a default
policy, which can be changed and customized using the policy API.
A policy defines the notion of *context* and manages a
separate event loop per context. The default policy
......@@ -20,11 +20,11 @@ By using a custom event loop policy, the behavior of
:func:`new_event_loop` functions can be customized.
Policy objects should implement the APIs defined
in the abstract base class :class:`AbstractEventLoopPolicy`.
in the :class:`AbstractEventLoopPolicy` abstract base class.
Access the Policy
=================
Getting and Setting the Policy
==============================
The following functions can be used to get and set the policy
for the current process:
......@@ -111,14 +111,14 @@ Process Watchers
A process watcher allows customization of how an event loop monitors
child processes on Unix. Specifically, the event loop needs to know
when a child process has finished its execution.
when a child process has exited.
In asyncio, child processes are created with
:func:`create_subprocess_exec` and :meth:`loop.subprocess_exec`
functions.
asyncio defines an abstract base class :class:`AbstractChildWatcher`
that child watchers should implement, and has two different
asyncio defines the :class:`AbstractChildWatcher` abstract base class,
which child watchers should implement, and has two different
implementations: :class:`SafeChildWatcher` (configured to be used
by default) and :class:`FastChildWatcher`.
......@@ -141,8 +141,7 @@ implementation used by the asyncio event loop:
.. note::
Third-party event loops implementations might not support
custom child watchers. For such event loops, using
:func:`set_child_watcher` might have no effect or even can
be prohibited.
:func:`set_child_watcher` might be prohibited or have no effect.
.. class:: AbstractChildWatcher
......@@ -155,7 +154,7 @@ implementation used by the asyncio event loop:
another callback for the same process replaces the previous
handler.
*callback* callable must be thread-safe.
The *callback* callable must be thread-safe.
.. method:: remove_child_handler(pid)
......
Doc/library/asyncio-protocol.rst
View file @ 1fa2ec49
......@@ -10,8 +10,8 @@ Transports and Protocols
.. rubric:: Preface
Transports and Protocols are used by **low-level** event loop
APIs such as :meth:`loop.create_connection`. They require using
Transports and Protocols are used by the **low-level** event loop
APIs such as :meth:`loop.create_connection`. They use
callback-based programming style and enable high-performance
implementations of network or IPC protocols (e.g. HTTP).
......@@ -282,7 +282,7 @@ Write-only Transports
.. method:: WriteTransport.get_write_buffer_limits()
Get the *high*- and *low*-water limits for write flow control. Return a
Get the *high* and *low* watermarks for write flow control. Return a
tuple ``(low, high)`` where *low* and *high* are positive number of
bytes.
......@@ -292,14 +292,14 @@ Write-only Transports
.. method:: WriteTransport.set_write_buffer_limits(high=None, low=None)
Set the *high*- and *low*-water limits for write flow control.
Set the *high* and *low* watermarks for write flow control.
These two values (measured in number of
bytes) control when the protocol's
:meth:`protocol.pause_writing() <BaseProtocol.pause_writing>`
and :meth:`protocol.resume_writing() <BaseProtocol.resume_writing>`
methods are called. If specified, the low-water limit must be less
than or equal to the high-water limit. Neither *high* nor *low*
methods are called. If specified, the low watermark must be less
than or equal to the high watermark. Neither *high* nor *low*
can be negative.
:meth:`~BaseProtocol.pause_writing` is called when the buffer size
......@@ -308,9 +308,9 @@ Write-only Transports
the buffer size becomes less than or equal to the *low* value.
The defaults are implementation-specific. If only the
high-water limit is given, the low-water limit defaults to an
high watermark is given, the low watermark defaults to an
implementation-specific value less than or equal to the
high-water limit. Setting *high* to zero forces *low* to zero as
high watermark. Setting *high* to zero forces *low* to zero as
well, and causes :meth:`~BaseProtocol.pause_writing` to be called
whenever the buffer becomes non-empty. Setting *low* to zero causes
:meth:`~BaseProtocol.resume_writing` to be called only once the
......@@ -337,11 +337,11 @@ Write-only Transports
.. method:: WriteTransport.write_eof()
Close the write end of the transport after flushing buffered data.
Close the write end of the transport after flushing all buffered data.
Data may still be received.
This method can raise :exc:`NotImplementedError` if the transport
(e.g. SSL) doesn't support half-closes.
(e.g. SSL) doesn't support half-closed connections.
Datagram Transports
......@@ -506,18 +506,18 @@ method for more details.
.. method:: BaseProtocol.pause_writing()
Called when the transport's buffer goes over the high-water mark.
Called when the transport's buffer goes over the high watermark.
.. method:: BaseProtocol.resume_writing()
Called when the transport's buffer drains below the low-water mark.
Called when the transport's buffer drains below the low watermark.
If the buffer size equals the high-water mark,
If the buffer size equals the high watermark,
:meth:`~BaseProtocol.pause_writing` is not called: the buffer size must
go strictly over.
Conversely, :meth:`~BaseProtocol.resume_writing` is called when the
buffer size is equal or lower than the low-water mark. These end
buffer size is equal or lower than the low watermark. These end
conditions are important to ensure that things go as expected when
either mark is zero.
......@@ -541,13 +541,12 @@ accept factories that return streaming protocols.
and instead make your parsing generic and flexible. However,
data is always received in the correct order.
The method can be called an arbitrary number of times during
a connection.
The method can be called an arbitrary number of times while
a connection is open.
However, :meth:`protocol.eof_received() <Protocol.eof_received>`
is called at most once and, if called,
:meth:`protocol.data_received() <Protocol.data_received>`
won't be called after it.
is called at most once. Once `eof_received()` is called,
``data_received()`` is not called anymore.
.. method:: Protocol.eof_received()
......@@ -562,9 +561,9 @@ accept factories that return streaming protocols.
Since the default implementation returns ``None``, it implicitly closes the
connection.
Some transports such as SSL don't support half-closed connections,
in which case returning true from this method will result in closing
the connection.
Some transports, including SSL, don't support half-closed connections,
in which case returning true from this method will result in the connection
being closed.
State machine:
......@@ -588,12 +587,12 @@ Buffered Streaming Protocols
Buffered Protocols can be used with any event loop method
that supports `Streaming Protocols`_.
The idea of ``BufferedProtocol`` is that it allows manual allocation
``BufferedProtocol`` implementations allow explicit manual allocation
and control of the receive buffer. Event loops can then use the buffer
provided by the protocol to avoid unnecessary data copies. This
can result in noticeable performance improvement for protocols that
receive big amounts of data. Sophisticated protocols implementations
can allocate the buffer only once at creation time.
receive big amounts of data. Sophisticated protocol implementations
can significantly reduce the number of buffer allocations.
The following callbacks are called on :class:`BufferedProtocol`
instances:
......@@ -602,12 +601,12 @@ instances:
Called to allocate a new receive buffer.
*sizehint* is a recommended minimal size for the returned
buffer. It is acceptable to return smaller or bigger buffers
*sizehint* is the recommended minimum size for the returned
buffer. It is acceptable to return smaller or larger buffers
than what *sizehint* suggests. When set to -1, the buffer size
can be arbitrary. It is an error to return a zero-sized buffer.
can be arbitrary. It is an error to return a buffer with a zero size.
Must return an object that implements the
``get_buffer()`` must return an object implementing the
:ref:`buffer protocol <bufferobjects>`.
.. method:: BufferedProtocol.buffer_updated(nbytes)
......@@ -658,14 +657,14 @@ factories passed to the :meth:`loop.create_datagram_endpoint` method.
:class:`OSError`. *exc* is the :class:`OSError` instance.
This method is called in rare conditions, when the transport (e.g. UDP)
detects that a datagram couldn't be delivered to its recipient.
detects that a datagram could not be delivered to its recipient.
In many conditions though, undeliverable datagrams will be silently
dropped.
.. note::
On BSD systems (macOS, FreeBSD, etc.) flow control is not supported
for datagram protocols, because it is difficult to detect easily send
for datagram protocols, because there is no reliable way to detect send
failures caused by writing too many packets.
The socket always appears 'ready' and excess packets are dropped. An
......
Doc/library/asyncio-queue.rst
View file @ 1fa2ec49
......@@ -10,7 +10,7 @@ asyncio queues are designed to be similar to classes of the
:mod:`queue` module. Although asyncio queues are not thread-safe,
they are designed to be used specifically in async/await code.
Note that methods on asyncio queues don't have a *timeout* parameter;
Note that methods of asyncio queues don't have a *timeout* parameter;
use :func:`asyncio.wait_for` function to do queue operations with a
timeout.
......@@ -72,7 +72,7 @@ Queue
.. coroutinemethod:: put(item)
Put an item into the queue. If the queue is full, wait until a
free slot is available before adding item.
free slot is available before adding the item.
.. method:: put_nowait(item)
......@@ -82,7 +82,7 @@ Queue
.. method:: qsize()
Number of items in the queue.
Return the number of items in the queue.
.. method:: task_done()
......
Doc/library/asyncio-stream.rst
View file @ 1fa2ec49
......@@ -54,7 +54,7 @@ and work with streams:
:class:`StreamReader` and :class:`StreamWriter` classes.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
automatically when this function is awaited from a coroutine.
*limit* determines the buffer size limit used by the
returned :class:`StreamReader` instance. By default the *limit*
......@@ -84,7 +84,7 @@ and work with streams:
*client_connected_cb* can be a plain callable or a
:ref:`coroutine function <coroutine>`; if it is a coroutine function,
it will be automatically wrapped into a :class:`Task`.
it will be automatically scheduled as a :class:`Task`.
The *loop* argument is optional and can always be determined
automatically when this method is awaited from a coroutine.
......@@ -107,14 +107,14 @@ and work with streams:
limit=None, ssl=None, sock=None, \
server_hostname=None, ssl_handshake_timeout=None)
Establish a UNIX socket connection and return a pair of
Establish a Unix socket connection and return a pair of
``(reader, writer)``.
Similar to :func:`open_connection` but operates on UNIX sockets.
Similar to :func:`open_connection` but operates on Unix sockets.
See also the documentation of :meth:`loop.create_unix_connection`.
Availability: UNIX.
Availability: Unix.
.. versionadded:: 3.7
......@@ -130,13 +130,13 @@ and work with streams:
backlog=100, ssl=None, ssl_handshake_timeout=None, \
start_serving=True)
Start a UNIX socket server.
Start a Unix socket server.
Similar to :func:`start_server` but works with UNIX sockets.
Similar to :func:`start_server` but works with Unix sockets.
See also the documentation of :meth:`loop.create_unix_server`.
Availability: UNIX.
Availability: Unix.
.. versionadded:: 3.7
......@@ -167,7 +167,7 @@ StreamReader
Read up to *n* bytes. If *n* is not provided, or set to ``-1``,
read until EOF and return all read bytes.
If an EOF was received and the internal buffer is empty,
If EOF was received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readline()
......@@ -175,41 +175,36 @@ StreamReader
Read one line, where "line" is a sequence of bytes
ending with ``\n``.
If an EOF is received and ``\n`` was not found, the method
If EOF is received and ``\n`` was not found, the method
returns partially read data.
If an EOF is received and the internal buffer is empty,
If EOF is received and the internal buffer is empty,
return an empty ``bytes`` object.
.. coroutinemethod:: readexactly(n)
Read exactly *n* bytes.
Raise an :exc:`IncompleteReadError` if an EOF reached before *n*
Raise an :exc:`IncompleteReadError` if EOF is reached before *n*
can be read. Use the :attr:`IncompleteReadError.partial`
attribute to get the partially read data.
.. coroutinemethod:: readuntil(separator=b'\\n')
Read data from the stream until ``separator`` is found.
Read data from the stream until *separator* is found.
On success, the data and separator will be removed from the
internal buffer (consumed). Returned data will include the
separator at the end.
Configured stream limit is used to check result. Limit sets the
maximal length of data that can be returned, not counting the
separator.
If an EOF occurs and the complete separator is still not found,
an :exc:`IncompleteReadError` exception will be
raised, and the internal buffer will be reset. The
:attr:`IncompleteReadError.partial` attribute may contain the
separator partially.
If the amount of data read exceeds the configured stream limit, a
:exc:`LimitOverrunError` exception is raised, and the data
is left in the internal buffer and can be read again.
If the data cannot be read because of over limit, a
:exc:`LimitOverrunError` exception will be raised, and the data
will be left in the internal buffer, so it can be read again.
If EOF is reached before the complete separator is found,
an :exc:`IncompleteReadError` exception is raised, and the internal
buffer is reset. The :attr:`IncompleteReadError.partial` attribute
may contain a portion of the separator.
.. versionadded:: 3.5.2
......@@ -235,8 +230,8 @@ StreamWriter
Write *data* to the stream.
The method respects control-flow, execution is paused if write
buffer reaches high-water limit.
The method respects flow control, execution is paused if the write
buffer reaches the high watermark.
.. versionadded:: 3.8
......@@ -244,7 +239,7 @@ StreamWriter
Close the stream.
Wait for finishing all closing actions, e.g. SSL shutdown for
Wait until all closing actions are complete, e.g. SSL shutdown for
secure sockets.
.. versionadded:: 3.8
......@@ -272,28 +267,29 @@ StreamWriter
Write *data* to the stream.
This method doesn't apply control-flow. The call should be
followed by :meth:`drain`.
This method is not subject to flow control. Calls to ``write()`` should
be followed by :meth:`drain`. The :meth:`awrite` method is a
recommended alternative the applies flow control automatically.
.. method:: writelines(data)
Write a list (or any iterable) of bytes to the stream.
This method doesn't apply control-flow. The call should be
followed by :meth:`drain`.
This method is not subject to flow control. Calls to ``writelines()``
should be followed by :meth:`drain`.
.. coroutinemethod:: drain()
Wait until it is appropriate to resume writing to the stream.
E.g.::
Example::
writer.write(data)
await writer.drain()
This is a flow-control method that interacts with the underlying
This is a flow control method that interacts with the underlying
IO write buffer. When the size of the buffer reaches
the high-water limit, *drain()* blocks until the size of the
buffer is drained down to the low-water limit and writing can
the high watermark, *drain()* blocks until the size of the
buffer is drained down to the low watermark and writing can
be resumed. When there is nothing to wait for, the :meth:`drain`
returns immediately.
......
Doc/library/asyncio-subprocess.rst
View file @ 1fa2ec49
......@@ -12,7 +12,7 @@ create and manage subprocesses.
.. _asyncio_example_subprocess_shell:
Here's an example of how asyncio can run a shell command and
communicate its result back::
obtain its result::
import asyncio
......@@ -41,7 +41,7 @@ will print::
Because all asyncio subprocess functions are asynchronous and asyncio
provides many tools to work with such functions, it is easy to execute
and monitor multiple subprocesses in parallel. It is indeed trivial
to modify the above example to run a few commands at once::
to modify the above example to run several commands simultaneously::
async def main():
await asyncio.gather(
......@@ -75,7 +75,7 @@ Creating Subprocesses
stdout=None, stderr=None, loop=None, \
limit=None, \*\*kwds)
Run the shell command *cmd*.
Run the *cmd* shell command.
The *limit* argument sets the buffer limit for :class:`StreamReader`
wrappers for :attr:`Process.stdout` and :attr:`Process.stderr`
......@@ -89,23 +89,23 @@ Creating Subprocesses
.. important::
It is the application's responsibility to ensure that all whitespace and
metacharacters are quoted appropriately to avoid `shell injection
special characters are quoted appropriately to avoid `shell injection
<https://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
vulnerabilities. The :func:`shlex.quote` function can be used to properly
escape whitespace and shell metacharacters in strings that are going to be
used to construct shell commands.
escape whitespace and special shell characters in strings that are going
to be used to construct shell commands.
.. note::
The default event loop that asyncio is pre-configured
to use on **Windows** does not support subprocesses. Subprocesses are
available for Windows if the :class:`ProactorEventLoop` is used.
The default asyncio event loop implementation on **Windows** does not
support subprocesses. Subprocesses are available for Windows if a
:class:`ProactorEventLoop` is used.
See :ref:`Subprocess Support on Windows <asyncio-windows-subprocess>`
for details.
.. seealso::
asyncio has also *low-level* APIs to work with subprocesses:
asyncio also has the following *low-level* APIs to work with subprocesses:
:meth:`loop.subprocess_exec`, :meth:`loop.subprocess_shell`,
:meth:`loop.connect_read_pipe`, :meth:`loop.connect_write_pipe`,
as well as the :ref:`Subprocess Transports <asyncio-subprocess-transports>`
......@@ -130,22 +130,23 @@ Constants
.. data:: asyncio.subprocess.STDOUT
Can be passed to the *stderr* parameter to redirect process'
*stderr* to *stdout*.
Special value that can be used as the *stderr* argument and indicates
that standard error should be redirected into standard output.
.. data:: asyncio.subprocess.DEVNULL
Can be passed as the *stdin*, *stdout* or *stderr* parameters
to redirect the corresponding subprocess' IO to :data:`os.devnull`.
Special value that can be used as the *stdin*, *stdout* or *stderr* argument
to process creation functions. It indicates that the special file
:data:`os.devnull` will be used for the corresponding subprocess stream.
Interacting with Subprocesses
=============================
Both :func:`create_subprocess_exec` and :func:`create_subprocess_shell`
functions return instances of the *Process* class. It is a high-level
wrapper that allows to watch for subprocesses completion and
communicate with them.
functions return instances of the *Process* class. *Process* is a high-level
wrapper that allows communicating with subprocesses and watching for
their completion.
.. class:: asyncio.subprocess.Process
......@@ -161,7 +162,7 @@ communicate with them.
the :meth:`~subprocess.Popen.poll` method;
* the :meth:`~asyncio.subprocess.Process.communicate` and
:meth:`~asyncio.subprocess.Process.wait` methods don't take a
:meth:`~asyncio.subprocess.Process.wait` methods don't have a
*timeout* parameter: use the :func:`wait_for` function;
* the :meth:`Process.wait() <asyncio.subprocess.Process.wait>` method
......@@ -177,7 +178,7 @@ communicate with them.
.. coroutinemethod:: wait()
Wait for child process to terminate.
Wait for the child process to terminate.
Set and return the :attr:`returncode` attribute.
......@@ -229,9 +230,9 @@ communicate with them.
.. method:: terminate()
Stop the child.
Stop the child process.
On Posix OSs the method sends :py:data:`signal.SIGTERM` to the
On POSIX systems this method sends :py:data:`signal.SIGTERM` to the
child process.
On Windows the Win32 API function :c:func:`TerminateProcess` is
......@@ -241,7 +242,7 @@ communicate with them.
Kill the child.
On Posix OSs the function sends :py:data:`SIGKILL` to the child
On POSIX systems this method sends :py:data:`SIGKILL` to the child
process.
On Windows this method is an alias for :meth:`terminate`.
......@@ -284,7 +285,7 @@ communicate with them.
A ``None`` value indicates that the process has not terminated yet.
A negative value ``-N`` indicates that the child was terminated
by signal ``N`` (Unix only).
by signal ``N`` (POSIX only).
.. _asyncio-subprocess-threads:
......@@ -292,17 +293,17 @@ communicate with them.
Subprocess and Threads
----------------------
asyncio built-in event loops support running subprocesses from
different threads, but there are the following limitations:
Standard asyncio event loop supports running subprocesses from
different threads, but there are limitations:
* An event loop must run in the main thread.
* The child watcher must be instantiated in the main thread,
* The child watcher must be instantiated in the main thread
before executing subprocesses from other threads. Call the
:func:`get_child_watcher` function in the main thread to instantiate
the child watcher.
Note, that alternative event loop implementations might not share
Note that alternative event loop implementations might not share
the above limitations; please refer to their documentation.
.. seealso::
......@@ -316,7 +317,7 @@ Examples
An example using the :class:`~asyncio.subprocess.Process` class to
control a subprocess and the :class:`StreamReader` class to read from
the *stdout*.
its standard output.
.. _asyncio_example_create_subprocess_exec:
......
Doc/library/asyncio-sync.rst
View file @ 1fa2ec49
......@@ -10,10 +10,10 @@ asyncio synchronization primitives are designed to be similar to
those of the :mod:`threading` module with two important caveats:
* asyncio primitives are not thread-safe, therefore they should not
be used for OS threads synchronization (use :mod:`threading` for
be used for OS thread synchronization (use :mod:`threading` for
that);
* methods of synchronization primitives do not accept the *timeout*
* methods of these synchronization primitives do not accept the *timeout*
argument; use the :func:`asyncio.wait_for` function to perform
operations with timeouts.
......@@ -153,12 +153,12 @@ Condition
A Condition object. Not thread-safe.
An asyncio condition primitive can be used by a task to wait for
some event to happen and then get an exclusive access to a shared
some event to happen and then get exclusive access to a shared
resource.
In essence, a Condition object combines the functionality
of :class:`Event` and :class:`Lock`. It is possible to have many
Condition objects sharing one Lock, which allows to coordinate
of an :class:`Event` and a :class:`Lock`. It is possible to have
multiple Condition objects share one Lock, which allows coordinating
exclusive access to a shared resource between different tasks
interested in particular states of that shared resource.
......@@ -287,7 +287,7 @@ Semaphore
Acquire a semaphore.
If the internal counter is greater than zero, decrement
it by one and return ``True`` immediately. If it is zero wait
it by one and return ``True`` immediately. If it is zero, wait
until a :meth:`release` is called and return ``True``.
.. method:: locked()
......@@ -300,7 +300,7 @@ Semaphore
Can wake up a task waiting to acquire the semaphore.
Unlike :class:`BoundedSemaphore`, :class:`Semaphore` allows
to make more ``release()`` calls than ``acquire()`` calls.
making more ``release()`` calls than ``acquire()`` calls.
BoundedSemaphore
......
Doc/library/asyncio-task.rst
View file @ 1fa2ec49
......@@ -20,7 +20,7 @@ Coroutines
Coroutines declared with async/await syntax is the preferred way of
writing asyncio applications. For example, the following snippet
of code prints "hello", waits 1 second, and prints "world"::
of code prints "hello", waits 1 second, and then prints "world"::
>>> import asyncio
......@@ -41,10 +41,10 @@ be executed::
To actually run a coroutine asyncio provides three main mechanisms:
* By using the :func:`asyncio.run` function to run the top-level
* The :func:`asyncio.run` function to run the top-level
entry point "main()" function (see the above example.)
* By awaiting on a coroutine. The following snippet of code will
* Awaiting on a coroutine. The following snippet of code will
print "hello" after waiting for 1 second, and then print "world"
after waiting for *another* 2 seconds::
......@@ -72,7 +72,7 @@ To actually run a coroutine asyncio provides three main mechanisms:
world
finished at 17:13:55
* By using the :func:`asyncio.create_task` function to run coroutines
* The :func:`asyncio.create_task` function to run coroutines
concurrently as asyncio :class:`Tasks <Task>`.
Let's modify the above example and run two "set_after" coroutines
......@@ -130,8 +130,8 @@ Running an asyncio Program
programs, and should ideally only be called once.
.. versionadded:: 3.7
**Important:** this has been added to asyncio in Python 3.7
on a :term:`provisional basis <provisional api>`.
**Important:** this function has been added to asyncio in
Python 3.7 on a :term:`provisional basis <provisional api>`.
Creating Tasks
......@@ -139,13 +139,13 @@ Creating Tasks
.. function:: create_task(coro, \*, name=None)
Wrap a :ref:`coroutine <coroutine>` *coro* into a task and schedule
Wrap the *coro* :ref:`coroutine <coroutine>` into a task and schedule
its execution. Return the task object.
If *name* is not ``None``, it is set as the name of the task using
:meth:`Task.set_name`.
The task is executed in :func:`get_running_loop` context,
The task is executed in the loop returned by :func:`get_running_loop`,
:exc:`RuntimeError` is raised if there is no running loop in
current thread.
......@@ -168,7 +168,7 @@ Sleeping
.. _asyncio_example_sleep:
Example of coroutine displaying the current date every second
during 5 seconds::
for 5 seconds::
import asyncio
import datetime
......@@ -198,7 +198,7 @@ Running Tasks Concurrently
order of the original *fs* sequence.
All coroutines in the *fs* list are automatically
wrapped in :class:`Tasks <Task>`.
scheduled as :class:`Tasks <Task>`.
If *return_exceptions* is ``True``, exceptions in the Tasks/Futures
are treated the same as successful results, and gathered in the
......@@ -263,14 +263,14 @@ Shielding Tasks From Cancellation
Wait for a Future/Task while protecting it from being cancelled.
*fut* can be a coroutine, a Task, or a Future-like object. If
*fut* is a coroutine it is automatically wrapped in a
*fut* is a coroutine it is automatically scheduled as a
:class:`Task`.
The statement::
res = await shield(something())
is equivalent to the statement::
is equivalent to::
res = await something()
......@@ -278,7 +278,7 @@ Shielding Tasks From Cancellation
Task running in ``something()`` is not cancelled. From the point
of view of ``something()``, the cancellation did not happen.
Although its caller is still cancelled, so the "await" expression
still raises :exc:`CancelledError`.
still raises a :exc:`CancelledError`.
If ``something()`` is cancelled by other means (i.e. from within
itself) that would also cancel ``shield()``.
......@@ -298,10 +298,10 @@ Timeouts
.. coroutinefunction:: wait_for(fut, timeout, \*, loop=None)
Wait for the coroutine, Task, or Future to complete with timeout.
Wait for a coroutine, Task, or Future to complete with timeout.
*fut* can be a coroutine, a Task, or a Future-like object. If
*fut* is a coroutine it is automatically wrapped in a
*fut* is a coroutine it is automatically scheduled as a
:class:`Task`.
*timeout* can either be ``None`` or a float or int number of seconds
......@@ -352,10 +352,10 @@ Waiting Primitives
.. coroutinefunction:: wait(fs, \*, loop=None, timeout=None,\
return_when=ALL_COMPLETED)
Wait for a set of Futures to complete.
Wait for a set of coroutines, Tasks, or Futures to complete.
*fs* is a list of coroutines, Futures, and/or Tasks. Coroutines
are automatically wrapped in :class:`Tasks <Task>`.
are automatically scheduled as :class:`Tasks <Task>`.
Returns two sets of Tasks/Futures: ``(done, pending)``.
......@@ -363,7 +363,7 @@ Waiting Primitives
the maximum number of seconds to wait before returning.
Note that this function does not raise :exc:`asyncio.TimeoutError`.
Futures or Tasks that aren't done when the timeout occurs are just
Futures or Tasks that aren't done when the timeout occurs are simply
returned in the second set.
*return_when* indicates when this function should return. It must
......@@ -397,7 +397,7 @@ Waiting Primitives
.. function:: as_completed(fs, \*, loop=None, timeout=None)
Return an iterator which values, when waited for, are
Return an iterator of awaitables which return
:class:`Future` instances.
Raises :exc:`asyncio.TimeoutError` if the timeout occurs before
......@@ -500,9 +500,9 @@ Task Object
IO operations.
Use the high-level :func:`asyncio.create_task` function to create
Tasks, or low-level :meth:`loop.create_task` or
:func:`ensure_future` functions. Manually instantiating Task
objects is discouraged.
Tasks, or the low-level :meth:`loop.create_task` or
:func:`ensure_future` functions. Manual instantiation of Tasks
is discouraged.
To cancel a running Task use the :meth:`cancel` method. Calling it
will cause the Task to throw a :exc:`CancelledError` exception into
......@@ -660,7 +660,7 @@ Task Object
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
This function is **deprecated** and scheduled for removal in
This method is **deprecated** and will be removed in
Python 3.9. Use the :func:`all_tasks` function instead.
.. classmethod:: current_task(loop=None)
......@@ -670,7 +670,7 @@ Task Object
If *loop* is ``None``, the :func:`get_event_loop` function
is used to get the current loop.
This function is **deprecated** and scheduled for removal in
This method is **deprecated** and will be removed in
Python 3.9. Use the :func:`current_task` function instead.
......@@ -682,10 +682,10 @@ Generator-based Coroutines
.. note::
Support for generator-based coroutines is **deprecated** and
scheduled for removal in Python 4.0.
is scheduled for removal in Python 4.0.
Generator-based coroutines predate async/await syntax. They are
Python generators that use ``yield from`` expression is to await
Python generators that use ``yield from`` expressions to await
on Futures and other coroutines.
Generator-based coroutines should be decorated with
......
Doc/library/asyncio.rst
View file @ 1fa2ec49
......@@ -20,7 +20,7 @@
asyncio.run(main())
asyncio is a library to write **concurrent** code using
**async/await** syntax.
the **async/await** syntax.
asyncio is used as a foundation for multiple Python asynchronous
frameworks that provide high-performance network and web-servers,
......@@ -42,7 +42,8 @@ asyncio provides a set of **high-level** APIs to:
* :ref:`synchronize <asyncio-sync>` concurrent code;
as well as **low-level** APIs for *library and framework developers* to:
Additionally, there are **low-level** APIs for
*library and framework developers* to:
* create and manage :ref:`event loops <asyncio-event-loop>`, which
provide asynchronous APIs for :meth:`networking <loop.create_server>`,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7