[Python-checkins] cpython: asyncio doc: reorder sections
victor.stinner
python-checkins at python.org
Tue Dec 3 00:49:39 CET 2013
http://hg.python.org/cpython/rev/9ac097756dba
changeset: 87722:9ac097756dba
user: Victor Stinner <victor.stinner at gmail.com>
date: Tue Dec 03 00:49:26 2013 +0100
summary:
asyncio doc: reorder sections
files:
Doc/library/asyncio.rst | 1072 +++++++++++++-------------
1 files changed, 536 insertions(+), 536 deletions(-)
diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -326,6 +326,40 @@
to bind the socket to locally. The *local_host* and *local_port*
are looked up using getaddrinfo(), similarly to *host* and *port*.
+
+Resolve name
+^^^^^^^^^^^^
+
+.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
+
+ XXX
+
+.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
+
+ XXX
+
+
+Running subprocesses
+^^^^^^^^^^^^^^^^^^^^
+
+Run subprocesses asynchronously using the :mod:`subprocess` module.
+
+.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=False, bufsize=0, \*\*kwargs)
+
+ XXX
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ 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, universal_newlines=False, shell=True, bufsize=0, \*\*kwargs)
+
+ XXX
+
+ This method returns a :ref:`coroutine <coroutine>`.
+
+ See the constructor of the :class:`subprocess.Popen` class for parameters.
+
.. method:: BaseEventLoop.connect_read_pipe(protocol_factory, pipe)
Register read pipe in eventloop.
@@ -349,492 +383,104 @@
This method returns a :ref:`coroutine <coroutine>`.
-Resolve name
-^^^^^^^^^^^^
+.. _coroutine:
-.. method:: BaseEventLoop.getaddrinfo(host, port, \*, family=0, type=0, proto=0, flags=0)
-
- XXX
-
-.. method:: BaseEventLoop.getnameinfo(sockaddr, flags=0)
-
- XXX
-
-
-Running subprocesses
-^^^^^^^^^^^^^^^^^^^^
-
-Run subprocesses asynchronously using the :mod:`subprocess` module.
-
-.. method:: BaseEventLoop.subprocess_exec(protocol_factory, \*args, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, universal_newlines=False, shell=False, bufsize=0, \*\*kwargs)
-
- XXX
-
- This method returns a :ref:`coroutine <coroutine>`.
-
- 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, universal_newlines=False, shell=True, bufsize=0, \*\*kwargs)
-
- XXX
-
- This method returns a :ref:`coroutine <coroutine>`.
-
- See the constructor of the :class:`subprocess.Popen` class for parameters.
-
-
-Network functions
------------------
-
-.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
-
- A wrapper for create_connection() returning a (reader, writer) pair.
-
- The reader returned is a StreamReader instance; the writer is a
- :class:`Transport`.
-
- The arguments are all the usual arguments to
- :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
- common are positional host and port, with various optional keyword arguments
- following.
-
- Additional optional keyword arguments are *loop* (to set the event loop
- instance to use) and *limit* (to set the buffer limit passed to the
- StreamReader).
-
- (If you want to customize the :class:`StreamReader` and/or
- :class:`StreamReaderProtocol` classes, just copy the code -- there's really
- nothing special here except some convenience.)
-
- This function returns a :ref:`coroutine <coroutine>`.
-
-.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
-
- Start a socket server, call back for each client connected.
-
- The first parameter, *client_connected_cb*, takes two parameters:
- *client_reader*, *client_writer*. *client_reader* is a
- :class:`StreamReader` object, while *client_writer* is a
- :class:`StreamWriter` object. This parameter can either be a plain callback
- function or a :ref:`coroutine <coroutine>`; if it is a coroutine, it will be
- automatically converted into a :class:`Task`.
-
- The rest of the arguments are all the usual arguments to
- :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
- common are positional host and port, with various optional keyword arguments
- following. The return value is the same as
- :meth:`~BaseEventLoop.create_server()`.
-
- Additional optional keyword arguments are *loop* (to set the event loop
- instance to use) and *limit* (to set the buffer limit passed to the
- :class:`StreamReader`).
-
- The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
- a :class:`AbstractServer` object which can be used to stop the service.
-
- This function returns a :ref:`coroutine <coroutine>`.
-
-
-.. _protocol:
-
-Protocols
----------
-
-:mod:`asyncio` provides base classes that you can subclass to implement
-your network protocols. Those classes are used in conjunction with
-:ref:`transports <transport>` (see below): the protocol parses incoming
-data and asks for the writing of outgoing data, while the transport is
-responsible for the actual I/O and buffering.
-
-When subclassing a protocol class, it is recommended you override certain
-methods. Those methods are callbacks: they will be called by the transport
-on certain events (for example when some data is received); you shouldn't
-call them yourself, unless you are implementing a transport.
-
-.. note::
- All callbacks have default implementations, which are empty. Therefore,
- you only need to implement the callbacks for the events in which you
- are interested.
-
-
-Protocol classes
-^^^^^^^^^^^^^^^^
-
-.. class:: Protocol
-
- The base class for implementing streaming protocols (for use with
- e.g. TCP and SSL transports).
-
-.. class:: DatagramProtocol
-
- The base class for implementing datagram protocols (for use with
- e.g. UDP transports).
-
-.. class:: SubprocessProtocol
-
- The base class for implementing protocols communicating with child
- processes (through a set of unidirectional pipes).
-
-
-Connection callbacks
-^^^^^^^^^^^^^^^^^^^^
-
-These callbacks may be called on :class:`Protocol` and
-:class:`SubprocessProtocol` instances:
-
-.. method:: BaseProtocol.connection_made(transport)
-
- Called when a connection is made.
-
- The *transport* argument is the transport representing the
- connection. You are responsible for storing it somewhere
- (e.g. as an attribute) if you need to.
-
-.. method:: BaseProtocol.connection_lost(exc)
-
- Called when the connection is lost or closed.
-
- The argument is either an exception object or :const:`None`.
- The latter means a regular EOF is received, or the connection was
- aborted or closed by this side of the connection.
-
-:meth:`connection_made` and :meth:`connection_lost` are called exactly once
-per successful connection. All other callbacks will be called between those
-two methods, which allows for easier resource management in your protocol
-implementation.
-
-The following callbacks may be called only on :class:`SubprocessProtocol`
-instances:
-
-.. method:: SubprocessProtocol.pipe_data_received(fd, data)
-
- Called when the child process writes data into its stdout or stderr pipe.
- *fd* is the integer file descriptor of the pipe. *data* is a non-empty
- bytes object containing the data.
-
-.. method:: SubprocessProtocol.pipe_connection_lost(fd, exc)
-
- Called when one of the pipes communicating with the child process
- is closed. *fd* is the integer file descriptor that was closed.
-
-.. method:: SubprocessProtocol.process_exited()
-
- Called when the child process has exited.
-
-
-Data reception callbacks
-^^^^^^^^^^^^^^^^^^^^^^^^
-
-Streaming protocols
-"""""""""""""""""""
-
-The following callbacks are called on :class:`Protocol` instances:
-
-.. method:: Protocol.data_received(data)
-
- Called when some data is received. *data* is a non-empty bytes object
- containing the incoming data.
-
- .. note::
- Whether the data is buffered, chunked or reassembled depends on
- the transport. In general, you shouldn't rely on specific semantics
- and instead make your parsing generic and flexible enough. However,
- data is always received in the correct order.
-
-.. method:: Protocol.eof_received()
-
- Calls when the other end signals it won't send any more data
- (for example by calling :meth:`write_eof`, if the other end also uses
- asyncio).
-
- This method may return a false value (including None), in which case
- the transport will close itself. Conversely, if this method returns a
- true value, closing the transport is up to the protocol. Since the
- default implementation returns None, it implicitly closes the connection.
-
- .. note::
- Some transports such as SSL don't support half-closed connections,
- in which case returning true from this method will not prevent closing
- the connection.
-
-:meth:`data_received` can be called an arbitrary number of times during
-a connection. However, :meth:`eof_received` is called at most once
-and, if called, :meth:`data_received` won't be called after it.
-
-Datagram protocols
-""""""""""""""""""
-
-The following callbacks are called on :class:`DatagramProtocol` instances.
-
-.. method:: DatagramProtocol.datagram_received(data, addr)
-
- Called when a datagram is received. *data* is a bytes object containing
- the incoming data. *addr* is the address of the peer sending the data;
- the exact format depends on the transport.
-
-.. method:: DatagramProtocol.error_received(exc)
-
- Called when a previous send or receive operation raises an
- :class:`OSError`. *exc* is the :class:`OSError` instance.
-
- This method is called in rare conditions, when the transport (e.g. UDP)
- detects that a datagram couldn't be delivered to its recipient.
- In many conditions though, undeliverable datagrams will be silently
- dropped.
-
-
-Flow control callbacks
-^^^^^^^^^^^^^^^^^^^^^^
-
-These callbacks may be called on :class:`Protocol` and
-:class:`SubprocessProtocol` instances:
-
-.. method:: BaseProtocol.pause_writing()
-
- Called when the transport's buffer goes over the high-water mark.
-
-.. method:: BaseProtocol.resume_writing()
-
- Called when the transport's buffer drains below the low-water mark.
-
-
-:meth:`pause_writing` and :meth:`resume_writing` calls are paired --
-:meth:`pause_writing` is called once when the buffer goes strictly over
-the high-water mark (even if subsequent writes increases the buffer size
-even more), and eventually :meth:`resume_writing` is called once when the
-buffer size reaches the low-water mark.
-
-.. note::
- If the buffer size equals the high-water mark,
- :meth:`pause_writing` is not called -- it must go strictly over.
- Conversely, :meth:`resume_writing` is called when the buffer size is
- equal or lower than the low-water mark. These end conditions
- are important to ensure that things go as expected when either
- mark is zero.
-
-
-.. _transport:
-
-Transports
+Coroutines
----------
-Transports are classed provided by :mod:`asyncio` in order to abstract
-various kinds of communication channels. You generally won't instantiate
-a transport yourself; instead, you will call a :class:`BaseEventLoop` method
-which will create the transport and try to initiate the underlying
-communication channel, calling you back when it succeeds.
+A coroutine is a generator that follows certain conventions. For
+documentation purposes, all coroutines should be decorated with
+``@asyncio.coroutine``, but this cannot be strictly enforced.
-Once the communication channel is established, a transport is always
-paired with a :ref:`protocol <protocol>` instance. The protocol can
-then call the transport's methods for various purposes.
+Coroutines use the ``yield from`` syntax introduced in :pep:`380`,
+instead of the original ``yield`` syntax.
-:mod:`asyncio` currently implements transports for TCP, UDP, SSL, and
-subprocess pipes. The methods available on a transport depend on
-the transport's kind.
+The word "coroutine", like the word "generator", is used for two
+different (though related) concepts:
+- The function that defines a coroutine (a function definition
+ decorated with ``asyncio.coroutine``). If disambiguation is needed
+ we will call this a *coroutine function*.
-Methods common to all transports: BaseTransport
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- The object obtained by calling a coroutine function. This object
+ represents a computation or an I/O operation (usually a combination)
+ that will complete eventually. If disambiguation is needed we will
+ call it a *coroutine object*.
-.. class:: BaseTransport
+Things a coroutine can do:
- Base class for transports.
+- ``result = yield from future`` -- suspends the coroutine until the
+ future is done, then returns the future's result, or raises an
+ exception, which will be propagated. (If the future is cancelled,
+ it will raise a ``CancelledError`` exception.) Note that tasks are
+ futures, and everything said about futures also applies to tasks.
- .. method:: close(self)
+- ``result = yield from coroutine`` -- wait for another coroutine to
+ produce a result (or raise an exception, which will be propagated).
+ The ``coroutine`` expression must be a *call* to another coroutine.
- Close the transport. If the transport has a buffer for outgoing
- data, buffered data will be flushed asynchronously. No more data
- will be received. After all buffered data is flushed, the
- protocol's :meth:`connection_lost` method will be called with
- :const:`None` as its argument.
+- ``return expression`` -- produce a result to the coroutine that is
+ waiting for this one using ``yield from``.
+- ``raise exception`` -- raise an exception in the coroutine that is
+ waiting for this one using ``yield from``.
- .. method:: get_extra_info(name, default=None)
+Calling a coroutine does not start its code running -- it is just a
+generator, and the coroutine object returned by the call is really a
+generator object, which doesn't do anything until you iterate over it.
+In the case of a coroutine object, there are two basic ways to start
+it running: call ``yield from coroutine`` from another coroutine
+(assuming the other coroutine is already running!), or convert it to a
+:class:`Task`.
- Return optional transport information. *name* is a string representing
- the piece of transport-specific information to get, *default* is the
- value to return if the information doesn't exist.
+Coroutines (and tasks) can only run when the event loop is running.
- This method allows transport implementations to easily expose
- channel-specific information.
- * socket:
+Task
+----
- - ``'peername'``: the remote address to which the socket is connected,
- result of :meth:`socket.socket.getpeername` (``None`` on error)
- - ``'socket'``: :class:`socket.socket` instance
- - ``'sockname'``: the socket's own address,
- result of :meth:`socket.socket.getsockname`
+.. class:: Task(coro, \*, loop=None)
- * SSL socket:
+ A coroutine wrapped in a :class:`~concurrent.futures.Future`.
- - ``'compression'``: the compression algorithm being used as a string,
- or ``None`` if the connection isn't compressed; result of
- :meth:`ssl.SSLSocket.compression`
- - ``'cipher'``: a three-value tuple containing the name of the cipher
- being used, the version of the SSL protocol that defines its use, and
- the number of secret bits being used; result of
- :meth:`ssl.SSLSocket.cipher`
- - ``'peercert'``: peer certificate; result of
- :meth:`ssl.SSLSocket.getpeercert`
- - ``'sslcontext'``: :class:`ssl.SSLContext` instance
+ .. classmethod:: all_tasks(loop=None)
- * pipe:
+ Return a set of all tasks for an event loop.
- - ``'pipe'``: pipe object
+ By default all tasks for the current event loop are returned.
- * subprocess:
+ .. method:: cancel()
- - ``'subprocess'``: :class:`subprocess.Popen` instance
+ Cancel the task.
+ .. method:: get_stack(self, \*, limit=None)
-Methods of readable streaming transports: ReadTransport
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ Return the list of stack frames for this task's coroutine.
-.. class:: ReadTransport
+ If the coroutine is active, this returns the stack where it is suspended.
+ If the coroutine has completed successfully or was cancelled, this
+ returns an empty list. If the coroutine was terminated by an exception,
+ this returns the list of traceback frames.
- Interface for read-only transports.
+ The frames are always ordered from oldest to newest.
- .. method:: pause_reading()
+ The optional limit gives the maximum nummber of frames to return; by
+ default all available frames are returned. Its meaning differs depending
+ on whether a stack or a traceback is returned: the newest frames of a
+ stack are returned, but the oldest frames of a traceback are returned.
+ (This matches the behavior of the traceback module.)
- Pause the receiving end of the transport. No data will be passed to
- the protocol's :meth:`data_received` method until meth:`resume_reading`
- is called.
+ For reasons beyond our control, only one stack frame is returned for a
+ suspended coroutine.
- .. method:: resume_reading()
+ .. method:: print_stack(\*, limit=None, file=None)
- Resume the receiving end. The protocol's :meth:`data_received` method
- will be called once again if some data is available for reading.
+ Print the stack or traceback for this task's coroutine.
-
-Methods of writable streaming transports: WriteTransport
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. class:: WriteTransport
-
- Interface for write-only transports.
-
- .. method:: write(data)
-
- Write some *data* bytes to the transport.
-
- This method does not block; it buffers the data and arranges for it
- to be sent out asynchronously.
-
- .. method:: writelines(list_of_data)
-
- Write a list (or any iterable) of data bytes to the transport.
- This is functionally equivalent to calling :meth:`write` on each
- element yielded by the iterable, but may be implemented more efficiently.
-
- .. method:: write_eof()
-
- Close the write end of the transport after flushing buffered data.
- Data may still be received.
-
- This method can raise :exc:`NotImplementedError` if the transport
- (e.g. SSL) doesn't support half-closes.
-
- .. method:: can_write_eof()
-
- Return :const:`True` if the transport supports :meth:`write_eof`,
- :const:`False` if not.
-
- .. method:: abort()
-
- Close the transport immediately, without waiting for pending operations
- to complete. Buffered data will be lost. No more data will be received.
- The protocol's :meth:`connection_lost` method will eventually be
- called with :const:`None` as its argument.
-
- .. method:: set_write_buffer_limits(high=None, low=None)
-
- Set the *high*- and *low*-water limits for write flow control.
-
- These two values control when call the protocol's
- :meth:`pause_writing` and :meth:`resume_writing` methods are called.
- If specified, the low-water limit must be less than or equal to the
- high-water limit. Neither *high* nor *low* can be negative.
-
- The defaults are implementation-specific. If only the
- high-water limit is given, the low-water limit defaults to a
- implementation-specific value less than or equal to the
- high-water limit. Setting *high* to zero forces *low* to zero as
- well, and causes :meth:`pause_writing` to be called whenever the
- buffer becomes non-empty. Setting *low* to zero causes
- :meth:`resume_writing` to be called only once the buffer is empty.
- Use of zero for either limit is generally sub-optimal as it
- reduces opportunities for doing I/O and computation
- concurrently.
-
- .. method:: get_write_buffer_size()
-
- Return the current size of the output buffer used by the transport.
-
-
-Methods of datagram transports
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. method:: DatagramTransport.sendto(data, addr=None)
-
- Send the *data* bytes to the remote peer given by *addr* (a
- transport-dependent target address). If *addr* is :const:`None`, the
- data is sent to the target address given on transport creation.
-
- This method does not block; it buffers the data and arranges for it
- to be sent out asynchronously.
-
-.. method:: DatagramTransport.abort()
-
- Close the transport immediately, without waiting for pending operations
- to complete. Buffered data will be lost. No more data will be received.
- The protocol's :meth:`connection_lost` method will eventually be
- called with :const:`None` as its argument.
-
-
-Methods of subprocess transports
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-.. class:: BaseSubprocessTransport
-
- .. method:: get_pid()
-
- Return the subprocess process id as an integer.
-
- .. method:: get_returncode()
-
- Return the subprocess returncode as an integer or :const:`None`
- if it hasn't returned, similarly to the
- :attr:`subprocess.Popen.returncode` attribute.
-
- .. method:: get_pipe_transport(fd)
-
- Return the transport for the communication pipe correspondong to the
- integer file descriptor *fd*. The return value can be a readable or
- writable streaming transport, depending on the *fd*. If *fd* doesn't
- correspond to a pipe belonging to this transport, :const:`None` is
- returned.
-
- .. method:: send_signal(signal)
-
- Send the *signal* number to the subprocess, as in
- :meth:`subprocess.Popen.send_signal`.
-
- .. method:: terminate()
-
- Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`.
- This method is an alias for the :meth:`close` method.
-
- On POSIX systems, this method sends SIGTERM to the subprocess.
- On Windows, the Windows API function TerminateProcess() is called to
- stop the subprocess.
-
- .. method:: kill(self)
-
- Kill the subprocess, as in :meth:`subprocess.Popen.kill`
-
- On POSIX systems, the function sends SIGKILL to the subprocess.
- On Windows, this method is an alias for :meth:`terminate`.
+ This produces output similar to that of the traceback module, for the
+ frames retrieved by get_stack(). The limit argument is passed to
+ get_stack(). The file argument is an I/O stream to which the output
+ goes; by default it goes to sys.stderr.
Task functions
@@ -965,71 +611,228 @@
the timeout occurs are returned in the second set.
-Task
-----
+.. _transport:
-.. class:: Task(coro, \*, loop=None)
+Transports
+----------
- A coroutine wrapped in a :class:`~concurrent.futures.Future`.
+Transports are classed provided by :mod:`asyncio` in order to abstract
+various kinds of communication channels. You generally won't instantiate
+a transport yourself; instead, you will call a :class:`BaseEventLoop` method
+which will create the transport and try to initiate the underlying
+communication channel, calling you back when it succeeds.
- .. classmethod:: all_tasks(loop=None)
+Once the communication channel is established, a transport is always
+paired with a :ref:`protocol <protocol>` instance. The protocol can
+then call the transport's methods for various purposes.
- Return a set of all tasks for an event loop.
+:mod:`asyncio` currently implements transports for TCP, UDP, SSL, and
+subprocess pipes. The methods available on a transport depend on
+the transport's kind.
- By default all tasks for the current event loop are returned.
- .. method:: cancel()
+Methods common to all transports: BaseTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Cancel the task.
+.. class:: BaseTransport
- .. method:: get_stack(self, \*, limit=None)
+ Base class for transports.
- Return the list of stack frames for this task's coroutine.
+ .. method:: close(self)
- If the coroutine is active, this returns the stack where it is suspended.
- If the coroutine has completed successfully or was cancelled, this
- returns an empty list. If the coroutine was terminated by an exception,
- this returns the list of traceback frames.
+ Close the transport. If the transport has a buffer for outgoing
+ data, buffered data will be flushed asynchronously. No more data
+ will be received. After all buffered data is flushed, the
+ protocol's :meth:`connection_lost` method will be called with
+ :const:`None` as its argument.
- The frames are always ordered from oldest to newest.
- The optional limit gives the maximum nummber of frames to return; by
- default all available frames are returned. Its meaning differs depending
- on whether a stack or a traceback is returned: the newest frames of a
- stack are returned, but the oldest frames of a traceback are returned.
- (This matches the behavior of the traceback module.)
+ .. method:: get_extra_info(name, default=None)
- For reasons beyond our control, only one stack frame is returned for a
- suspended coroutine.
+ Return optional transport information. *name* is a string representing
+ the piece of transport-specific information to get, *default* is the
+ value to return if the information doesn't exist.
- .. method:: print_stack(\*, limit=None, file=None)
+ This method allows transport implementations to easily expose
+ channel-specific information.
- Print the stack or traceback for this task's coroutine.
+ * socket:
- This produces output similar to that of the traceback module, for the
- frames retrieved by get_stack(). The limit argument is passed to
- get_stack(). The file argument is an I/O stream to which the output
- goes; by default it goes to sys.stderr.
+ - ``'peername'``: the remote address to which the socket is connected,
+ result of :meth:`socket.socket.getpeername` (``None`` on error)
+ - ``'socket'``: :class:`socket.socket` instance
+ - ``'sockname'``: the socket's own address,
+ result of :meth:`socket.socket.getsockname`
+ * SSL socket:
-Protocols
----------
+ - ``'compression'``: the compression algorithm being used as a string,
+ or ``None`` if the connection isn't compressed; result of
+ :meth:`ssl.SSLSocket.compression`
+ - ``'cipher'``: a three-value tuple containing the name of the cipher
+ being used, the version of the SSL protocol that defines its use, and
+ the number of secret bits being used; result of
+ :meth:`ssl.SSLSocket.cipher`
+ - ``'peercert'``: peer certificate; result of
+ :meth:`ssl.SSLSocket.getpeercert`
+ - ``'sslcontext'``: :class:`ssl.SSLContext` instance
-:mod:`asyncio` provides base classes that you can subclass to implement
-your network protocols. Those classes are used in conjunction with
-:ref:`transports <transport>` (see below): the protocol parses incoming
-data and asks for the writing of outgoing data, while the transport is
-responsible for the actual I/O and buffering.
+ * pipe:
-When subclassing a protocol class, it is recommended you override certain
-methods. Those methods are callbacks: they will be called by the transport
-on certain events (for example when some data is received); you shouldn't
-call them yourself, unless you are implementing a transport.
+ - ``'pipe'``: pipe object
-.. note::
- All callbacks have default implementations, which are empty. Therefore,
- you only need to implement the callbacks for the events in which you
- are interested.
+ * subprocess:
+
+ - ``'subprocess'``: :class:`subprocess.Popen` instance
+
+
+Methods of readable streaming transports: ReadTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: ReadTransport
+
+ Interface for read-only transports.
+
+ .. method:: pause_reading()
+
+ Pause the receiving end of the transport. No data will be passed to
+ the protocol's :meth:`data_received` method until meth:`resume_reading`
+ is called.
+
+ .. method:: resume_reading()
+
+ Resume the receiving end. The protocol's :meth:`data_received` method
+ will be called once again if some data is available for reading.
+
+
+Methods of writable streaming transports: WriteTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: WriteTransport
+
+ Interface for write-only transports.
+
+ .. method:: abort()
+
+ Close the transport immediately, without waiting for pending operations
+ to complete. Buffered data will be lost. No more data will be received.
+ The protocol's :meth:`connection_lost` method will eventually be
+ called with :const:`None` as its argument.
+
+ .. method:: can_write_eof()
+
+ Return :const:`True` if the transport supports :meth:`write_eof`,
+ :const:`False` if not.
+
+ .. method:: get_write_buffer_size()
+
+ Return the current size of the output buffer used by the transport.
+
+ .. method:: set_write_buffer_limits(high=None, low=None)
+
+ Set the *high*- and *low*-water limits for write flow control.
+
+ These two values control when call the protocol's
+ :meth:`pause_writing` and :meth:`resume_writing` methods are called.
+ If specified, the low-water limit must be less than or equal to the
+ high-water limit. Neither *high* nor *low* can be negative.
+
+ The defaults are implementation-specific. If only the
+ high-water limit is given, the low-water limit defaults to a
+ implementation-specific value less than or equal to the
+ high-water limit. Setting *high* to zero forces *low* to zero as
+ well, and causes :meth:`pause_writing` to be called whenever the
+ buffer becomes non-empty. Setting *low* to zero causes
+ :meth:`resume_writing` to be called only once the buffer is empty.
+ Use of zero for either limit is generally sub-optimal as it
+ reduces opportunities for doing I/O and computation
+ concurrently.
+
+ .. method:: write(data)
+
+ Write some *data* bytes to the transport.
+
+ This method does not block; it buffers the data and arranges for it
+ to be sent out asynchronously.
+
+ .. method:: writelines(list_of_data)
+
+ Write a list (or any iterable) of data bytes to the transport.
+ This is functionally equivalent to calling :meth:`write` on each
+ element yielded by the iterable, but may be implemented more efficiently.
+
+ .. method:: write_eof()
+
+ Close the write end of the transport after flushing buffered data.
+ Data may still be received.
+
+ This method can raise :exc:`NotImplementedError` if the transport
+ (e.g. SSL) doesn't support half-closes.
+
+
+Methods of datagram transports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. method:: DatagramTransport.sendto(data, addr=None)
+
+ Send the *data* bytes to the remote peer given by *addr* (a
+ transport-dependent target address). If *addr* is :const:`None`, the
+ data is sent to the target address given on transport creation.
+
+ This method does not block; it buffers the data and arranges for it
+ to be sent out asynchronously.
+
+.. method:: DatagramTransport.abort()
+
+ Close the transport immediately, without waiting for pending operations
+ to complete. Buffered data will be lost. No more data will be received.
+ The protocol's :meth:`connection_lost` method will eventually be
+ called with :const:`None` as its argument.
+
+
+Methods of subprocess transports
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. class:: BaseSubprocessTransport
+
+ .. method:: get_pid()
+
+ Return the subprocess process id as an integer.
+
+ .. method:: get_returncode()
+
+ Return the subprocess returncode as an integer or :const:`None`
+ if it hasn't returned, similarly to the
+ :attr:`subprocess.Popen.returncode` attribute.
+
+ .. method:: get_pipe_transport(fd)
+
+ Return the transport for the communication pipe correspondong to the
+ integer file descriptor *fd*. The return value can be a readable or
+ writable streaming transport, depending on the *fd*. If *fd* doesn't
+ correspond to a pipe belonging to this transport, :const:`None` is
+ returned.
+
+ .. method:: send_signal(signal)
+
+ Send the *signal* number to the subprocess, as in
+ :meth:`subprocess.Popen.send_signal`.
+
+ .. method:: terminate()
+
+ Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`.
+ This method is an alias for the :meth:`close` method.
+
+ On POSIX systems, this method sends SIGTERM to the subprocess.
+ On Windows, the Windows API function TerminateProcess() is called to
+ stop the subprocess.
+
+ .. method:: kill(self)
+
+ Kill the subprocess, as in :meth:`subprocess.Popen.kill`
+
+ On POSIX systems, the function sends SIGKILL to the subprocess.
+ On Windows, this method is an alias for :meth:`terminate`.
Stream reader and writer
@@ -1136,57 +939,202 @@
-.. _coroutine:
+.. _protocol:
-Coroutines
-----------
+Protocols
+---------
-A coroutine is a generator that follows certain conventions. For
-documentation purposes, all coroutines should be decorated with
-``@asyncio.coroutine``, but this cannot be strictly enforced.
+:mod:`asyncio` provides base classes that you can subclass to implement
+your network protocols. Those classes are used in conjunction with
+:ref:`transports <transport>` (see below): the protocol parses incoming
+data and asks for the writing of outgoing data, while the transport is
+responsible for the actual I/O and buffering.
-Coroutines use the ``yield from`` syntax introduced in :pep:`380`,
-instead of the original ``yield`` syntax.
+When subclassing a protocol class, it is recommended you override certain
+methods. Those methods are callbacks: they will be called by the transport
+on certain events (for example when some data is received); you shouldn't
+call them yourself, unless you are implementing a transport.
-The word "coroutine", like the word "generator", is used for two
-different (though related) concepts:
+.. note::
+ All callbacks have default implementations, which are empty. Therefore,
+ you only need to implement the callbacks for the events in which you
+ are interested.
-- The function that defines a coroutine (a function definition
- decorated with ``asyncio.coroutine``). If disambiguation is needed
- we will call this a *coroutine function*.
-- The object obtained by calling a coroutine function. This object
- represents a computation or an I/O operation (usually a combination)
- that will complete eventually. If disambiguation is needed we will
- call it a *coroutine object*.
+Protocol classes
+^^^^^^^^^^^^^^^^
-Things a coroutine can do:
+.. class:: Protocol
-- ``result = yield from future`` -- suspends the coroutine until the
- future is done, then returns the future's result, or raises an
- exception, which will be propagated. (If the future is cancelled,
- it will raise a ``CancelledError`` exception.) Note that tasks are
- futures, and everything said about futures also applies to tasks.
+ The base class for implementing streaming protocols (for use with
+ e.g. TCP and SSL transports).
-- ``result = yield from coroutine`` -- wait for another coroutine to
- produce a result (or raise an exception, which will be propagated).
- The ``coroutine`` expression must be a *call* to another coroutine.
+.. class:: DatagramProtocol
-- ``return expression`` -- produce a result to the coroutine that is
- waiting for this one using ``yield from``.
+ The base class for implementing datagram protocols (for use with
+ e.g. UDP transports).
-- ``raise exception`` -- raise an exception in the coroutine that is
- waiting for this one using ``yield from``.
+.. class:: SubprocessProtocol
-Calling a coroutine does not start its code running -- it is just a
-generator, and the coroutine object returned by the call is really a
-generator object, which doesn't do anything until you iterate over it.
-In the case of a coroutine object, there are two basic ways to start
-it running: call ``yield from coroutine`` from another coroutine
-(assuming the other coroutine is already running!), or convert it to a
-:class:`Task`.
+ The base class for implementing protocols communicating with child
+ processes (through a set of unidirectional pipes).
-Coroutines (and tasks) can only run when the event loop is running.
+
+Connection callbacks
+^^^^^^^^^^^^^^^^^^^^
+
+These callbacks may be called on :class:`Protocol` and
+:class:`SubprocessProtocol` instances:
+
+.. method:: BaseProtocol.connection_made(transport)
+
+ Called when a connection is made.
+
+ The *transport* argument is the transport representing the
+ connection. You are responsible for storing it somewhere
+ (e.g. as an attribute) if you need to.
+
+.. method:: BaseProtocol.connection_lost(exc)
+
+ Called when the connection is lost or closed.
+
+ The argument is either an exception object or :const:`None`.
+ The latter means a regular EOF is received, or the connection was
+ aborted or closed by this side of the connection.
+
+:meth:`connection_made` and :meth:`connection_lost` are called exactly once
+per successful connection. All other callbacks will be called between those
+two methods, which allows for easier resource management in your protocol
+implementation.
+
+The following callbacks may be called only on :class:`SubprocessProtocol`
+instances:
+
+.. method:: SubprocessProtocol.pipe_data_received(fd, data)
+
+ Called when the child process writes data into its stdout or stderr pipe.
+ *fd* is the integer file descriptor of the pipe. *data* is a non-empty
+ bytes object containing the data.
+
+.. method:: SubprocessProtocol.pipe_connection_lost(fd, exc)
+
+ Called when one of the pipes communicating with the child process
+ is closed. *fd* is the integer file descriptor that was closed.
+
+.. method:: SubprocessProtocol.process_exited()
+
+ Called when the child process has exited.
+
+
+Data reception callbacks
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+Streaming protocols
+"""""""""""""""""""
+
+The following callbacks are called on :class:`Protocol` instances:
+
+.. method:: Protocol.data_received(data)
+
+ Called when some data is received. *data* is a non-empty bytes object
+ containing the incoming data.
+
+ .. note::
+ Whether the data is buffered, chunked or reassembled depends on
+ the transport. In general, you shouldn't rely on specific semantics
+ and instead make your parsing generic and flexible enough. However,
+ data is always received in the correct order.
+
+.. method:: Protocol.eof_received()
+
+ Calls when the other end signals it won't send any more data
+ (for example by calling :meth:`write_eof`, if the other end also uses
+ asyncio).
+
+ This method may return a false value (including None), in which case
+ the transport will close itself. Conversely, if this method returns a
+ true value, closing the transport is up to the protocol. Since the
+ default implementation returns None, it implicitly closes the connection.
+
+ .. note::
+ Some transports such as SSL don't support half-closed connections,
+ in which case returning true from this method will not prevent closing
+ the connection.
+
+:meth:`data_received` can be called an arbitrary number of times during
+a connection. However, :meth:`eof_received` is called at most once
+and, if called, :meth:`data_received` won't be called after it.
+
+Datagram protocols
+""""""""""""""""""
+
+The following callbacks are called on :class:`DatagramProtocol` instances.
+
+.. method:: DatagramProtocol.datagram_received(data, addr)
+
+ Called when a datagram is received. *data* is a bytes object containing
+ the incoming data. *addr* is the address of the peer sending the data;
+ the exact format depends on the transport.
+
+.. method:: DatagramProtocol.error_received(exc)
+
+ Called when a previous send or receive operation raises an
+ :class:`OSError`. *exc* is the :class:`OSError` instance.
+
+ This method is called in rare conditions, when the transport (e.g. UDP)
+ detects that a datagram couldn't be delivered to its recipient.
+ In many conditions though, undeliverable datagrams will be silently
+ dropped.
+
+
+Flow control callbacks
+^^^^^^^^^^^^^^^^^^^^^^
+
+These callbacks may be called on :class:`Protocol` and
+:class:`SubprocessProtocol` instances:
+
+.. method:: BaseProtocol.pause_writing()
+
+ Called when the transport's buffer goes over the high-water mark.
+
+.. method:: BaseProtocol.resume_writing()
+
+ Called when the transport's buffer drains below the low-water mark.
+
+
+:meth:`pause_writing` and :meth:`resume_writing` calls are paired --
+:meth:`pause_writing` is called once when the buffer goes strictly over
+the high-water mark (even if subsequent writes increases the buffer size
+even more), and eventually :meth:`resume_writing` is called once when the
+buffer size reaches the low-water mark.
+
+.. note::
+ If the buffer size equals the high-water mark,
+ :meth:`pause_writing` is not called -- it must go strictly over.
+ Conversely, :meth:`resume_writing` is called when the buffer size is
+ equal or lower than the low-water mark. These end conditions
+ are important to ensure that things go as expected when either
+ mark is zero.
+
+
+Protocols
+---------
+
+:mod:`asyncio` provides base classes that you can subclass to implement
+your network protocols. Those classes are used in conjunction with
+:ref:`transports <transport>` (see below): the protocol parses incoming
+data and asks for the writing of outgoing data, while the transport is
+responsible for the actual I/O and buffering.
+
+When subclassing a protocol class, it is recommended you override certain
+methods. Those methods are callbacks: they will be called by the transport
+on certain events (for example when some data is received); you shouldn't
+call them yourself, unless you are implementing a transport.
+
+.. note::
+ All callbacks have default implementations, which are empty. Therefore,
+ you only need to implement the callbacks for the events in which you
+ are interested.
Server
@@ -1205,6 +1153,58 @@
Coroutine to wait until service is closed.
+Network functions
+-----------------
+
+.. function:: open_connection(host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+ A wrapper for create_connection() returning a (reader, writer) pair.
+
+ The reader returned is a StreamReader instance; the writer is a
+ :class:`Transport`.
+
+ The arguments are all the usual arguments to
+ :meth:`BaseEventLoop.create_connection` except *protocol_factory*; most
+ common are positional host and port, with various optional keyword arguments
+ following.
+
+ Additional optional keyword arguments are *loop* (to set the event loop
+ instance to use) and *limit* (to set the buffer limit passed to the
+ StreamReader).
+
+ (If you want to customize the :class:`StreamReader` and/or
+ :class:`StreamReaderProtocol` classes, just copy the code -- there's really
+ nothing special here except some convenience.)
+
+ This function returns a :ref:`coroutine <coroutine>`.
+
+.. function:: start_server(client_connected_cb, host=None, port=None, *, loop=None, limit=_DEFAULT_LIMIT, **kwds)
+
+ Start a socket server, call back for each client connected.
+
+ The first parameter, *client_connected_cb*, takes two parameters:
+ *client_reader*, *client_writer*. *client_reader* is a
+ :class:`StreamReader` object, while *client_writer* is a
+ :class:`StreamWriter` object. This parameter can either be a plain callback
+ function or a :ref:`coroutine <coroutine>`; if it is a coroutine, it will be
+ automatically converted into a :class:`Task`.
+
+ The rest of the arguments are all the usual arguments to
+ :meth:`~BaseEventLoop.create_server()` except *protocol_factory*; most
+ common are positional host and port, with various optional keyword arguments
+ following. The return value is the same as
+ :meth:`~BaseEventLoop.create_server()`.
+
+ Additional optional keyword arguments are *loop* (to set the event loop
+ instance to use) and *limit* (to set the buffer limit passed to the
+ :class:`StreamReader`).
+
+ The return value is the same as :meth:`~BaseEventLoop.create_server()`, i.e.
+ a :class:`AbstractServer` object which can be used to stop the service.
+
+ This function returns a :ref:`coroutine <coroutine>`.
+
+
.. _sync:
Synchronization primitives
--
Repository URL: http://hg.python.org/cpython
More information about the Python-checkins
mailing list