asyncio doc: group transport method by classes

Declare classes because they are mentionned in documentation of other functions

1 files changed, 113 insertions, 94 deletions

diff --git a/Doc/library/asyncio.rst b/Doc/library/asyncio.rst
index c66da12..ba5f6b1 100644
--- a/Doc/library/asyncio.rst
+++ b/Doc/library/asyncio.rst
@@ -633,100 +633,116 @@ then call the transport's methods for various purposes.
 subprocess pipes.  The methods available on a transport depend on
 the transport's kind.
 
-Methods common to all transports
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. method:: BaseTransport.close(self)
+Methods common to all transports: BaseTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   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.
+.. class:: BaseTransport
 
+   Base class for transports.
 
-.. method:: BaseTransport.get_extra_info(name, default=None)
+   .. method:: close(self)
 
-   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.
+      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.
 
-   This method allows transport implementations to easily expose
-   channel-specific information.
 
-Methods of readable streaming transports
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   .. method:: get_extra_info(name, default=None)
 
-.. method:: ReadTransport.pause_reading()
+      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.
 
-   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.
+      This method allows transport implementations to easily expose
+      channel-specific information.
 
-.. method:: ReadTransport.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 readable streaming transports: ReadTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Methods of writable streaming transports
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+.. class:: ReadTransport
 
-.. method:: WriteTransport.write(data)
+   Interface for read-only transports.
 
-   Write some *data* bytes to the transport.
+   .. method:: pause_reading()
 
-   This method does not block; it buffers the data and arranges for it
-   to be sent out asynchronously.
+      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:: WriteTransport.writelines(list_of_data)
+   .. method:: resume_reading()
 
-   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.
+      Resume the receiving end.  The protocol's :meth:`data_received` method
+      will be called once again if some data is available for reading.
 
-.. method:: WriteTransport.write_eof()
 
-   Close the write end of the transport after flushing buffered data.
-   Data may still be received.
+Methods of writable streaming transports: WriteTransport
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-   This method can raise :exc:`NotImplementedError` if the transport
-   (e.g. SSL) doesn't support half-closes.
+.. class:: WriteTransport
 
-.. method:: WriteTransport.can_write_eof()
+   Interface for write-only transports.
 
-   Return :const:`True` if the transport supports :meth:`write_eof`,
-   :const:`False` if not.
+   .. method:: write(data)
 
-.. method:: WriteTransport.abort()
+      Write some *data* bytes to the transport.
 
-   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.
+      This method does not block; it buffers the data and arranges for it
+      to be sent out asynchronously.
 
-.. method:: WriteTransport.set_write_buffer_limits(high=None, low=None)
+   .. method:: writelines(list_of_data)
 
-   Set the *high*- and *low*-water limits for write flow control.
+      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.
 
-   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.
+   .. method:: write_eof()
+
+      Close the write end of the transport after flushing buffered data.
+      Data may still be received.
 
-   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.
+      This method can raise :exc:`NotImplementedError` if the transport
+      (e.g. SSL) doesn't support half-closes.
 
-.. method:: WriteTransport.get_write_buffer_size()
+   .. 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.
 
-   Return the current size of the output buffer used by the transport.
 
 Methods of datagram transports
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -747,47 +763,50 @@ Methods of datagram transports
    The protocol's :meth:`connection_lost` method will eventually be
    called with :const:`None` as its argument.
 
+
 Methods of subprocess transports
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. method:: BaseSubprocessTransport.get_pid()
+.. class:: BaseSubprocessTransport
+
+   .. method:: get_pid()
 
-   Return the subprocess process id as an integer.
+      Return the subprocess process id as an integer.
 
-.. method:: BaseSubprocessTransport.get_returncode()
+   .. 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.
+      Return the subprocess returncode as an integer or :const:`None`
+      if it hasn't returned, similarly to the
+      :attr:`subprocess.Popen.returncode` attribute.
 
-.. method:: BaseSubprocessTransport.get_pipe_transport(fd)
+   .. 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.
+      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:: BaseSubprocessTransport.send_signal(signal)
+   .. method:: send_signal(signal)
 
-   Send the *signal* number to the subprocess, as in
-   :meth:`subprocess.Popen.send_signal`.
+      Send the *signal* number to the subprocess, as in
+      :meth:`subprocess.Popen.send_signal`.
 
-.. method:: BaseSubprocessTransport.terminate()
+   .. method:: terminate()
 
-   Ask the subprocess to stop, as in :meth:`subprocess.Popen.terminate`.
-   This method is an alias for the :meth:`close` method.
+      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.
+      On POSIX systems, this method sends SIGTERM to the subprocess.
+      On Windows, the Windows API function TerminateProcess() is called to
+      stop the subprocess.
 
-.. method:: BaseSubprocessTransport.kill(self)
+   .. method:: kill(self)
 
-   Kill the subprocess, as in :meth:`subprocess.Popen.kill`
+      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`.
+      On POSIX systems, the function sends SIGKILL to the subprocess.
+      On Windows, this method is an alias for :meth:`terminate`.
 
 
 Task functions
@@ -843,12 +862,12 @@ Task functions
 
    Return ``True`` if *obj* is a coroutine object.
 
-.. function:: sleep(delay, result=None, *, loop=None)
+.. function:: sleep(delay, result=None, \*, loop=None)
 
    Create a :ref:`coroutine <coroutine>` that completes after a given time
    (in seconds).
 
-.. function:: shield(arg, *, loop=None)
+.. function:: shield(arg, \*, loop=None)
 
    Wait for a future, shielding it from cancellation.
 
@@ -879,7 +898,7 @@ Task functions
 Task
 ----
 
-.. class:: Task(coro, *, loop=None)
+.. class:: Task(coro, \*, loop=None)
 
    A coroutine wrapped in a :class:`~concurrent.futures.Future`.
 
@@ -893,7 +912,7 @@ Task
 
       Cancel the task.
 
-   .. method:: get_stack(self, *, limit=None)
+   .. method:: get_stack(self, \*, limit=None)
 
       Return the list of stack frames for this task's coroutine.
 
@@ -913,7 +932,7 @@ Task
       For reasons beyond our control, only one stack frame is returned for a
       suspended coroutine.
 
-   .. method:: print_stack(*, limit=None, file=None)
+   .. method:: print_stack(\*, limit=None, file=None)
 
       Print the stack or traceback for this task's coroutine.