diff options
| -rw-r--r-- | Doc/library/asyncio-eventloop.rst | 32 | ||||
| -rw-r--r-- | Doc/library/asyncio-stream.rst | 16 | ||||
| -rw-r--r-- | Doc/library/asyncio-subprocess.rst | 12 | ||||
| -rw-r--r-- | Doc/library/asyncio-sync.rst | 20 | ||||
| -rw-r--r-- | Doc/library/asyncio-task.rst | 8 | ||||
| -rw-r--r-- | Doc/tools/extensions/pyspecific.py | 26 |
6 files changed, 72 insertions, 42 deletions
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst index 4f7fdfe..f2c8945 100644 --- a/Doc/library/asyncio-eventloop.rst +++ b/Doc/library/asyncio-eventloop.rst @@ -180,7 +180,7 @@ Coroutines 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 @@ -253,7 +253,7 @@ Creating connections (: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), @@ -271,7 +271,7 @@ Creating connections :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 @@ -290,7 +290,7 @@ Creating connections 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*. @@ -336,11 +336,13 @@ Creating listening connections :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. @@ -384,7 +386,7 @@ the file descriptor of a socket. 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 @@ -399,7 +401,7 @@ Low-level socket operations 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 @@ -416,7 +418,7 @@ Low-level socket operations 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*. @@ -438,7 +440,7 @@ Low-level socket operations 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* @@ -459,12 +461,12 @@ Low-level socket operations 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. @@ -476,7 +478,7 @@ Connect pipes 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. @@ -490,7 +492,7 @@ Use :class:`ProactorEventLoop` to support pipes on Windows. 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. @@ -543,7 +545,7 @@ Call a function in an :class:`~concurrent.futures.Executor` (pool of threads or 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. @@ -654,7 +656,7 @@ Server 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. diff --git a/Doc/library/asyncio-stream.rst b/Doc/library/asyncio-stream.rst index 3809d94..22b7341 100644 --- a/Doc/library/asyncio-stream.rst +++ b/Doc/library/asyncio-stream.rst @@ -9,7 +9,7 @@ Streams (high-level API) 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. @@ -32,7 +32,7 @@ Stream functions 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()`. @@ -56,7 +56,7 @@ Stream functions 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. @@ -68,7 +68,7 @@ Stream functions 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. @@ -106,7 +106,7 @@ StreamReader 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. @@ -116,7 +116,7 @@ StreamReader This method is a :ref:`coroutine <coroutine>`. - .. method:: readline() + .. coroutinemethod:: readline() Read one line, where "line" is a sequence of bytes ending with ``\n``. @@ -128,7 +128,7 @@ StreamReader 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 @@ -168,7 +168,7 @@ StreamWriter Close the transport: see :meth:`BaseTransport.close`. - .. method:: drain() + .. coroutinemethod:: drain() Let the write buffer of the underlying transport a chance to be flushed. diff --git a/Doc/library/asyncio-subprocess.rst b/Doc/library/asyncio-subprocess.rst index 570107e..1334f5b 100644 --- a/Doc/library/asyncio-subprocess.rst +++ b/Doc/library/asyncio-subprocess.rst @@ -27,7 +27,7 @@ Example to use it on Windows:: 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. @@ -39,7 +39,7 @@ Create a subprocess: high-level API using Process 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*. @@ -67,7 +67,7 @@ Create a subprocess: low-level API using subprocess.Popen 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 @@ -116,7 +116,7 @@ Run subprocesses asynchronously using the :mod:`subprocess` module. 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>`, @@ -193,7 +193,7 @@ Process :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. @@ -207,7 +207,7 @@ Process 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. diff --git a/Doc/library/asyncio-sync.rst b/Doc/library/asyncio-sync.rst index 80974d9..f036bc8 100644 --- a/Doc/library/asyncio-sync.rst +++ b/Doc/library/asyncio-sync.rst @@ -89,7 +89,7 @@ Lock Return ``True`` if the lock is acquired. - .. method:: acquire() + .. coroutinemethod:: acquire() Acquire a lock. @@ -139,7 +139,7 @@ Event 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. @@ -166,7 +166,7 @@ Condition 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. @@ -213,7 +213,7 @@ Condition There is no return value. - .. method:: wait() + .. coroutinemethod:: wait() Wait until notified. @@ -227,7 +227,7 @@ Condition This method is a :ref:`coroutine <coroutine>`. - .. method:: wait_for(predicate) + .. coroutinemethod:: wait_for(predicate) Wait until a predicate becomes true. @@ -258,7 +258,7 @@ Semaphore defaults to ``1``. If the value given is less than ``0``, :exc:`ValueError` is raised. - .. method:: acquire() + .. coroutinemethod:: acquire() Acquire a semaphore. @@ -273,7 +273,7 @@ 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 @@ -323,7 +323,7 @@ Queue 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. @@ -341,7 +341,7 @@ Queue 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. @@ -395,7 +395,7 @@ JoinableQueue 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. diff --git a/Doc/library/asyncio-task.rst b/Doc/library/asyncio-task.rst index 3008c86..edc05c3 100644 --- a/Doc/library/asyncio-task.rst +++ b/Doc/library/asyncio-task.rst @@ -545,7 +545,7 @@ Task functions 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 @@ -554,6 +554,8 @@ Task functions 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. @@ -581,7 +583,7 @@ Task functions 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 @@ -626,7 +628,7 @@ Task functions 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 diff --git a/Doc/tools/extensions/pyspecific.py b/Doc/tools/extensions/pyspecific.py index 7baacc4..17b3c82 100644 --- a/Doc/tools/extensions/pyspecific.py +++ b/Doc/tools/extensions/pyspecific.py @@ -145,6 +145,30 @@ class PyDecoratorMethod(PyDecoratorMixin, PyClassmember): 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): @@ -347,5 +371,7 @@ def setup(app): 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} |