[Python-checkins] cpython (merge 3.4 -> default): (Merge 3.4) Tulip issue 83: document more asyncio functions in docstrings
victor.stinner
python-checkins at python.org
Thu Jun 19 17:14:26 CEST 2014
http://hg.python.org/cpython/rev/493d1ae3227b
changeset: 91276:493d1ae3227b
parent: 91274:706fab0213db
parent: 91275:aaee7df990a2
user: Victor Stinner <victor.stinner at gmail.com>
date: Thu Jun 19 17:14:05 2014 +0200
summary:
(Merge 3.4) Tulip issue 83: document more asyncio functions in docstrings
files:
Doc/library/asyncio-eventloop.rst | 7 +-
Lib/asyncio/base_events.py | 21 ++++++++-
Lib/asyncio/selector_events.py | 41 +++++++++++++++++-
3 files changed, 58 insertions(+), 11 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
@@ -311,11 +311,10 @@
.. 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 <coroutine>` method which creates a TCP server bound to
- host and port.
+ Create a TCP server bound to host and port. Return an
+ :class:`AbstractServer` object which can be used to stop the service.
- The return value is a :class:`AbstractServer` object which can be used to stop
- the service.
+ 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
diff --git a/Lib/asyncio/base_events.py b/Lib/asyncio/base_events.py
--- a/Lib/asyncio/base_events.py
+++ b/Lib/asyncio/base_events.py
@@ -320,7 +320,7 @@
"than the current one")
def call_soon_threadsafe(self, callback, *args):
- """XXX"""
+ """Like call_soon(), but thread safe."""
handle = self._call_soon(callback, args, check_loop=False)
self._write_to_self()
return handle
@@ -358,7 +358,17 @@
def create_connection(self, protocol_factory, host=None, port=None, *,
ssl=None, family=0, proto=0, flags=0, sock=None,
local_addr=None, server_hostname=None):
- """XXX"""
+ """Connect to a TCP server.
+
+ Create a streaming transport connection to a given Internet host and
+ port: socket family AF_INET or socket.AF_INET6 depending on host (or
+ family if specified), socket type SOCK_STREAM. protocol_factory must be
+ a callable returning a protocol instance.
+
+ This method is a coroutine which will try to establish the connection
+ in the background. When successful, the coroutine returns a
+ (transport, protocol) pair.
+ """
if server_hostname is not None and not ssl:
raise ValueError('server_hostname is only meaningful with ssl')
@@ -557,7 +567,12 @@
backlog=100,
ssl=None,
reuse_address=None):
- """XXX"""
+ """Create a TCP server bound to host and port.
+
+ Return an AbstractServer object which can be used to stop the service.
+
+ This method is a coroutine.
+ """
if isinstance(ssl, bool):
raise TypeError('ssl argument must be an SSLContext or None')
if host is not None or port is not None:
diff --git a/Lib/asyncio/selector_events.py b/Lib/asyncio/selector_events.py
--- a/Lib/asyncio/selector_events.py
+++ b/Lib/asyncio/selector_events.py
@@ -226,7 +226,14 @@
return False
def sock_recv(self, sock, n):
- """XXX"""
+ """Receive data from the socket.
+
+ The return value is a bytes object representing the data received.
+ The maximum amount of data to be received at once is specified by
+ nbytes.
+
+ This method is a coroutine.
+ """
fut = futures.Future(loop=self)
self._sock_recv(fut, False, sock, n)
return fut
@@ -253,7 +260,16 @@
fut.set_result(data)
def sock_sendall(self, sock, data):
- """XXX"""
+ """Send data to the socket.
+
+ The socket must be connected to a remote socket. 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 processed by the receiving end of the connection.
+
+ This method is a coroutine.
+ """
fut = futures.Future(loop=self)
if data:
self._sock_sendall(fut, False, sock, data)
@@ -285,7 +301,16 @@
self.add_writer(fd, self._sock_sendall, fut, True, sock, data)
def sock_connect(self, sock, address):
- """XXX"""
+ """Connect to a remote socket at address.
+
+ The address must be already resolved to avoid the trap of hanging the
+ entire event loop when the address requires doing a DNS lookup. For
+ example, it must be an IP address, not an hostname, for AF_INET and
+ AF_INET6 address families. Use getaddrinfo() to resolve the hostname
+ asynchronously.
+
+ This method is a coroutine.
+ """
fut = futures.Future(loop=self)
try:
base_events._check_resolved_address(sock, address)
@@ -318,7 +343,15 @@
fut.set_result(None)
def sock_accept(self, sock):
- """XXX"""
+ """Accept a connection.
+
+ The socket must be bound to an address and listening for connections.
+ The return value is a pair (conn, address) where conn is a new socket
+ object usable to send and receive data on the connection, and address
+ is the address bound to the socket on the other end of the connection.
+
+ This method is a coroutine.
+ """
fut = futures.Future(loop=self)
self._sock_accept(fut, False, sock)
return fut
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list