[Python-checkins] cpython: asyncio.docs: Improve wordings; add a note to the Coroutines section. Issue

yury.selivanov python-checkins at python.org
Thu Feb 20 22:21:01 CET 2014

• Previous message: [Python-checkins] release: Updates for threefourtool.py.
• Next message: [Python-checkins] cpython (3.3): Issue #20221: Removed conflicting (or circular) hypot definition
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

---

http://hg.python.org/cpython/rev/cd23d0c3f850
changeset: 89308:cd23d0c3f850
user: Yury Selivanov <yselivanov at sprymix.com>
date: Thu Feb 20 16:20:44 2014 -0500
summary:
 asyncio.docs: Improve wordings; add a note to the Coroutines section. Issue #20706
files:
 Doc/library/asyncio-eventloop.rst | 45 +++++++++---------
 Doc/library/asyncio-stream.rst | 14 ++--
 Doc/library/asyncio-sync.rst | 14 ++--
 Doc/library/asyncio-task.rst | 14 +++++-
 4 files changed, 49 insertions(+), 38 deletions(-)
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
--- a/Doc/library/asyncio-eventloop.rst
+++ b/Doc/library/asyncio-eventloop.rst
@@ -102,7 +102,8 @@
 
 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 @@
 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 @@
 :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 @@
 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 @@
 
 .. 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 @@
 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 @@
 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 @@
 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 @@
 :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 @@
 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 @@
 
 .. 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 @@
 
 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 @@
 
 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 @@
 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 @@
 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 @@
 *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 @@
 
 .. method:: wait_closed()
 
- Coroutine to wait until service is closed.
+ A :ref:`coroutine <coroutine>` to wait until service is closed.
 
 
 Handle
diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst
--- a/Doc/library/asyncio-stream.rst
+++ b/Doc/library/asyncio-stream.rst
@@ -30,7 +30,7 @@
 :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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 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 @@
 :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()
 
diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst
--- a/Doc/library/asyncio-sync.rst
+++ b/Doc/library/asyncio-sync.rst
@@ -124,7 +124,7 @@
 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 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 @@
 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 @@
 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 @@
 
 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 @@
 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 @@
 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()
 
diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst
--- a/Doc/library/asyncio-task.rst
+++ b/Doc/library/asyncio-task.rst
@@ -64,6 +64,14 @@
 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 @@
 
 .. 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 @@
 | | 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 @@
 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)
-- 
Repository URL: http://hg.python.org/cpython

---

• Previous message: [Python-checkins] release: Updates for threefourtool.py.
• Next message: [Python-checkins] cpython (3.3): Issue #20221: Removed conflicting (or circular) hypot definition
• Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]

---

More information about the Python-checkins mailing list