gh-126890: Restore stripped ssl docstrings

[ZeroIntensity]

In GH-124993, I forgot to carry over some of the docstrings to AC. This adds all of them back.

• Issue: Restore docstrings in ssl #126890

[encukou]

At a first glance at those warnings, it looks like this might need some changes in clinic :(
Shout if you want me to help.

[neonene]

Please add a docstring for _ssl.MemoryBIO.pending.

I think the warnings are related to the following regression:

3.12 on Windows:

>>> help(_ssl._SSLSocket.context)
Help on getset descriptor _ssl._SSLSocket.context:

context
    _setter_context(ctx)
    This changes the context associated with the SSLSocket. This is typically
    used from within a callback function set by the sni_callback
    on the SSLContext to change the certificate information associated with the
    SSLSocket before the cryptographic exchange handshake messages
>>>

This PR:

>>> help(_ssl._SSLSocket.context)
Help on getset descriptor _ssl._SSLSocket.context:

context

>>>

[ZeroIntensity]

As far as I can tell, the warnings are a clinic bug.

[erlend-aasland]

Can we tear out the Argument Clinic bug fix as a separate PR?

[ZeroIntensity]

Yeah, I'll do that. A fair warning: it might take me a little while to get the PR up; I'm currently on a slow connection and GitHub takes forever.

[neonene]

Thanks. I confirmed the following 16 PyDoc_STRVAR()s' migration on this PR:

PyDoc_STRVAR(PySSL_set_context_doc, ...)
PyDoc_STRVAR(PySSL_get_server_side_doc, ...)
PyDoc_STRVAR(PySSL_get_server_hostname_doc, ...)
PyDoc_STRVAR(PySSL_get_owner_doc, ...)
PyDoc_STRVAR(PySSL_set_session_doc, ...)
PyDoc_STRVAR(PySSL_get_session_reused_doc, ...)
PyDoc_STRVAR(PySSLContext_num_tickets_doc, ...)
PyDoc_STRVAR(PySSLContext_security_level_doc, ...)
PyDoc_STRVAR(PySSLContext_sni_callback_doc, ...)
PyDoc_STRVAR(PySSL_memory_bio_pending_doc, ...)
PyDoc_STRVAR(PySSL_memory_bio_eof_doc, ...)
PyDoc_STRVAR(PySSLSession_get_time_doc, ...)
PyDoc_STRVAR(PySSLSession_get_timeout_doc, ...)
PyDoc_STRVAR(PySSLSession_get_ticket_lifetime_hint_doc, ...)
PyDoc_STRVAR(PySSLSession_get_session_id_doc, ...)
PyDoc_STRVAR(PySSLSession_get_has_ticket_doc, ...)

>>> help(_ssl._SSLSocket.context)
Help on getset descriptor _ssl._SSLSocket.context:

context
    This changes the context associated with the SSLSocket.

    This is typically used from within a callback function set by the sni_callback
    on the SSLContext to change the certificate information associated with the
    SSLSocket before the cryptographic exchange handshake messages.

>>> help(_ssl._SSLSocket.server_side)
Help on getset descriptor _ssl._SSLSocket.server_side:

server_side
    Whether this is a server-side socket.

>>> help(_ssl._SSLSocket.server_hostname)
Help on getset descriptor _ssl._SSLSocket.server_hostname:

server_hostname
    The currently set server hostname (for SNI).

>>> help(_ssl._SSLSocket.owner)
Help on getset descriptor _ssl._SSLSocket.owner:

owner
    The Python-level owner of this object.

    Passed as "self" in servername callback.

>>> help(_ssl._SSLSocket.session)
Help on getset descriptor _ssl._SSLSocket.session:

session
    The underlying SSLSession object.

>>> help(_ssl._SSLSocket.session_reused)
Help on getset descriptor _ssl._SSLSocket.session_reused:

session_reused
    Was the client session reused during handshake?

>>> help(_ssl._SSLContext.num_tickets)
Help on getset descriptor _ssl._SSLContext.num_tickets:

num_tickets
    Control the number of TLSv1.3 session tickets.

>>> help(_ssl._SSLContext.security_level)
Help on getset descriptor _ssl._SSLContext.security_level:

security_level
    The current security level.

>>> help(_ssl._SSLContext.sni_callback)
Help on getset descriptor _ssl._SSLContext.sni_callback:

sni_callback
    Set a callback that will be called when a server name is provided by the SSL/TLS client in the SNI extension.

    If the argument is None then the callback is disabled. The method is called
    with the SSLSocket, the server name as a string, and the SSLContext object.

    See RFC 6066 for details of the SNI extension.

>>> help(_ssl.MemoryBIO.pending)
Help on getset descriptor _ssl.MemoryBIO.pending:

pending
    The number of bytes pending in the memory BIO.

>>> help(_ssl.MemoryBIO.eof)
Help on getset descriptor _ssl.MemoryBIO.eof:

eof
    Whether the memory BIO is at EOF.

>>> help(_ssl.SSLSession.time)
Help on getset descriptor _ssl.SSLSession.time:

time
    Session creation time (seconds since epoch).

>>> help(_ssl.SSLSession.timeout)
Help on getset descriptor _ssl.SSLSession.timeout:

timeout
    Session timeout (delta in seconds).

>>> help(_ssl.SSLSession.ticket_lifetime_hint)
Help on getset descriptor _ssl.SSLSession.ticket_lifetime_hint:

ticket_lifetime_hint
    Ticket life time hint.

>>> help(_ssl.SSLSession.id)
Help on getset descriptor _ssl.SSLSession.id:

id
    Session ID.

>>> help(_ssl.SSLSession.has_ticket)
Help on getset descriptor _ssl.SSLSession.has_ticket:

has_ticket
    Does the session contain a ticket?

>>>

[encukou]

Thank you for following up!

[ZeroIntensity]

@encukou, the 3.13 backport (GH-125780) just got merged for the original thread safety fix, so we have to backport this as well.

[miss-islington-app]

Thanks @ZeroIntensity for the PR, and @encukou for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @ZeroIntensity and @encukou, I could not cleanly backport this to 3.13 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker c112de1da2d18e3b5c2ea30b0e409f18e574efd8 3.13

[ZeroIntensity]

I figured that might happen :(. I'll look into it.

[bedevere-app]

GH-127513 is a backport of this pull request to the 3.13 branch.