[Python-checkins] cpython: Issue #22564: cleanup SSLObject doc
victor.stinner
python-checkins at python.org
Fri Oct 10 13:05:58 CEST 2014
https://hg.python.org/cpython/rev/5f773540e2ef
changeset: 92922:5f773540e2ef
user: Victor Stinner <victor.stinner at gmail.com>
date: Fri Oct 10 13:04:08 2014 +0200
summary:
Issue #22564: cleanup SSLObject doc
files:
Doc/library/ssl.rst | 79 +++++++++++++++++++-------------
1 files changed, 46 insertions(+), 33 deletions(-)
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1777,9 +1777,22 @@
.. class:: SSLObject
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`:
+ instance that does not contain any network IO methods. This class is
+ typically used by framework authors that want to implement asynchronous IO
+ for SSL through memory buffers.
+
+ This class implements an interface on top of a low-level SSL object as
+ implemented by OpenSSL. This object captures the state of an SSL connection
+ but does not provide any network IO itself. IO needs to be performed through
+ separate "BIO" objects which are OpenSSL's IO abstraction layer.
+
+ 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.
+
+ The following methods are available:
- :attr:`~SSLSocket.context`
- :attr:`~SSLSocket.server_side`
@@ -1795,36 +1808,36 @@
- :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 :ref:`non-blocking <ssl-nonblocking>`.
- 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.
+ When compared to :class:`SSLSocket`, this object lacks the following
+ features:
+
+ - Any form of network IO incluging methods such as ``recv()`` and
+ ``send()``.
+
+ - 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.
+
+ Some notes related to the use of :class:`SSLObject`:
+
+ - All IO on an :class:`SSLObject` is :ref:`non-blocking <ssl-nonblocking>`.
+ 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`.
An SSLObject communicates with the outside world using memory buffers. The
class :class:`MemoryBIO` provides a memory buffer that can be used for this
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list