[Python-checkins] cpython (3.5): docs: Update asyncio docs & whatsnew

[yury.selivanov]

https://hg.python.org/cpython/rev/83450939b106
changeset:   101386:83450939b106
branch:      3.5
parent:      101383:32ceaad6243d
user:        Yury Selivanov <yselivanov at sprymix.com>
date:        Mon May 16 16:23:00 2016 -0400
summary:
  docs: Update asyncio docs & whatsnew

files:
  Doc/library/asyncio-eventloop.rst |  21 +++++++++++
  Doc/library/asyncio-stream.rst    |  36 +++++++++++++++++++
  Doc/library/asyncio-task.rst      |   2 +
  Doc/whatsnew/3.5.rst              |  27 ++++++++++++++
  4 files changed, 86 insertions(+), 0 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
@@ -179,6 +179,20 @@
    The :func:`asyncio.sleep` function.
 
 
+Futures
+-------
+
+.. method:: BaseEventLoop.create_future()
+
+   Create an :class:`asyncio.Future` object attached to the loop.
+
+   This is a preferred way to create futures in asyncio, as event
+   loop implementations can provide alternative implementations
+   of the Future class (with better performance or instrumentation).
+
+   .. versionadded:: 3.5.2
+
+
 Tasks
 -----
 
@@ -669,6 +683,13 @@
    will be a ``dict`` object (see :meth:`call_exception_handler`
    documentation for details about context).
 
+.. method:: BaseEventLoop.get_exception_handler()
+
+   Return the exception handler, or ``None`` if the default one
+   is in use.
+
+   .. versionadded:: 3.5.2
+
 .. method:: BaseEventLoop.default_exception_handler(context)
 
    Default exception handler.
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
@@ -142,6 +142,30 @@
 
       This method is a :ref:`coroutine <coroutine>`.
 
+   .. coroutinemethod:: readuntil(separator=b'\n')
+
+      Read data from the stream until ``separator`` is found.
+
+      On success, the data and separator will be removed from the
+      internal buffer (consumed). Returned data will include the
+      separator at the end.
+
+      Configured stream limit is used to check result. Limit sets the
+      maximal length of data that can be returned, not counting the
+      separator.
+
+      If an EOF occurs and the complete separator is still not found,
+      an :exc:`IncompleteReadError` exception will be
+      raised, and the internal buffer will be reset.  The
+      :attr:`IncompleteReadError.partial` attribute may contain the
+      separator partially.
+
+      If the 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.
+
+      .. versionadded:: 3.5.2
+
    .. method:: at_eof()
 
       Return ``True`` if the buffer is empty and :meth:`feed_eof` was called.
@@ -251,6 +275,18 @@
       Read bytes string before the end of stream was reached (:class:`bytes`).
 
 
+LimitOverrunError
+=================
+
+.. exception:: LimitOverrunError
+
+   Reached the buffer limit while looking for a separator.
+
+   .. attribute:: consumed
+
+      Total number of to be consumed bytes.
+
+
 Stream examples
 ===============
 
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
@@ -677,6 +677,8 @@
 
    Passing ``None`` as *timeout* argument disables the manager logic.
 
+   .. versionadded:: 3.5.2
+
 .. coroutinefunction:: wait(futures, \*, loop=None, timeout=None,\
                             return_when=ALL_COMPLETED)
 
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -822,6 +822,33 @@
   method can now accept a list of hosts.
   (Contributed by Yann Sionneau.)
 
+Updates in 3.5.2:
+
+* New :meth:`loop.create_future() <asyncio.BaseEventLoop.create_future>`
+  method to create Future objects.  This allows alternative event
+  loop implementations, such as
+  `uvloop <https://github.com/MagicStack/uvloop>`_, to provide a faster
+  :class:`asyncio.Future` implementation.
+  (Contributed by Yury Selivanov.)
+
+* New :meth:`loop.get_exception_handler() <asyncio.BaseEventLoop.get_exception_handler>`
+  method to get the current exception handler.
+  (Contributed by Yury Selivanov.)
+
+* New :func:`~asyncio.timeout` context manager to simplify timeouts
+  handling code.
+  (Contributed by Andrew Svetlov.)
+
+* New :meth:`StreamReader.readuntil() <asyncio.StreamReader.readuntil>`
+  method to read data from the stream until a separator bytes
+  sequence appears.
+  (Contributed by Mark Korenberg.)
+
+* The :meth:`loop.getaddrinfo() <asyncio.BaseEventLoop.getaddrinfo>`
+  method is optimized to avoid calling the system ``getaddrinfo``
+  function if the address is already resolved.
+  (Contributed by A. Jesse Jiryu Davis.)
+
 
 bz2
 ---

-- 
Repository URL: https://hg.python.org/cpython