[Python-checkins] cpython: Issue #22564: ssl doc: reorganize and reindent documentation of SSLObject and
victor.stinner
python-checkins at python.org
Fri Oct 10 13:05:58 CEST 2014
https://hg.python.org/cpython/rev/11ad670ca663
changeset: 92920:11ad670ca663
user: Victor Stinner <victor.stinner at gmail.com>
date: Fri Oct 10 12:49:08 2014 +0200
summary:
Issue #22564: ssl doc: reorganize and reindent documentation of SSLObject and
MemoryBIO; move documentation of SSLContext.wrap_bio()
files:
Doc/library/ssl.rst | 164 ++++++++++++++++----------------
1 files changed, 82 insertions(+), 82 deletions(-)
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -1269,6 +1269,16 @@
*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,21 +1778,51 @@
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`
+ 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 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
@@ -1793,73 +1833,33 @@
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`.
-
-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.
+ .. 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:
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list