Skip to content

[3.13] gh-138633: synchronize documented signatures of SSL objects with runtime ones (GH-138639, GH-138648) #138647

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Sep 18, 2025
Merged

[3.13] gh-138633: synchronize documented signatures of SSL objects with runtime ones (GH-138639, GH-138648) #138647

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 25 additions & 21 deletions Doc/library/ssl.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,7 +125,8 @@ Context creation
A convenience function helps create :class:`SSLContext` objects for common
purposes.

.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, cafile=None, capath=None, cadata=None)
.. function:: create_default_context(purpose=Purpose.SERVER_AUTH, *,\
cafile=None, capath=None, cadata=None)

Return a new :class:`SSLContext` object with default settings for
the given *purpose*. The settings are chosen by the :mod:`ssl` module,
Expand Down Expand Up @@ -314,7 +315,7 @@ Exceptions
Random generation
^^^^^^^^^^^^^^^^^

.. function:: RAND_bytes(num)
.. function:: RAND_bytes(num, /)

Return *num* cryptographically strong pseudo-random bytes. Raises an
:class:`SSLError` if the PRNG has not been seeded with enough data or if the
Expand All @@ -338,7 +339,7 @@ Random generation
:func:`ssl.RAND_egd` and :func:`ssl.RAND_add` to increase the randomness of
the pseudo-random number generator.

.. function:: RAND_add(bytes, entropy)
.. function:: RAND_add(bytes, entropy, /)

Mix the given *bytes* into the SSL pseudo-random number generator. The
parameter *entropy* (a float) is a lower bound on the entropy contained in
Expand Down Expand Up @@ -406,12 +407,12 @@ Certificate handling
.. versionchanged:: 3.10
The *timeout* parameter was added.

.. function:: DER_cert_to_PEM_cert(DER_cert_bytes)
.. function:: DER_cert_to_PEM_cert(der_cert_bytes)

Given a certificate as a DER-encoded blob of bytes, returns a PEM-encoded
string version of the same certificate.

.. function:: PEM_cert_to_DER_cert(PEM_cert_string)
.. function:: PEM_cert_to_DER_cert(pem_cert_string)

Given a certificate as an ASCII PEM string, returns a DER-encoded sequence of
bytes for that same certificate.
Expand Down Expand Up @@ -1122,10 +1123,10 @@ SSL sockets also have the following additional methods and attributes:
.. deprecated:: 3.6
Use :meth:`~SSLSocket.recv` instead of :meth:`~SSLSocket.read`.

.. method:: SSLSocket.write(buf)
.. method:: SSLSocket.write(data)

Write *buf* to the SSL socket and return the number of bytes written. The
*buf* argument must be an object supporting the buffer interface.
Write *data* to the SSL socket and return the number of bytes written. The
*data* argument must be an object supporting the buffer interface.

Raise :exc:`SSLWantReadError` or :exc:`SSLWantWriteError` if the socket is
:ref:`non-blocking <ssl-nonblocking>` and the write would block.
Expand All @@ -1135,7 +1136,7 @@ SSL sockets also have the following additional methods and attributes:

.. versionchanged:: 3.5
The socket timeout is no longer reset each time bytes are received or sent.
The socket timeout is now the maximum total duration to write *buf*.
The socket timeout is now the maximum total duration to write *data*.

.. deprecated:: 3.6
Use :meth:`~SSLSocket.send` instead of :meth:`~SSLSocket.write`.
Expand All @@ -1152,12 +1153,15 @@ SSL sockets also have the following additional methods and attributes:
:meth:`~socket.socket.recv` and :meth:`~socket.socket.send` instead of these
methods.

.. method:: SSLSocket.do_handshake()
.. method:: SSLSocket.do_handshake(block=False)

Perform the SSL setup handshake.

If *block* is true and the timeout obtained by :meth:`~socket.socket.gettimeout`
is zero, the socket is set in blocking mode until the handshake is performed.

.. versionchanged:: 3.4
The handshake method also performs :func:`match_hostname` when the
The handshake method also performs :func:`!match_hostname` when the
:attr:`~SSLContext.check_hostname` attribute of the socket's
:attr:`~SSLSocket.context` is true.

Expand All @@ -1167,7 +1171,7 @@ SSL sockets also have the following additional methods and attributes:

.. versionchanged:: 3.7
Hostname or IP address is matched by OpenSSL during handshake. The
function :func:`match_hostname` is no longer used. In case OpenSSL
function :func:`!match_hostname` is no longer used. In case OpenSSL
refuses a hostname or IP address, the handshake is aborted early and
a TLS alert message is sent to the peer.

Expand Down Expand Up @@ -1637,7 +1641,7 @@ to speed up repeated connections from the same clients.
provided as part of the operating system, though, it is likely to be
configured properly.

.. method:: SSLContext.set_ciphers(ciphers)
.. method:: SSLContext.set_ciphers(ciphers, /)

Set the available ciphers for sockets created with this context.
It should be a string in the `OpenSSL cipher list format
Expand All @@ -1653,7 +1657,7 @@ to speed up repeated connections from the same clients.
TLS 1.3 cipher suites cannot be disabled with
:meth:`~SSLContext.set_ciphers`.

.. method:: SSLContext.set_alpn_protocols(protocols)
.. method:: SSLContext.set_alpn_protocols(alpn_protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of ASCII strings, like ``['http/1.1',
Expand All @@ -1667,7 +1671,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.5

.. method:: SSLContext.set_npn_protocols(protocols)
.. method:: SSLContext.set_npn_protocols(npn_protocols)

Specify which protocols the socket should advertise during the SSL/TLS
handshake. It should be a list of strings, like ``['http/1.1', 'spdy/2']``,
Expand Down Expand Up @@ -1734,7 +1738,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.7

.. attribute:: SSLContext.set_servername_callback(server_name_callback)
.. method:: SSLContext.set_servername_callback(server_name_callback)

This is a legacy API retained for backwards compatibility. When possible,
you should use :attr:`sni_callback` instead. The given *server_name_callback*
Expand All @@ -1748,7 +1752,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.4

.. method:: SSLContext.load_dh_params(dhfile)
.. method:: SSLContext.load_dh_params(dhfile, /)

Load the key generation parameters for Diffie-Hellman (DH) key exchange.
Using DH key exchange improves forward secrecy at the expense of
Expand All @@ -1761,7 +1765,7 @@ to speed up repeated connections from the same clients.

.. versionadded:: 3.3

.. method:: SSLContext.set_ecdh_curve(curve_name)
.. method:: SSLContext.set_ecdh_curve(curve_name, /)

Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) key
exchange. ECDH is significantly faster than regular DH while arguably
Expand Down Expand Up @@ -2635,12 +2639,12 @@ purpose. It wraps an OpenSSL memory BIO (Basic IO) object:
A boolean indicating whether the memory BIO is current at the end-of-file
position.

.. method:: MemoryBIO.read(n=-1)
.. 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)
.. method:: MemoryBIO.write(buf, /)

Write the bytes from *buf* to the memory BIO. The *buf* argument must be an
object supporting the buffer protocol.
Expand Down Expand Up @@ -2723,7 +2727,7 @@ This common check is automatically performed when

.. versionchanged:: 3.7
Hostname matchings is now performed by OpenSSL. Python no longer uses
:func:`match_hostname`.
:func:`!match_hostname`.

In server mode, if you want to authenticate your clients using the SSL layer
(rather than using a higher-level authentication mechanism), you'll also have
Expand Down
Loading