gh-126890: Restore stripped `ssl` docstrings (GH-127281)

diff --git a/Modules/_ssl.c b/Modules/_ssl.c
index e5b8bf21002ea5a4bdcc37878683c95b3838f441..59c414f9ce1cebff828f610687c3a7c2e809927d 100644 (file)
--- a/Modules/_ssl.c
+++ b/Modules/_ssl.c
@@ -2162,11 +2162,17 @@ _ssl__SSLSocket_compression_impl(PySSLSocket *self)
 @critical_section
 @getter
 _ssl._SSLSocket.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.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLSocket_context_get_impl(PySSLSocket *self)
-/*[clinic end generated code: output=d23e82f72f32e3d7 input=25aa82e4d9fa344a]*/
+/*[clinic end generated code: output=d23e82f72f32e3d7 input=7cbb97407c2ace30]*/
 {
     return Py_NewRef(self->ctx);
 }
@@ -2233,11 +2239,15 @@ _ssl__SSLSocket_server_hostname_get_impl(PySSLSocket *self)
 @critical_section
 @getter
 _ssl._SSLSocket.owner
+
+The Python-level owner of this object.
+
+Passed as "self" in servername callback.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLSocket_owner_get_impl(PySSLSocket *self)
-/*[clinic end generated code: output=1f278cb930382927 input=bc2861ff3cf1402e]*/
+/*[clinic end generated code: output=1f278cb930382927 input=978a8382d9c25c92]*/
 {
     if (self->owner == NULL) {
         Py_RETURN_NONE;
@@ -2851,11 +2861,13 @@ _ssl__SSLSocket_verify_client_post_handshake_impl(PySSLSocket *self)
 @critical_section
 @getter
 _ssl._SSLSocket.session
+
+The underlying SSLSession object.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLSocket_session_get_impl(PySSLSocket *self)
-/*[clinic end generated code: output=a5cd5755b35da670 input=b9792df9255a9f63]*/
+/*[clinic end generated code: output=a5cd5755b35da670 input=d427318604244bf8]*/
 {
     /* get_session can return sessions from a server-side connection,
      * it does not check for handshake done or client socket. */
@@ -3657,11 +3669,13 @@ _ssl__SSLContext_maximum_version_set_impl(PySSLContext *self,
 @critical_section
 @getter
 _ssl._SSLContext.num_tickets
+
+Control the number of TLSv1.3 session tickets.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLContext_num_tickets_get_impl(PySSLContext *self)
-/*[clinic end generated code: output=3d06d016318846c9 input=1dee26d75163c073]*/
+/*[clinic end generated code: output=3d06d016318846c9 input=1e2599a2e22564ff]*/
 {
     // Clinic seems to be misbehaving when the comment is wrapped with in directive
 #if defined(TLS1_3_VERSION) && !defined(OPENSSL_NO_TLS1_3)
@@ -3705,11 +3719,13 @@ _ssl__SSLContext_num_tickets_set_impl(PySSLContext *self, PyObject *value)
 @critical_section
 @getter
 _ssl._SSLContext.security_level
+
+The current security level.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLContext_security_level_get_impl(PySSLContext *self)
-/*[clinic end generated code: output=56ece09e6a9572d0 input=a0416598e07c3183]*/
+/*[clinic end generated code: output=56ece09e6a9572d0 input=2bdeecb57bb86e3f]*/
 {
     PyObject *res = PyLong_FromLong(SSL_CTX_get_security_level(self->ctx));
     return res;
@@ -4666,11 +4682,18 @@ error:
 @critical_section
 @getter
 _ssl._SSLContext.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.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl__SSLContext_sni_callback_get_impl(PySSLContext *self)
-/*[clinic end generated code: output=961e6575cdfaf036 input=22dd28c31fdc4318]*/
+/*[clinic end generated code: output=961e6575cdfaf036 input=9b2473c5e984cfe6]*/
 {
     PyObject *cb = self->set_sni_cb;
     if (cb == NULL) {
@@ -5243,11 +5266,13 @@ memory_bio_dealloc(PySSLMemoryBIO *self)
 @critical_section
 @getter
 _ssl.MemoryBIO.pending
+
+The number of bytes pending in the memory BIO.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_MemoryBIO_pending_get_impl(PySSLMemoryBIO *self)
-/*[clinic end generated code: output=19236a32a51ac8ff input=c0b6d14eba107f6a]*/
+/*[clinic end generated code: output=19236a32a51ac8ff input=02d9063d8ac31732]*/
 {
     size_t res = BIO_ctrl_pending(self->bio);
     return PyLong_FromSize_t(res);
@@ -5257,11 +5282,13 @@ _ssl_MemoryBIO_pending_get_impl(PySSLMemoryBIO *self)
 @critical_section
 @getter
 _ssl.MemoryBIO.eof
+
+Whether the memory BIO is at EOF.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_MemoryBIO_eof_get_impl(PySSLMemoryBIO *self)
-/*[clinic end generated code: output=c255a9ea16e31b92 input=0f5c6be69752e04c]*/
+/*[clinic end generated code: output=c255a9ea16e31b92 input=c6ecc12c4509de1f]*/
 {
     size_t pending = BIO_ctrl_pending(self->bio);
     return PyBool_FromLong((pending == 0) && self->eof_written);
@@ -5502,11 +5529,13 @@ PySSLSession_clear(PySSLSession *self)
 @critical_section
 @getter
 _ssl.SSLSession.time
+
+Session creation time (seconds since epoch).
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_SSLSession_time_get_impl(PySSLSession *self)
-/*[clinic end generated code: output=4b887b9299de9be4 input=8d1e4afd09103279]*/
+/*[clinic end generated code: output=4b887b9299de9be4 input=67f2325284450ae2]*/
 {
 #if OPENSSL_VERSION_NUMBER >= 0x30300000L
     return _PyLong_FromTime_t(SSL_SESSION_get_time_ex(self->session));
@@ -5519,11 +5548,13 @@ _ssl_SSLSession_time_get_impl(PySSLSession *self)
 @critical_section
 @getter
 _ssl.SSLSession.timeout
+
+Session timeout (delta in seconds).
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_SSLSession_timeout_get_impl(PySSLSession *self)
-/*[clinic end generated code: output=82339c148ab2f7d1 input=ae5e84a9d85df60d]*/
+/*[clinic end generated code: output=82339c148ab2f7d1 input=cd17c2b087c442f2]*/
 {
     long timeout = SSL_SESSION_get_timeout(self->session);
     PyObject *res = PyLong_FromLong(timeout);
@@ -5534,11 +5565,13 @@ _ssl_SSLSession_timeout_get_impl(PySSLSession *self)
 @critical_section
 @getter
 _ssl.SSLSession.ticket_lifetime_hint
+
+Ticket life time hint.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_SSLSession_ticket_lifetime_hint_get_impl(PySSLSession *self)
-/*[clinic end generated code: output=c8b6db498136c275 input=d0e06942ddd8d07f]*/
+/*[clinic end generated code: output=c8b6db498136c275 input=f0e2df50961a7806]*/
 {
     unsigned long hint = SSL_SESSION_get_ticket_lifetime_hint(self->session);
     return PyLong_FromUnsignedLong(hint);
@@ -5548,11 +5581,13 @@ _ssl_SSLSession_ticket_lifetime_hint_get_impl(PySSLSession *self)
 @critical_section
 @getter
 _ssl.SSLSession.id
+
+Session ID.
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_SSLSession_id_get_impl(PySSLSession *self)
-/*[clinic end generated code: output=c532fb96b10c5adf input=e7322372cf6325dd]*/
+/*[clinic end generated code: output=c532fb96b10c5adf input=0a379e64312b776d]*/
 
 {
     const unsigned char *id;
@@ -5565,11 +5600,13 @@ _ssl_SSLSession_id_get_impl(PySSLSession *self)
 @critical_section
 @getter
 _ssl.SSLSession.has_ticket
+
+Does the session contain a ticket?
 [clinic start generated code]*/
 
 static PyObject *
 _ssl_SSLSession_has_ticket_get_impl(PySSLSession *self)
-/*[clinic end generated code: output=aa3ccfc40b10b96d input=1a48ae8955fa9601]*/
+/*[clinic end generated code: output=aa3ccfc40b10b96d input=fa475555f53a5086]*/
 {
     int res = SSL_SESSION_has_ticket(self->session);
     return res ? Py_True : Py_False;

diff --git a/Modules/clinic/_ssl.c.h b/Modules/clinic/_ssl.c.h
index 957f5ced3a2ceed919784f4a90b18d424e0acc97..1ff85e32ffe5a05a5c0eff005d0415351c811d70 100644 (file)
--- a/Modules/clinic/_ssl.c.h
+++ b/Modules/clinic/_ssl.c.h
@@ -258,6 +258,14 @@ _ssl__SSLSocket_compression(PySSLSocket *self, PyObject *Py_UNUSED(ignored))
     return _ssl__SSLSocket_compression_impl(self);
 }
 
+PyDoc_STRVAR(_ssl__SSLSocket_context__doc__,
+"This changes the context associated with the SSLSocket.\n"
+"\n"
+"This is typically used from within a callback function set by the sni_callback\n"
+"on the SSLContext to change the certificate information associated with the\n"
+"SSLSocket before the cryptographic exchange handshake messages.");
+#define _ssl__SSLSocket_context_DOCSTR _ssl__SSLSocket_context__doc__
+
 #if !defined(_ssl__SSLSocket_context_DOCSTR)
 #  define _ssl__SSLSocket_context_DOCSTR NULL
 #endif
@@ -366,6 +374,12 @@ _ssl__SSLSocket_server_hostname_get(PySSLSocket *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl__SSLSocket_owner__doc__,
+"The Python-level owner of this object.\n"
+"\n"
+"Passed as \"self\" in servername callback.");
+#define _ssl__SSLSocket_owner_DOCSTR _ssl__SSLSocket_owner__doc__
+
 #if !defined(_ssl__SSLSocket_owner_DOCSTR)
 #  define _ssl__SSLSocket_owner_DOCSTR NULL
 #endif
@@ -652,6 +666,10 @@ _ssl__SSLSocket_verify_client_post_handshake(PySSLSocket *self, PyObject *Py_UNU
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl__SSLSocket_session__doc__,
+"The underlying SSLSession object.");
+#define _ssl__SSLSocket_session_DOCSTR _ssl__SSLSocket_session__doc__
+
 #if !defined(_ssl__SSLSocket_session_DOCSTR)
 #  define _ssl__SSLSocket_session_DOCSTR NULL
 #endif
@@ -1057,6 +1075,10 @@ _ssl__SSLContext_maximum_version_set(PySSLContext *self, PyObject *value, void *
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl__SSLContext_num_tickets__doc__,
+"Control the number of TLSv1.3 session tickets.");
+#define _ssl__SSLContext_num_tickets_DOCSTR _ssl__SSLContext_num_tickets__doc__
+
 #if !defined(_ssl__SSLContext_num_tickets_DOCSTR)
 #  define _ssl__SSLContext_num_tickets_DOCSTR NULL
 #endif
@@ -1107,6 +1129,10 @@ _ssl__SSLContext_num_tickets_set(PySSLContext *self, PyObject *value, void *Py_U
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl__SSLContext_security_level__doc__,
+"The current security level.");
+#define _ssl__SSLContext_security_level_DOCSTR _ssl__SSLContext_security_level__doc__
+
 #if !defined(_ssl__SSLContext_security_level_DOCSTR)
 #  define _ssl__SSLContext_security_level_DOCSTR NULL
 #endif
@@ -1745,6 +1771,15 @@ _ssl__SSLContext_set_ecdh_curve(PySSLContext *self, PyObject *name)
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl__SSLContext_sni_callback__doc__,
+"Set a callback that will be called when a server name is provided by the SSL/TLS client in the SNI extension.\n"
+"\n"
+"If the argument is None then the callback is disabled. The method is called\n"
+"with the SSLSocket, the server name as a string, and the SSLContext object.\n"
+"\n"
+"See RFC 6066 for details of the SNI extension.");
+#define _ssl__SSLContext_sni_callback_DOCSTR _ssl__SSLContext_sni_callback__doc__
+
 #if !defined(_ssl__SSLContext_sni_callback_DOCSTR)
 #  define _ssl__SSLContext_sni_callback_DOCSTR NULL
 #endif
@@ -2063,6 +2098,10 @@ exit:
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_MemoryBIO_pending__doc__,
+"The number of bytes pending in the memory BIO.");
+#define _ssl_MemoryBIO_pending_DOCSTR _ssl_MemoryBIO_pending__doc__
+
 #if !defined(_ssl_MemoryBIO_pending_DOCSTR)
 #  define _ssl_MemoryBIO_pending_DOCSTR NULL
 #endif
@@ -2088,6 +2127,10 @@ _ssl_MemoryBIO_pending_get(PySSLMemoryBIO *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_MemoryBIO_eof__doc__,
+"Whether the memory BIO is at EOF.");
+#define _ssl_MemoryBIO_eof_DOCSTR _ssl_MemoryBIO_eof__doc__
+
 #if !defined(_ssl_MemoryBIO_eof_DOCSTR)
 #  define _ssl_MemoryBIO_eof_DOCSTR NULL
 #endif
@@ -2217,6 +2260,10 @@ _ssl_MemoryBIO_write_eof(PySSLMemoryBIO *self, PyObject *Py_UNUSED(ignored))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_SSLSession_time__doc__,
+"Session creation time (seconds since epoch).");
+#define _ssl_SSLSession_time_DOCSTR _ssl_SSLSession_time__doc__
+
 #if !defined(_ssl_SSLSession_time_DOCSTR)
 #  define _ssl_SSLSession_time_DOCSTR NULL
 #endif
@@ -2242,6 +2289,10 @@ _ssl_SSLSession_time_get(PySSLSession *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_SSLSession_timeout__doc__,
+"Session timeout (delta in seconds).");
+#define _ssl_SSLSession_timeout_DOCSTR _ssl_SSLSession_timeout__doc__
+
 #if !defined(_ssl_SSLSession_timeout_DOCSTR)
 #  define _ssl_SSLSession_timeout_DOCSTR NULL
 #endif
@@ -2267,6 +2318,10 @@ _ssl_SSLSession_timeout_get(PySSLSession *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_SSLSession_ticket_lifetime_hint__doc__,
+"Ticket life time hint.");
+#define _ssl_SSLSession_ticket_lifetime_hint_DOCSTR _ssl_SSLSession_ticket_lifetime_hint__doc__
+
 #if !defined(_ssl_SSLSession_ticket_lifetime_hint_DOCSTR)
 #  define _ssl_SSLSession_ticket_lifetime_hint_DOCSTR NULL
 #endif
@@ -2292,6 +2347,10 @@ _ssl_SSLSession_ticket_lifetime_hint_get(PySSLSession *self, void *Py_UNUSED(con
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_SSLSession_id__doc__,
+"Session ID.");
+#define _ssl_SSLSession_id_DOCSTR _ssl_SSLSession_id__doc__
+
 #if !defined(_ssl_SSLSession_id_DOCSTR)
 #  define _ssl_SSLSession_id_DOCSTR NULL
 #endif
@@ -2317,6 +2376,10 @@ _ssl_SSLSession_id_get(PySSLSession *self, void *Py_UNUSED(context))
     return return_value;
 }
 
+PyDoc_STRVAR(_ssl_SSLSession_has_ticket__doc__,
+"Does the session contain a ticket?");
+#define _ssl_SSLSession_has_ticket_DOCSTR _ssl_SSLSession_has_ticket__doc__
+
 #if !defined(_ssl_SSLSession_has_ticket_DOCSTR)
 #  define _ssl_SSLSession_has_ticket_DOCSTR NULL
 #endif
@@ -2767,4 +2830,4 @@ exit:
 #ifndef _SSL_ENUM_CRLS_METHODDEF
     #define _SSL_ENUM_CRLS_METHODDEF
 #endif /* !defined(_SSL_ENUM_CRLS_METHODDEF) */
-/*[clinic end generated code: output=44ab066d21277ee5 input=a9049054013a1b77]*/
+/*[clinic end generated code: output=654d6d7af659f6cd input=a9049054013a1b77]*/