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

MemoryBIO; move documentation of SSLContext.wrap_bio()

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.
@@ -1784,6 +1794,36 @@ The following methods are available from :class:`SSLSocket`:
    - :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 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.
+
+- There is no module-level ``wrap_bio`` call like there is for
+  :meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created via
+  an :class:`SSLContext`.
+
+- There is no *do_handshake_on_connect* machinery. You must always manually
+  call :meth:`~SSLSocket.do_handshake` to start the handshake.
+
+- There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
+  that are in violation of the protocol are reported via the :exc:`SSLEOFError`
+  exception.
+
+- The method :meth:`~SSLSocket.unwrap` call does not return anything, unlike
+  for an SSL socket where it returns the underlying socket.
+
+- The *server_name_callback* callback passed to
+  :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:
@@ -1821,46 +1861,6 @@ purpose.  It wraps an OpenSSL memory BIO (Basic IO) object:
       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`.
-
-Some notes related to the use of :class:`SSLObject`:
-
-- All IO 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.
-
-- There is no module-level ``wrap_bio`` call like there is for
-  :meth:`~SSLContext.wrap_socket`. An :class:`SSLObject` is always created via
-  an :class:`SSLContext`.
-
-- There is no *do_handshake_on_connect* machinery. You must always manually
-  call :meth:`~SSLSocket.do_handshake` to start the handshake.
-
-- There is no handling of *suppress_ragged_eofs*. All end-of-file conditions
-  that are in violation of the protocol are reported via the :exc:`SSLEOFError`
-  exception.
-
-- The method :meth:`~SSLSocket.unwrap` call does not return anything, unlike
-  for an SSL socket where it returns the underlying socket.
-
-- The *server_name_callback* callback passed to
-  :meth:`SSLContext.set_servername_callback` will get an :class:`SSLObject`
-  instance instead of a :class:`SSLSocket` instance as its first parameter.
-
 
 .. _ssl-security: