mirror of https://github.com/python/cpython
asyncio.docs: Improve wordings; add a note to the Coroutines section. Issue #20706
This commit is contained in:
parent
934c885885
commit
37f15bcfed
|
@ -102,7 +102,8 @@ Run an event loop
|
|||
|
||||
Run until the :class:`Future` is done.
|
||||
|
||||
If the argument is a coroutine, it is wrapped in a :class:`Task`.
|
||||
If the argument is a :ref:`coroutine <coroutine>`, it is wrapped
|
||||
in a :class:`Task`.
|
||||
|
||||
Return the Future's result, or raise its exception.
|
||||
|
||||
|
@ -207,7 +208,7 @@ Creating connections
|
|||
socket type :py:data:`~socket.SOCK_STREAM`. *protocol_factory* must be a
|
||||
callable returning a :ref:`protocol <asyncio-protocol>` instance.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>` which will try to
|
||||
This method is a :ref:`coroutine <coroutine>` which will try to
|
||||
establish the connection in the background. When successful, the
|
||||
coroutine returns a ``(transport, protocol)`` pair.
|
||||
|
||||
|
@ -274,7 +275,7 @@ Creating connections
|
|||
:py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
|
||||
socket type :py:data:`~socket.SOCK_DGRAM`.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>` which will try to
|
||||
This method is a :ref:`coroutine <coroutine>` which will try to
|
||||
establish the connection in the background. When successful, the
|
||||
coroutine returns a ``(transport, protocol)`` pair.
|
||||
|
||||
|
@ -288,7 +289,7 @@ Creating connections
|
|||
family is used to communicate between processes on the same machine
|
||||
efficiently.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>` which will try to
|
||||
This method is a :ref:`coroutine <coroutine>` which will try to
|
||||
establish the connection in the background. When successful, the
|
||||
coroutine returns a ``(transport, protocol)`` pair.
|
||||
|
||||
|
@ -302,8 +303,8 @@ Creating listening connections
|
|||
|
||||
.. method:: BaseEventLoop.create_server(protocol_factory, host=None, port=None, \*, family=socket.AF_UNSPEC, flags=socket.AI_PASSIVE, sock=None, backlog=100, ssl=None, reuse_address=None)
|
||||
|
||||
A :ref:`coroutine function <coroutine>` which creates a TCP server bound to host and
|
||||
port.
|
||||
A :ref:`coroutine <coroutine>` method which creates a TCP server bound to
|
||||
host and port.
|
||||
|
||||
The return value is a :class:`AbstractServer` object which can be used to stop
|
||||
the service.
|
||||
|
@ -332,8 +333,6 @@ Creating listening connections
|
|||
expire. If not specified will automatically be set to True on
|
||||
UNIX.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
The function :func:`start_server` creates a (:class:`StreamReader`,
|
||||
|
@ -380,7 +379,7 @@ Low-level socket operations
|
|||
representing the data received. The maximum amount of data to be received
|
||||
at once is specified by *nbytes*.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -392,9 +391,9 @@ Low-level socket operations
|
|||
This method continues to send data from *data* until either all data has
|
||||
been sent or an error occurs. ``None`` is returned on success. On error,
|
||||
an exception is raised, and there is no way to determine how much data, if
|
||||
any, was successfully sent.
|
||||
any, was successfully processed by the receiving end of the connection.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -410,7 +409,7 @@ Low-level socket operations
|
|||
:py:data:`~socket.AF_INET` and :py:data:`~socket.AF_INET6` address families.
|
||||
Use :meth:`getaddrinfo` to resolve the hostname asynchronously.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -427,7 +426,7 @@ Low-level socket operations
|
|||
and *address* is the address bound to the socket on the other end of the
|
||||
connection.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -440,13 +439,13 @@ Resolve host name
|
|||
|
||||
.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
|
||||
|
||||
Similar to the :meth:`socket.getaddrinfo` function, but return a
|
||||
:ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`, similar to
|
||||
:meth:`socket.getaddrinfo` function but non-blocking.
|
||||
|
||||
.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
|
||||
|
||||
Similar to the :meth:`socket.getnameinfo` function, but return a
|
||||
:ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`, similar to
|
||||
:meth:`socket.getnameinfo` function but non-blocking.
|
||||
|
||||
|
||||
Running subprocesses
|
||||
|
@ -472,7 +471,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
|||
|
||||
XXX
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
|
||||
|
@ -480,7 +479,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
|||
|
||||
XXX
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
See the constructor of the :class:`subprocess.Popen` class for parameters.
|
||||
|
||||
|
@ -493,7 +492,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
|||
Return pair (transport, protocol), where transport support
|
||||
:class:`ReadTransport` interface.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
|
||||
|
||||
|
@ -504,7 +503,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module.
|
|||
Return pair (transport, protocol), where transport support
|
||||
:class:`WriteTransport` interface.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
|
@ -549,6 +548,8 @@ pool of processes). By default, an event loop uses a thread pool executor
|
|||
*executor* is a :class:`~concurrent.futures.Executor` instance,
|
||||
the default executor is used if *executor* is ``None``.
|
||||
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: BaseEventLoop.set_default_executor(executor)
|
||||
|
||||
Set the default executor used by :meth:`run_in_executor`.
|
||||
|
@ -633,7 +634,7 @@ Server
|
|||
|
||||
.. method:: wait_closed()
|
||||
|
||||
Coroutine to wait until service is closed.
|
||||
A :ref:`coroutine <coroutine>` to wait until service is closed.
|
||||
|
||||
|
||||
Handle
|
||||
|
|
|
@ -30,7 +30,7 @@ Stream functions
|
|||
:class:`StreamReaderProtocol` classes, just copy the code -- there's really
|
||||
nothing special here except some convenience.)
|
||||
|
||||
This function returns a :ref:`coroutine object <coroutine>`.
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
|
||||
|
||||
|
@ -56,7 +56,7 @@ Stream functions
|
|||
The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
|
||||
a :class:`AbstractServer` object which can be used to stop the service.
|
||||
|
||||
This function returns a :ref:`coroutine object <coroutine>`.
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
|
||||
|
||||
|
@ -66,7 +66,7 @@ Stream functions
|
|||
See :func:`open_connection` for information about return value and other
|
||||
details.
|
||||
|
||||
This function returns a :ref:`coroutine object <coroutine>`.
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
Availability: UNIX.
|
||||
|
||||
|
@ -77,7 +77,7 @@ Stream functions
|
|||
See :func:`start_server` for information about return value and other
|
||||
details.
|
||||
|
||||
This function returns a :ref:`coroutine object <coroutine>`.
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
Availability: UNIX.
|
||||
|
||||
|
@ -116,7 +116,7 @@ StreamReader
|
|||
If the EOF was received and the internal buffer is empty,
|
||||
return an empty ``bytes`` object.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: readline()
|
||||
|
||||
|
@ -128,7 +128,7 @@ StreamReader
|
|||
If the EOF was received and the internal buffer is empty,
|
||||
return an empty ``bytes`` object.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: readexactly(n)
|
||||
|
||||
|
@ -137,7 +137,7 @@ StreamReader
|
|||
:attr:`IncompleteReadError.partial` attribute of the exception contains
|
||||
the partial read bytes.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: at_eof()
|
||||
|
||||
|
|
|
@ -124,7 +124,7 @@ Event
|
|||
Otherwise, block until another coroutine calls :meth:`set` to set the
|
||||
flag to true, then return ``True``.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
|
||||
Condition
|
||||
|
@ -175,7 +175,7 @@ Condition
|
|||
condition variable in another coroutine. Once awakened, it re-acquires
|
||||
the lock and returns ``True``.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: wait_for(predicate)
|
||||
|
||||
|
@ -184,7 +184,7 @@ Condition
|
|||
The predicate should be a callable which result will be interpreted as a
|
||||
boolean value. The final predicate value is the return value.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
|
||||
Semaphores
|
||||
|
@ -217,7 +217,7 @@ Semaphore
|
|||
until some other coroutine has called :meth:`release` to make it larger
|
||||
than ``0``, and then return ``True``.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: locked()
|
||||
|
||||
|
@ -279,7 +279,7 @@ Queue
|
|||
|
||||
If you yield from :meth:`get()`, wait until a item is available.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: get_nowait()
|
||||
|
||||
|
@ -295,7 +295,7 @@ Queue
|
|||
If you yield from ``put()``, wait until a free slot is available before
|
||||
adding item.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: put_nowait(item)
|
||||
|
||||
|
@ -350,7 +350,7 @@ JoinableQueue
|
|||
it is complete. When the count of unfinished tasks drops to zero,
|
||||
:meth:`join` unblocks.
|
||||
|
||||
This method returns a :ref:`coroutine object <coroutine>`.
|
||||
This method is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
.. method:: task_done()
|
||||
|
||||
|
|
|
@ -64,6 +64,14 @@ Coroutines (and tasks) can only run when the event loop is running.
|
|||
message is logged. See :ref:`Detect coroutines never scheduled
|
||||
<asyncio-coroutine-not-scheduled>`.
|
||||
|
||||
.. note::
|
||||
|
||||
In this documentation, some methods are documented as coroutines,
|
||||
even if they are plain Python functions returning a :class:`Future`.
|
||||
This is intentional to have a freedom of tweaking the implementation
|
||||
of these functions in the future. If such a function is needed to be
|
||||
used in a callback-style code, wrap its result with :func:`async`.
|
||||
|
||||
|
||||
.. _asyncio-hello-world-coroutine:
|
||||
|
||||
|
@ -440,7 +448,7 @@ Task functions
|
|||
|
||||
.. function:: sleep(delay, result=None, \*, loop=None)
|
||||
|
||||
Create a :ref:`coroutine object <coroutine>` that completes after a given
|
||||
Create a :ref:`coroutine <coroutine>` that completes after a given
|
||||
time (in seconds). If *result* is provided, it is produced to the caller
|
||||
when the coroutine completes.
|
||||
|
||||
|
@ -505,7 +513,7 @@ Task functions
|
|||
| | futures finish or are cancelled. |
|
||||
+-----------------------------+----------------------------------------+
|
||||
|
||||
This function returns a :ref:`coroutine object <coroutine>`.
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
Usage::
|
||||
|
||||
|
@ -529,6 +537,8 @@ Task functions
|
|||
cancels the task and raises :exc:`TimeoutError`. To avoid the task
|
||||
cancellation, wrap it in :func:`shield`.
|
||||
|
||||
This function is a :ref:`coroutine <coroutine>`.
|
||||
|
||||
Usage::
|
||||
|
||||
result = yield from asyncio.wait_for(fut, 60.0)
|
||||
|
|
Loading…
Reference in New Issue