Issue #10075: Add a session_stats() method to SSLContext objects.
diff --git a/Doc/library/ssl.rst b/Doc/library/ssl.rst
index f36dbc7..c9c6ca0 100644
--- a/Doc/library/ssl.rst
+++ b/Doc/library/ssl.rst
@@ -481,13 +481,17 @@
.. versionadded:: 3.2
+An SSL context holds various data longer-lived than single SSL connections,
+such as SSL configuration options, certificate(s) and private key(s).
+It also manages a cache of SSL sessions for server-side sockets, in order
+to speed up repeated connections from the same clients.
+
.. class:: SSLContext(protocol)
- An object holding various data longer-lived than single SSL connections,
- such as SSL configuration options, certificate(s) and private key(s).
- You must pass *protocol* which must be one of the ``PROTOCOL_*`` constants
- defined in this module. :data:`PROTOCOL_SSLv23` is recommended for
- maximum interoperability.
+ Create a new SSL context. You must pass *protocol* which must be one
+ of the ``PROTOCOL_*`` constants defined in this module.
+ :data:`PROTOCOL_SSLv23` is recommended for maximum interoperability.
+
:class:`SSLContext` objects have the following methods and attributes:
@@ -542,6 +546,18 @@
and *suppress_ragged_eofs* have the same meaning as in the top-level
:func:`wrap_socket` function.
+.. method:: SSLContext.session_stats()
+
+ Get statistics about the SSL sessions created or managed by this context.
+ A dictionary is returned which maps the names of each `piece of information
+ <http://www.openssl.org/docs/ssl/SSL_CTX_sess_number.html>`_ to their
+ numeric values. For example, here is the total number of hits and misses
+ in the session cache since the context was created::
+
+ >>> stats = context.session_stats()
+ >>> stats['hits'], stats['misses']
+ (0, 0)
+
.. attribute:: SSLContext.options
An integer representing the set of SSL options enabled on this context.