[Python-checkins] cpython (merge 3.4 -> default): Merge 3.4 (asyncio doc)
victor.stinner
python-checkins at python.org
Mon Oct 13 00:10:11 CEST 2014
https://hg.python.org/cpython/rev/3ea5ebfd13e4
changeset: 93014:3ea5ebfd13e4
parent: 93008:4c9d27eef892
parent: 93013:1f649b8cf69a
user: Victor Stinner <victor.stinner at gmail.com>
date: Mon Oct 13 00:10:02 2014 +0200
summary:
Merge 3.4 (asyncio doc)
files:
Doc/library/asyncio-dev.rst | 47 ++++++----
Doc/library/asyncio-eventloop.rst | 64 +++++++------
Doc/library/asyncio-eventloops.rst | 2 +-
Doc/library/asyncio-protocol.rst | 32 +++++-
Doc/library/asyncio-stream.rst | 78 ++++++++++++++++++
Doc/library/asyncio-task.rst | 3 +-
6 files changed, 168 insertions(+), 58 deletions(-)
diff --git a/Doc/library/asyncio-dev.rst b/Doc/library/asyncio-dev.rst
--- a/Doc/library/asyncio-dev.rst
+++ b/Doc/library/asyncio-dev.rst
@@ -166,25 +166,34 @@
Output::
Task exception was never retrieved
- future: <Task finished bug() done at asyncio/coroutines.py:139 exception=Exception('not consumed',)>
- source_traceback: Object created at (most recent call last):
- File "test.py", line 10, in <module>
- asyncio.async(bug())
- File "asyncio/tasks.py", line 510, in async
- task = loop.create_task(coro_or_future)
+ future: <Task finished coro=<coro() done, defined at asyncio/coroutines.py:139> exception=Exception('not consumed',)>
Traceback (most recent call last):
- File "asyncio/tasks.py", line 244, in _step
+ File "asyncio/tasks.py", line 237, in _step
result = next(coro)
- File "coroutines.py", line 78, in __next__
- return next(self.gen)
File "asyncio/coroutines.py", line 141, in coro
res = func(*args, **kw)
- File "test.py", line 7, in bug
+ File "test.py", line 5, in bug
raise Exception("not consumed")
Exception: not consumed
:ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the
-traceback where the task was created.
+traceback where the task was created. Output in debug mode::
+
+ Task exception was never retrieved
+ future: <Task finished coro=<bug() done, defined at test.py:3> exception=Exception('not consumed',) created at test.py:8>
+ source_traceback: Object created at (most recent call last):
+ File "test.py", line 8, in <module>
+ asyncio.async(bug())
+ Traceback (most recent call last):
+ File "asyncio/tasks.py", line 237, in _step
+ result = next(coro)
+ File "asyncio/coroutines.py", line 79, in __next__
+ return next(self.gen)
+ File "asyncio/coroutines.py", line 141, in coro
+ res = func(*args, **kw)
+ File "test.py", line 5, in bug
+ raise Exception("not consumed")
+ Exception: not consumed
There are different options to fix this issue. The first option is to chain to
coroutine in another coroutine and use classic try/except::
@@ -303,15 +312,17 @@
Example of log::
Task was destroyed but it is pending!
- source_traceback: Object created at (most recent call last):
- File "test.py", line 17, in <module>
- task = asyncio.async(coro, loop=loop)
- File "asyncio/tasks.py", line 510, in async
- task = loop.create_task(coro_or_future)
- task: <Task pending kill_me() done at test.py:5 wait_for=<Future pending cb=[Task._wakeup()]>>
+ task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()]>>
:ref:`Enable the debug mode of asyncio <asyncio-debug-mode>` to get the
-traceback where the task was created.
+traceback where the task was created. Example of log in debug mode::
+
+ Task was destroyed but it is pending!
+ source_traceback: Object created at (most recent call last):
+ File "test.py", line 15, in <module>
+ task = asyncio.async(coro, loop=loop)
+ task: <Task pending coro=<kill_me() done, defined at test.py:5> wait_for=<Future pending cb=[Task._wakeup()] created at test.py:7> created at test.py:15>
+
.. seealso::
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
@@ -258,8 +258,6 @@
establish the connection in the background. When successful, the
coroutine returns a ``(transport, protocol)`` pair.
- On Windows with :class:`ProactorEventLoop`, SSL/TLS is not supported.
-
See the :meth:`BaseEventLoop.create_connection` method for parameters.
Availability: UNIX.
@@ -270,36 +268,42 @@
.. 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)
- Create a TCP server bound to *host* and *port*. Return a :class:`Server` object,
- its :attr:`~Server.sockets` attribute contains created sockets. Use the
- :meth:`Server.close` method to stop the server: close listening sockets.
+ Create a TCP server (socket type :data:`~socket.SOCK_STREAM`) bound to
+ *host* and *port*.
+
+ Return a :class:`Server` object, its :attr:`~Server.sockets` attribute
+ contains created sockets. Use the :meth:`Server.close` method to stop the
+ server: close listening sockets.
+
+ Parameters:
+
+ * 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. If not set
+ it will be determined from host (defaults to :data:`socket.AF_UNSPEC`).
+
+ * *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`).
+
+ * *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.
+
+ * *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.
This method is a :ref:`coroutine <coroutine>`.
- 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. If not set
- it will be determined from host (defaults to :data:`socket.AF_UNSPEC`).
-
- *flags* is a bitmask for :meth:`getaddrinfo`.
-
- *sock* can optionally be specified in order to use a preexisting
- socket object.
-
- *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.
-
- *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.
-
On Windows with :class:`ProactorEventLoop`, SSL/TLS is not supported.
.. seealso::
@@ -462,7 +466,7 @@
*protocol_factory* should instantiate object with :class:`BaseProtocol`
interface. *pipe* is file-like object.
- Return pair (transport, protocol), where transport support
+ Return pair (transport, protocol), where *transport* supports
:class:`WriteTransport` interface.
With :class:`SelectorEventLoop` event loop, the *pipe* is set to
diff --git a/Doc/library/asyncio-eventloops.rst b/Doc/library/asyncio-eventloops.rst
--- a/Doc/library/asyncio-eventloops.rst
+++ b/Doc/library/asyncio-eventloops.rst
@@ -76,7 +76,7 @@
Common limits of Windows event loops:
-- :meth:`~BaseEventLoop.create_unix_server` and
+- :meth:`~BaseEventLoop.create_unix_connection` and
:meth:`~BaseEventLoop.create_unix_server` are not supported: the socket
family :data:`socket.AF_UNIX` is specific to UNIX
- :meth:`~BaseEventLoop.add_signal_handler` and
diff --git a/Doc/library/asyncio-protocol.rst b/Doc/library/asyncio-protocol.rst
--- a/Doc/library/asyncio-protocol.rst
+++ b/Doc/library/asyncio-protocol.rst
@@ -439,10 +439,13 @@
Protocol examples
=================
-TCP echo client
----------------
+.. _asyncio-tcp-echo-client-protocol:
-TCP echo client example, send data and wait until the connection is closed::
+TCP echo client protocol
+------------------------
+
+TCP echo client using the :meth:`BaseEventLoop.create_connection` method, send
+data and wait until the connection is closed::
import asyncio
@@ -478,11 +481,19 @@
running loop. At :meth:`~BaseEventLoop.run_until_complete` exit, the loop is
no longer running, so there is no need to stop the loop in case of an error.
+.. seealso::
-TCP echo server
----------------
+ The :ref:`TCP echo client using streams <asyncio-tcp-echo-client-streams>`
+ example uses the :func:`asyncio.open_connection` function.
-TCP echo server example, send back received data and close the connection::
+
+.. _asyncio-tcp-echo-server-protocol:
+
+TCP echo server protocol
+------------------------
+
+TCP echo server using the :meth:`BaseEventLoop.create_server` method, send back
+received data and close the connection::
import asyncio
@@ -507,12 +518,12 @@
coro = loop.create_server(EchoServerClientProtocol, '127.0.0.1', 8888)
server = loop.run_until_complete(coro)
- # Server requests until CTRL+c is pressed
+ # Serve requests until CTRL+c is pressed
print('Serving on {}'.format(server.sockets[0].getsockname()))
try:
loop.run_forever()
except KeyboardInterrupt:
- print("exit")
+ pass
# Close the server
server.close()
@@ -524,6 +535,11 @@
methods are asynchronous. ``yield from`` is not needed because these transport
methods are not coroutines.
+.. seealso::
+
+ The :ref:`TCP echo server using streams <asyncio-tcp-echo-server-streams>`
+ example uses the :func:`asyncio.start_server` function.
+
.. _asyncio-udp-echo-client-protocol:
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
@@ -241,6 +241,84 @@
Stream examples
===============
+.. _asyncio-tcp-echo-client-streams:
+
+TCP echo client using streams
+-----------------------------
+
+TCP echo client using the :func:`asyncio.open_connection` function::
+
+ import asyncio
+
+ def tcp_echo_client(message, loop):
+ reader, writer = yield from asyncio.open_connection('127.0.0.1', 8888,
+ loop=loop)
+
+ print('Send: %r' % message)
+ writer.write(message.encode())
+
+ data = yield from reader.read(100)
+ print('Received: %r' % data.decode())
+
+ print('Close the socket')
+ writer.close()
+
+ message = 'Hello World!'
+ loop = asyncio.get_event_loop()
+ loop.run_until_complete(tcp_echo_client(message, loop))
+ loop.close()
+
+.. seealso::
+
+ The :ref:`TCP echo client protocol <asyncio-tcp-echo-client-protocol>`
+ example uses the :meth:`BaseEventLoop.create_connection` method.
+
+
+.. _asyncio-tcp-echo-server-streams:
+
+TCP echo server using streams
+-----------------------------
+
+TCP echo server using the :func:`asyncio.start_server` function::
+
+ import asyncio
+
+ @asyncio.coroutine
+ def handle_echo(reader, writer):
+ data = yield from reader.read(100)
+ message = data.decode()
+ addr = writer.get_extra_info('peername')
+ print("Received %r from %r" % (message, addr))
+
+ print("Send: %r" % message)
+ writer.write(data)
+ yield from writer.drain()
+
+ print("Close the client socket")
+ writer.close()
+
+ loop = asyncio.get_event_loop()
+ coro = asyncio.start_server(handle_echo, '127.0.0.1', 8888, loop=loop)
+ server = loop.run_until_complete(coro)
+
+ # Serve requests until CTRL+c is pressed
+ print('Serving on {}'.format(server.sockets[0].getsockname()))
+ try:
+ loop.run_forever()
+ except KeyboardInterrupt:
+ pass
+
+ # Close the server
+ server.close()
+ loop.run_until_complete(server.wait_closed())
+ loop.close()
+
+.. seealso::
+
+ The :ref:`TCP echo server protocol <asyncio-tcp-echo-server-protocol>`
+ example uses the :meth:`BaseEventLoop.create_server` method.
+
+
Get HTTP headers
----------------
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
@@ -478,7 +478,8 @@
.. function:: async(coro_or_future, \*, loop=None)
- Wrap a :ref:`coroutine object <coroutine>` in a future.
+ Schedule the execution of a :ref:`coroutine object <coroutine>`: wrap it in
+ a future. Return a :class:`Task` object.
If the argument is a :class:`Future`, it is returned directly.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list