Issue #22564: ssl doc: reorganize and reindent documentation of SSLObject and

MemoryBIO; move documentation of SSLContext.wrap_bio()

diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index 9aa30211e8a94d947b443aa22f9375ca31b9dcb4..ed966ee01bc0cee257dab79b304eb7055a5babe3 100644 (file)
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1269,6 +1269,16 @@ to speed up repeated connections from the same clients.
    *server_hostname* will also raise a :exc:`ValueError` if *server_side*
    is true.
 
+.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
+                                server_hostname=None)
+
+   Create a new :class:`SSLObject` instance by wrapping the BIO objects
+   *incoming* and *outgoing*. The SSL routines will read input data from the
+   incoming BIO and write data to the outgoing BIO.
+
+   The *server_side* and *server_hostname* parameters have the same meaning as
+   in :meth:`SSLContext.wrap_socket`.
+
 .. method:: SSLContext.session_stats()
 
    Get statistics about the SSL sessions created or managed by this context.
@@ -1768,78 +1778,31 @@ provided.
    A reduced-scope variant of :class:`SSLSocket` representing an SSL protocol
    instance that does not contain any network IO methods.
 
-The following methods are available from :class:`SSLSocket`:
-
-- :attr:`~SSLSocket.context`
-- :attr:`~SSLSocket.server_side`
-- :attr:`~SSLSocket.server_hostname`
-- :meth:`~SSLSocket.read`
-- :meth:`~SSLSocket.write`
-- :meth:`~SSLSocket.getpeercert`
-- :meth:`~SSLSocket.selected_npn_protocol`
-- :meth:`~SSLSocket.cipher`
-- :meth:`~SSLSocket.compression`
-- :meth:`~SSLSocket.pending`
-- :meth:`~SSLSocket.do_handshake`
-- :meth:`~SSLSocket.unwrap`
-- :meth:`~SSLSocket.get_channel_binding`
-
-An SSLObject communicates with the outside world using memory buffers. The
-class :class:`MemoryBIO` provides a memory buffer that can be used for this
-purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:
-
-.. class:: MemoryBIO
-
-   A memory buffer that can be used to pass data between Python and an SSL
-   protocol instance.
-
-.. attribute:: MemoryBIO.pending
-
-   Return the number of bytes currently in the memory buffer.
-
-.. attribute:: MemoryBIO.eof
-
-   A boolean indicating whether the memory BIO is current at the end-of-file
-   position.
-
-.. method:: MemoryBIO.read(n=-1)
-
-   Read up to *n* bytes from the memory buffer. If *n* is not specified or
-   negative, all bytes are returned.
-
-.. method:: MemoryBIO.write(buf)
-
-   Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
-   object supporting the buffer protocol.
-
-   The return value is the number of bytes written, which is always equal to
-   the length of *buf*.
-
-.. method:: MemoryBIO.write_eof()
-
-   Write an EOF marker to the memory BIO. After this method has been called, it
-   is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will
-   become true after all data currently in the buffer has been read.
-
-An :class:`SSLObject` instance can be created using the
-:meth:`~SSLContext.wrap_bio` method. This method will create the
-:class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming* BIO
-is used to pass data from Python to the SSL protocol instance, while the
-*outgoing* BIO is used to pass data the other way around.
-
-.. method:: SSLContext.wrap_bio(incoming, outgoing, server_side=False, \
-                                server_hostname=None)
-
-   Create a new :class:`SSLObject` instance by wrapping the BIO objects
-   *incoming* and *outgoing*. The SSL routines will read input data from the
-   incoming BIO and write data to the outgoing BIO.
-
-   The *server_side* and *server_hostname* parameters have the same meaning as
-   in :meth:`SSLContext.wrap_socket`.
+   The following methods are available from :class:`SSLSocket`:
+
+   - :attr:`~SSLSocket.context`
+   - :attr:`~SSLSocket.server_side`
+   - :attr:`~SSLSocket.server_hostname`
+   - :meth:`~SSLSocket.read`
+   - :meth:`~SSLSocket.write`
+   - :meth:`~SSLSocket.getpeercert`
+   - :meth:`~SSLSocket.selected_npn_protocol`
+   - :meth:`~SSLSocket.cipher`
+   - :meth:`~SSLSocket.compression`
+   - :meth:`~SSLSocket.pending`
+   - :meth:`~SSLSocket.do_handshake`
+   - :meth:`~SSLSocket.unwrap`
+   - :meth:`~SSLSocket.get_channel_binding`
+
+   An :class:`SSLObject` instance can be created using the
+   :meth:`~SSLContext.wrap_bio` method. This method will create the
+   :class:`SSLObject` instance and bind it to a pair of BIOs. The *incoming* BIO
+   is used to pass data from Python to the SSL protocol instance, while the
+   *outgoing* BIO is used to pass data the other way around.
 
 Some notes related to the use of :class:`SSLObject`:
 
-- All IO on an :class:`SSLObject` is non-blocking. This means that for example
+- All I/O on an :class:`SSLObject` is non-blocking. This means that for example
   :meth:`~SSLSocket.read` will raise an :exc:`SSLWantReadError` if it needs
   more data than the incoming BIO has available.
 
@@ -1861,6 +1824,43 @@ Some notes related to the use of :class:`SSLObject`:
   :meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject`
   instance instead of a :class:`SSLSocket` instance as its first parameter.
 
+An SSLObject communicates with the outside world using memory buffers. The
+class :class:`MemoryBIO` provides a memory buffer that can be used for this
+purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:
+
+.. class:: MemoryBIO
+
+   A memory buffer that can be used to pass data between Python and an SSL
+   protocol instance.
+
+   .. attribute:: MemoryBIO.pending
+
+      Return the number of bytes currently in the memory buffer.
+
+   .. attribute:: MemoryBIO.eof
+
+      A boolean indicating whether the memory BIO is current at the end-of-file
+      position.
+
+   .. method:: MemoryBIO.read(n=-1)
+
+      Read up to *n* bytes from the memory buffer. If *n* is not specified or
+      negative, all bytes are returned.
+
+   .. method:: MemoryBIO.write(buf)
+
+      Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
+      object supporting the buffer protocol.
+
+      The return value is the number of bytes written, which is always equal to
+      the length of *buf*.
+
+   .. method:: MemoryBIO.write_eof()
+
+      Write an EOF marker to the memory BIO. After this method has been called, it
+      is illegal to call :meth:`~MemoryBIO.write`. The attribute :attr:`eof` will
+      become true after all data currently in the buffer has been read.
+
 
 .. _ssl-security: