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, ...)

Details

>>>help(_ssl._SSLSocket.context)
Helpongetsetdescriptor_ssl._SSLSocket.context:
contextThischangesthecontextassociatedwiththeSSLSocket.
Thisistypicallyusedfromwithinacallbackfunctionsetbythesni_callbackontheSSLContexttochangethecertificateinformationassociatedwiththeSSLSocketbeforethecryptographicexchangehandshakemessages.
>>>help(_ssl._SSLSocket.server_side)
Helpongetsetdescriptor_ssl._SSLSocket.server_side:
server_sideWhetherthisisaserver-sidesocket.
>>>help(_ssl._SSLSocket.server_hostname)
Helpongetsetdescriptor_ssl._SSLSocket.server_hostname:
server_hostnameThecurrentlysetserverhostname (forSNI).
>>>help(_ssl._SSLSocket.owner)
Helpongetsetdescriptor_ssl._SSLSocket.owner:
ownerThePython-levelownerofthisobject.
Passedas"self"inservernamecallback.
>>>help(_ssl._SSLSocket.session)
Helpongetsetdescriptor_ssl._SSLSocket.session:
sessionTheunderlyingSSLSessionobject.
>>>help(_ssl._SSLSocket.session_reused)
Helpongetsetdescriptor_ssl._SSLSocket.session_reused:
session_reusedWastheclientsessionreusedduringhandshake?
>>>help(_ssl._SSLContext.num_tickets)
Helpongetsetdescriptor_ssl._SSLContext.num_tickets:
num_ticketsControlthenumberofTLSv1.3sessiontickets.
>>>help(_ssl._SSLContext.security_level)
Helpongetsetdescriptor_ssl._SSLContext.security_level:
security_levelThecurrentsecuritylevel.
>>>help(_ssl._SSLContext.sni_callback)
Helpongetsetdescriptor_ssl._SSLContext.sni_callback:
sni_callbackSetacallbackthatwillbecalledwhenaservernameisprovidedbytheSSL/TLSclientintheSNIextension.
IftheargumentisNonethenthecallbackisdisabled. ThemethodiscalledwiththeSSLSocket, theservernameasastring, andtheSSLContextobject.
SeeRFC6066fordetailsoftheSNIextension.
>>>help(_ssl.MemoryBIO.pending)
Helpongetsetdescriptor_ssl.MemoryBIO.pending:
pendingThenumberofbytespendinginthememoryBIO.
>>>help(_ssl.MemoryBIO.eof)
Helpongetsetdescriptor_ssl.MemoryBIO.eof:
eofWhetherthememoryBIOisatEOF.
>>>help(_ssl.SSLSession.time)
Helpongetsetdescriptor_ssl.SSLSession.time:
timeSessioncreationtime (secondssinceepoch).
>>>help(_ssl.SSLSession.timeout)
Helpongetsetdescriptor_ssl.SSLSession.timeout:
timeoutSessiontimeout (deltainseconds).
>>>help(_ssl.SSLSession.ticket_lifetime_hint)
Helpongetsetdescriptor_ssl.SSLSession.ticket_lifetime_hint:
ticket_lifetime_hintTicketlifetimehint.
>>>help(_ssl.SSLSession.id)
Helpongetsetdescriptor_ssl.SSLSession.id:
idSessionID.
>>>help(_ssl.SSLSession.has_ticket)
Helpongetsetdescriptor_ssl.SSLSession.has_ticket:
has_ticketDoesthesessioncontainaticket?
>>>

[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.