Creating connections
--------------------
-.. method:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
+.. coroutinemethod:: BaseEventLoop.create_connection(protocol_factory, host=None, port=None, \*, ssl=None, family=0, proto=0, flags=0, sock=None, local_addr=None, server_hostname=None)
Create a streaming transport connection to a given Internet *host* and
*port*: socket family :py:data:`~socket.AF_INET` or
(:class:`StreamReader`, :class:`StreamWriter`) instead of a protocol.
-.. method:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
+.. coroutinemethod:: BaseEventLoop.create_datagram_endpoint(protocol_factory, local_addr=None, remote_addr=None, \*, family=0, proto=0, flags=0)
Create datagram connection: socket family :py:data:`~socket.AF_INET` or
:py:data:`~socket.AF_INET6` depending on *host* (or *family* if specified),
:ref:`UDP echo server protocol <asyncio-udp-echo-server-protocol>` examples.
-.. method:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
+.. coroutinemethod:: BaseEventLoop.create_unix_connection(protocol_factory, path, \*, ssl=None, sock=None, server_hostname=None)
Create UNIX connection: socket family :py:data:`~socket.AF_UNIX`, socket
type :py:data:`~socket.SOCK_STREAM`. The :py:data:`~socket.AF_UNIX` socket
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)
+.. coroutinemethod:: 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 (socket type :data:`~socket.SOCK_STREAM`) bound to
*host* and *port*.
:class:`StreamWriter`) pair and calls back a function with this pair.
-.. method:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
+.. coroutinemethod:: BaseEventLoop.create_unix_server(protocol_factory, path=None, \*, sock=None, backlog=100, ssl=None)
Similar to :meth:`BaseEventLoop.create_server`, but specific to the
socket family :py:data:`~socket.AF_UNIX`.
+ This method is a :ref:`coroutine <coroutine>`.
+
Availability: UNIX.
Low-level socket operations
---------------------------
-.. method:: BaseEventLoop.sock_recv(sock, nbytes)
+.. coroutinemethod:: BaseEventLoop.sock_recv(sock, nbytes)
Receive data from the socket. The return value is a bytes object
representing the data received. The maximum amount of data to be received
The :meth:`socket.socket.recv` method.
-.. method:: BaseEventLoop.sock_sendall(sock, data)
+.. coroutinemethod:: BaseEventLoop.sock_sendall(sock, data)
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
The :meth:`socket.socket.sendall` method.
-.. method:: BaseEventLoop.sock_connect(sock, address)
+.. coroutinemethod:: BaseEventLoop.sock_connect(sock, address)
Connect to a remote socket at *address*.
method.
-.. method:: BaseEventLoop.sock_accept(sock)
+.. coroutinemethod:: BaseEventLoop.sock_accept(sock)
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*
Resolve host name
-----------------
-.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
+.. coroutinemethod:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
This method is a :ref:`coroutine <coroutine>`, similar to
:meth:`socket.getaddrinfo` function but non-blocking.
-.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
+.. coroutinemethod:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
This method is a :ref:`coroutine <coroutine>`, similar to
:meth:`socket.getnameinfo` function but non-blocking.
On Windows with :class:`SelectorEventLoop`, these methods are not supported.
Use :class:`ProactorEventLoop` to support pipes on Windows.
-.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
+.. coroutinemethod:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
Register read pipe in eventloop.
This method is a :ref:`coroutine <coroutine>`.
-.. method:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
+.. coroutinemethod:: BaseEventLoop.connect_write_pipe(protocol_factory, pipe)
Register write pipe in eventloop.
pool of processes). By default, an event loop uses a thread pool executor
(:class:`~concurrent.futures.ThreadPoolExecutor`).
-.. method:: BaseEventLoop.run_in_executor(executor, callback, \*args)
+.. coroutinemethod:: BaseEventLoop.run_in_executor(executor, callback, \*args)
Arrange for a callback to be called in the specified executor.
The server is closed asynchonously, use the :meth:`wait_closed` coroutine
to wait until the server is closed.
- .. method:: wait_closed()
+ .. coroutinemethod:: wait_closed()
Wait until the :meth:`close` method completes.
Stream functions
================
-.. function:: open_connection(host=None, port=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: open_connection(host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
A wrapper for :meth:`~BaseEventLoop.create_connection()` returning a (reader,
writer) pair.
This function is a :ref:`coroutine <coroutine>`.
-.. function:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: start_server(client_connected_cb, host=None, port=None, \*, loop=None, limit=None, \*\*kwds)
Start a socket server, with a callback for each client connected. The return
value is the same as :meth:`~BaseEventLoop.create_server()`.
This function is a :ref:`coroutine <coroutine>`.
-.. function:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: open_unix_connection(path=None, \*, loop=None, limit=None, **kwds)
A wrapper for :meth:`~BaseEventLoop.create_unix_connection()` returning
a (reader, writer) pair.
Availability: UNIX.
-.. function:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
+.. coroutinefunction:: start_unix_server(client_connected_cb, path=None, \*, loop=None, limit=None, **kwds)
Start a UNIX Domain Socket server, with a callback for each client connected.
Set the transport.
- .. method:: read(n=-1)
+ .. coroutinemethod:: read(n=-1)
Read up to *n* bytes. If *n* is not provided, or set to ``-1``,
read until EOF and return all read bytes.
This method is a :ref:`coroutine <coroutine>`.
- .. method:: readline()
+ .. coroutinemethod:: readline()
Read one line, where "line" is a sequence of bytes ending with ``\n``.
This method is a :ref:`coroutine <coroutine>`.
- .. method:: readexactly(n)
+ .. coroutinemethod:: readexactly(n)
Read exactly *n* bytes. Raise an :exc:`IncompleteReadError` if the end of
the stream is reached before *n* can be read, the
Close the transport: see :meth:`BaseTransport.close`.
- .. method:: drain()
+ .. coroutinemethod:: drain()
Let the write buffer of the underlying transport a chance to be flushed.
Create a subprocess: high-level API using Process
-------------------------------------------------
-.. function:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+.. coroutinefunction:: create_subprocess_exec(\*args, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
Create a subprocess.
This function is a :ref:`coroutine <coroutine>`.
-.. function:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
+.. coroutinefunction:: create_subprocess_shell(cmd, stdin=None, stdout=None, stderr=None, loop=None, limit=None, \*\*kwds)
Run the shell command *cmd*.
Run subprocesses asynchronously using the :mod:`subprocess` module.
-.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
Create a subprocess from one or more string arguments (character strings or
bytes strings encoded to the :ref:`filesystem encoding
See the constructor of the :class:`subprocess.Popen` class for parameters.
-.. method:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
+.. coroutinemethod:: BaseEventLoop.subprocess_shell(protocol_factory, cmd, \*, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, \*\*kwargs)
Create a subprocess from *cmd*, which is a character string or a bytes
string encoded to the :ref:`filesystem encoding <filesystem-encoding>`,
:meth:`~subprocess.Popen.wait` method of the :class:`~subprocess.Popen`
class is implemented as a busy loop.
- .. method:: wait()
+ .. coroutinemethod:: wait()
Wait for child process to terminate. Set and return :attr:`returncode`
attribute.
blocks waiting for the OS pipe buffer to accept more data. Use the
:meth:`communicate` method when using pipes to avoid that.
- .. method:: communicate(input=None)
+ .. coroutinemethod:: communicate(input=None)
Interact with process: Send data to stdin. Read data from stdout and
stderr, until end-of-file is reached. Wait for process to terminate.
Return ``True`` if the lock is acquired.
- .. method:: acquire()
+ .. coroutinemethod:: acquire()
Acquire a lock.
true are awakened. Coroutine that call :meth:`wait` once the flag is true
will not block at all.
- .. method:: wait()
+ .. coroutinemethod:: wait()
Block until the internal flag is true.
object, and it is used as the underlying lock. Otherwise,
a new :class:`Lock` object is created and used as the underlying lock.
- .. method:: acquire()
+ .. coroutinemethod:: acquire()
Acquire the underlying lock.
There is no return value.
- .. method:: wait()
+ .. coroutinemethod:: wait()
Wait until notified.
This method is a :ref:`coroutine <coroutine>`.
- .. method:: wait_for(predicate)
+ .. coroutinemethod:: wait_for(predicate)
Wait until a predicate becomes true.
defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError`
is raised.
- .. method:: acquire()
+ .. coroutinemethod:: acquire()
Acquire a semaphore.
Returns ``True`` if semaphore can not be acquired immediately.
- .. method:: release()
+ .. coroutinemethod:: release()
Release a semaphore, incrementing the internal counter by one. When it
was zero on entry and another coroutine is waiting for it to become
If the Queue was initialized with ``maxsize=0`` (the default), then
:meth:`full()` is never ``True``.
- .. method:: get()
+ .. coroutinemethod:: get()
Remove and return an item from the queue. If queue is empty, wait until
an item is available.
Return an item if one is immediately available, else raise
:exc:`QueueEmpty`.
- .. method:: put(item)
+ .. coroutinemethod:: put(item)
Put an item into the queue. If the queue is full, wait until a free slot
is available before adding item.
A subclass of :class:`Queue` with :meth:`task_done` and :meth:`join`
methods.
- .. method:: join()
+ .. coroutinemethod:: join()
Block until all items in the queue have been gotten and processed.
Return ``True`` if *func* is a decorated :ref:`coroutine function
<coroutine>`.
-.. function:: sleep(delay, result=None, \*, loop=None)
+.. coroutinefunction:: sleep(delay, result=None, \*, loop=None)
Create a :ref:`coroutine <coroutine>` that completes after a given
time (in seconds). If *result* is provided, it is produced to the caller
The resolution of the sleep depends on the :ref:`granularity of the event
loop <asyncio-delayed-calls>`.
+ This function is a :ref:`coroutine <coroutine>`.
+
.. function:: shield(arg, \*, loop=None)
Wait for a future, shielding it from cancellation.
except CancelledError:
res = None
-.. function:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
+.. coroutinefunction:: wait(futures, \*, loop=None, timeout=None, return_when=ALL_COMPLETED)
Wait for the Futures and coroutine objects given by the sequence *futures*
to complete. Coroutines will be wrapped in Tasks. Returns two sets of
when the timeout occurs are returned in the second set.
-.. function:: wait_for(fut, timeout, \*, loop=None)
+.. coroutinefunction:: wait_for(fut, timeout, \*, loop=None)
Wait for the single :class:`Future` or :ref:`coroutine object <coroutine>`
to complete with timeout. If *timeout* is ``None``, block until the future
return PyClassmember.run(self)
+class PyCoroutineMixin(object):
+ def handle_signature(self, sig, signode):
+ ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
+# signode.insert(0, addnodes.desc_addname('coroutine ', 'coroutine '))
+ signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
+ return ret
+
+ def needs_arglist(self):
+ return False
+
+
+class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
+ def run(self):
+ # a decorator function is a function after all
+ self.name = 'py:function'
+ return PyModulelevel.run(self)
+
+
+class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
+ def run(self):
+ self.name = 'py:method'
+ return PyClassmember.run(self)
+
+
# Support for documenting version of removal in deprecations
class DeprecatedRemoved(Directive):
app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
+ app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
+ app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
app.add_directive('miscnews', MiscNews)
return {'version': '1.0', 'parallel_read_safe': True}
projects / python / commitdiff