mirror of
https://github.com/python/cpython.git
synced 2025-08-04 17:08:35 +00:00
bpo-33649: A copy-editing pass on asyncio documentation (GH-9376)
This commit is contained in:
Elvis Pranskevichus
Yury Selivanov
parent
3085534c39
commit
1fa2ec49be
12 changed files with 347 additions and 349 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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,13 +538,18 @@ 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.
|
||||
- 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).
|
||||
* 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).
|
||||
|
||||
* *family* can be set to either :data:`socket.AF_INET` or
|
||||
:data:`~socket.AF_INET6` to force the socket to use IPv4 or 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::
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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()
|
||||
|
||||
|
|
|
|||
|
|
@ -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 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 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 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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>`,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue