https://github.com/python/cpython/commit/c112de1da2d18e3b5c2ea30b0e409f18e574efd8
commit: c112de1da2d18e3b5c2ea30b0e409f18e574efd8
branch: main
author: Peter Bierma <[email protected]>
committer: encukou <[email protected]>
date: 2024-12-02T13:50:34+01:00
summary:
gh-126890: Restore stripped `ssl` docstrings (GH-127281)
files:
M Modules/_ssl.c
M Modules/clinic/_ssl.c.h
diff --git a/Modules/_ssl.c b/Modules/_ssl.c
index e5b8bf21002ea5..59c414f9ce1ceb 100644
--- 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 @@ _servername_callback(SSL *s, int *al, void *args)
@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 957f5ced3a2cee..1ff85e32ffe5a0 100644
--- 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 @@ _ssl_MemoryBIO(PyTypeObject *type, PyObject *args,
PyObject *kwargs)
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 @@ _ssl_enum_crls(PyObject *module, PyObject *const *args,
Py_ssize_t nargs, PyObje
#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]*/
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: [email protected]
