Skip to content

gh-138633: synchronize documented signatures of SSL objects with runtime ones #138639

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 8, 2025
Merged

gh-138633: synchronize documented signatures of SSL objects with runtime ones #138639

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
48 changes: 26 additions & 22 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 @@
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 @@ -333,7 +334,7 @@
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 @@ -357,7 +358,7 @@
: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 @@ -425,12 +426,12 @@
.. 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 @@ -1160,10 +1161,10 @@
.. 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 @@ -1173,7 +1174,7 @@

.. 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 @@ -1190,12 +1191,15 @@
: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.gettimeout`

Check warning on line 1198 in Doc/library/ssl.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:meth reference target not found: socket.gettimeout [ref.meth]
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

Check warning on line 1202 in Doc/library/ssl.rst

View workflow job for this annotation

GitHub Actions / Docs / Docs 

py:func reference target not found: match_hostname [ref.func]
:attr:`~SSLContext.check_hostname` attribute of the socket's
:attr:`~SSLSocket.context` is true.

Expand Down Expand Up @@ -1717,7 +1721,7 @@
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 allowed ciphers for sockets created with this context when
connecting using TLS 1.2 and earlier. The *ciphers* argument should
Expand All @@ -1733,7 +1737,7 @@
When connected, the :meth:`SSLSocket.cipher` method of SSL sockets will
return details about the negotiated cipher.

.. method:: SSLContext.set_ciphersuites(ciphersuites)
.. method:: SSLContext.set_ciphersuites(ciphersuites, /)

Set the allowed ciphers for sockets created with this context when
connecting using TLS 1.3. The *ciphersuites* argument should be a
Expand All @@ -1747,7 +1751,7 @@

.. versionadded:: next

.. method:: SSLContext.set_groups(groups)
.. method:: SSLContext.set_groups(groups, /)

Set the groups allowed for key agreement for sockets created with this
context. It should be a string in the `OpenSSL group list format
Expand All @@ -1760,7 +1764,7 @@

.. versionadded:: next

.. method:: SSLContext.set_client_sigalgs(sigalgs)
.. method:: SSLContext.set_client_sigalgs(sigalgs, /)

Set the signature algorithms allowed for certificate-based client
authentication. It should be a string in the `OpenSSL client sigalgs
Expand All @@ -1775,7 +1779,7 @@

.. versionadded:: next

.. method:: SSLContext.set_server_sigalgs(sigalgs)
.. method:: SSLContext.set_server_sigalgs(sigalgs, /)

Set the signature algorithms allowed for the server to complete the TLS
handshake. It should be a string in the `OpenSSL sigalgs list format
Expand All @@ -1789,7 +1793,7 @@

.. versionadded:: next

.. 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 @@ -1803,7 +1807,7 @@

.. 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 @@ -1870,7 +1874,7 @@

.. 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 @@ -1884,7 +1888,7 @@

.. 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 @@ -1897,7 +1901,7 @@

.. 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 @@ -2771,12 +2775,12 @@
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
Loading