gh-95065: Make Argument Clinic append deprecation warnings to docstrings (#107745)

Author: erlend-aasland

Lib/test/clinic.test.c

@@ -5477,7 +5477,11 @@ test_deprecate_positional_pos1_len1_optional
 PyDoc_STRVAR(test_deprecate_positional_pos1_len1_optional__doc__,
 "test_deprecate_positional_pos1_len1_optional($module, /, a, b=None)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing 2 positional arguments to\n"
+"test_deprecate_positional_pos1_len1_optional() is deprecated.\n"
+"Parameter \'b\' will become a keyword-only parameter in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS1_LEN1_OPTIONAL_METHODDEF    \
     {"test_deprecate_positional_pos1_len1_optional", _PyCFunction_CAST(test_deprecate_positional_pos1_len1_optional), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos1_len1_optional__doc__},
@@ -5567,7 +5571,7 @@ test_deprecate_positional_pos1_len1_optional(PyObject *module, PyObject *const *
 static PyObject *
 test_deprecate_positional_pos1_len1_optional_impl(PyObject *module,
                                                   PyObject *a, PyObject *b)
-/*[clinic end generated code: output=09a6edec1ddcd469 input=89099f3dacd757da]*/
+/*[clinic end generated code: output=6c0fd9d94fa1e765 input=89099f3dacd757da]*/
 
 
 /*[clinic input]
@@ -5580,7 +5584,11 @@ test_deprecate_positional_pos1_len1
 PyDoc_STRVAR(test_deprecate_positional_pos1_len1__doc__,
 "test_deprecate_positional_pos1_len1($module, /, a, b)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing 2 positional arguments to\n"
+"test_deprecate_positional_pos1_len1() is deprecated. Parameter \'b\'\n"
+"will become a keyword-only parameter in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS1_LEN1_METHODDEF    \
     {"test_deprecate_positional_pos1_len1", _PyCFunction_CAST(test_deprecate_positional_pos1_len1), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos1_len1__doc__},
@@ -5661,7 +5669,7 @@ test_deprecate_positional_pos1_len1(PyObject *module, PyObject *const *args, Py_
 static PyObject *
 test_deprecate_positional_pos1_len1_impl(PyObject *module, PyObject *a,
                                          PyObject *b)
-/*[clinic end generated code: output=52a2618293df747d input=1702bbab1e9b3b99]*/
+/*[clinic end generated code: output=22821a0fa9945d0c input=1702bbab1e9b3b99]*/
 
 
 /*[clinic input]
@@ -5677,7 +5685,12 @@ test_deprecate_positional_pos1_len2_with_kwd
 PyDoc_STRVAR(test_deprecate_positional_pos1_len2_with_kwd__doc__,
 "test_deprecate_positional_pos1_len2_with_kwd($module, /, a, b, c, *, d)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing more than 1 positional argument to\n"
+"test_deprecate_positional_pos1_len2_with_kwd() is deprecated.\n"
+"Parameters \'b\' and \'c\' will become keyword-only parameters in Python\n"
+"3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS1_LEN2_WITH_KWD_METHODDEF    \
     {"test_deprecate_positional_pos1_len2_with_kwd", _PyCFunction_CAST(test_deprecate_positional_pos1_len2_with_kwd), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos1_len2_with_kwd__doc__},
@@ -5768,7 +5781,7 @@ static PyObject *
 test_deprecate_positional_pos1_len2_with_kwd_impl(PyObject *module,
                                                   PyObject *a, PyObject *b,
                                                   PyObject *c, PyObject *d)
-/*[clinic end generated code: output=550aabea548589b4 input=28cdb885f6c34eab]*/
+/*[clinic end generated code: output=061d554ccc6b8f51 input=28cdb885f6c34eab]*/
 
 
 /*[clinic input]
@@ -5780,7 +5793,11 @@ test_deprecate_positional_pos0_len1
 PyDoc_STRVAR(test_deprecate_positional_pos0_len1__doc__,
 "test_deprecate_positional_pos0_len1($module, /, a)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing positional arguments to\n"
+"test_deprecate_positional_pos0_len1() is deprecated. Parameter \'a\'\n"
+"will become a keyword-only parameter in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS0_LEN1_METHODDEF    \
     {"test_deprecate_positional_pos0_len1", _PyCFunction_CAST(test_deprecate_positional_pos0_len1), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos0_len1__doc__},
@@ -5857,7 +5874,7 @@ test_deprecate_positional_pos0_len1(PyObject *module, PyObject *const *args, Py_
 
 static PyObject *
 test_deprecate_positional_pos0_len1_impl(PyObject *module, PyObject *a)
-/*[clinic end generated code: output=66c63ec8d6903bde input=678206db25c0652c]*/
+/*[clinic end generated code: output=3e512117a5eda970 input=678206db25c0652c]*/
 
 
 /*[clinic input]
@@ -5870,7 +5887,11 @@ test_deprecate_positional_pos0_len2
 PyDoc_STRVAR(test_deprecate_positional_pos0_len2__doc__,
 "test_deprecate_positional_pos0_len2($module, /, a, b)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing positional arguments to\n"
+"test_deprecate_positional_pos0_len2() is deprecated. Parameters \'a\'\n"
+"and \'b\' will become keyword-only parameters in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS0_LEN2_METHODDEF    \
     {"test_deprecate_positional_pos0_len2", _PyCFunction_CAST(test_deprecate_positional_pos0_len2), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos0_len2__doc__},
@@ -5954,7 +5975,7 @@ test_deprecate_positional_pos0_len2(PyObject *module, PyObject *const *args, Py_
 static PyObject *
 test_deprecate_positional_pos0_len2_impl(PyObject *module, PyObject *a,
                                          PyObject *b)
-/*[clinic end generated code: output=6b6df40aaf751b2e input=fae0d0b1d480c939]*/
+/*[clinic end generated code: output=d41da050a5b82dd0 input=fae0d0b1d480c939]*/
 
 
 /*[clinic input]
@@ -5971,7 +5992,12 @@ PyDoc_STRVAR(test_deprecate_positional_pos0_len3_with_kwdonly__doc__,
 "test_deprecate_positional_pos0_len3_with_kwdonly($module, /, a, b, c,\n"
 "                                                 *, e)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing positional arguments to\n"
+"test_deprecate_positional_pos0_len3_with_kwdonly() is deprecated.\n"
+"Parameters \'a\', \'b\' and \'c\' will become keyword-only parameters in\n"
+"Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS0_LEN3_WITH_KWDONLY_METHODDEF    \
     {"test_deprecate_positional_pos0_len3_with_kwdonly", _PyCFunction_CAST(test_deprecate_positional_pos0_len3_with_kwdonly), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos0_len3_with_kwdonly__doc__},
@@ -6069,7 +6095,7 @@ test_deprecate_positional_pos0_len3_with_kwdonly_impl(PyObject *module,
                                                       PyObject *b,
                                                       PyObject *c,
                                                       PyObject *e)
-/*[clinic end generated code: output=5c936993846d01a3 input=1b0121770c0c52e0]*/
+/*[clinic end generated code: output=c5d7ddfc139ddf31 input=1b0121770c0c52e0]*/
 
 
 /*[clinic input]
@@ -6083,7 +6109,11 @@ test_deprecate_positional_pos2_len1
 PyDoc_STRVAR(test_deprecate_positional_pos2_len1__doc__,
 "test_deprecate_positional_pos2_len1($module, /, a, b, c)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing 3 positional arguments to\n"
+"test_deprecate_positional_pos2_len1() is deprecated. Parameter \'c\'\n"
+"will become a keyword-only parameter in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS2_LEN1_METHODDEF    \
     {"test_deprecate_positional_pos2_len1", _PyCFunction_CAST(test_deprecate_positional_pos2_len1), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos2_len1__doc__},
@@ -6166,7 +6196,7 @@ test_deprecate_positional_pos2_len1(PyObject *module, PyObject *const *args, Py_
 static PyObject *
 test_deprecate_positional_pos2_len1_impl(PyObject *module, PyObject *a,
                                          PyObject *b, PyObject *c)
-/*[clinic end generated code: output=2641e037296e3b61 input=e1d129689e69ec7c]*/
+/*[clinic end generated code: output=d80609e6b37ffb8a input=e1d129689e69ec7c]*/
 
 
 /*[clinic input]
@@ -6181,7 +6211,11 @@ test_deprecate_positional_pos2_len2
 PyDoc_STRVAR(test_deprecate_positional_pos2_len2__doc__,
 "test_deprecate_positional_pos2_len2($module, /, a, b, c, d)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing more than 2 positional arguments to\n"
+"test_deprecate_positional_pos2_len2() is deprecated. Parameters \'c\'\n"
+"and \'d\' will become keyword-only parameters in Python 3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS2_LEN2_METHODDEF    \
     {"test_deprecate_positional_pos2_len2", _PyCFunction_CAST(test_deprecate_positional_pos2_len2), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos2_len2__doc__},
@@ -6271,7 +6305,7 @@ static PyObject *
 test_deprecate_positional_pos2_len2_impl(PyObject *module, PyObject *a,
                                          PyObject *b, PyObject *c,
                                          PyObject *d)
-/*[clinic end generated code: output=4a9068ef8fee61f6 input=0d53533463a12792]*/
+/*[clinic end generated code: output=1c10d6197562319f input=0d53533463a12792]*/
 
 
 /*[clinic input]
@@ -6289,7 +6323,12 @@ PyDoc_STRVAR(test_deprecate_positional_pos2_len3_with_kwdonly__doc__,
 "test_deprecate_positional_pos2_len3_with_kwdonly($module, /, a, b, c,\n"
 "                                                 d, *, e)\n"
 "--\n"
-"\n");
+"\n"
+"Note: Passing more than 2 positional arguments to\n"
+"test_deprecate_positional_pos2_len3_with_kwdonly() is deprecated.\n"
+"Parameters \'c\' and \'d\' will become keyword-only parameters in Python\n"
+"3.14.\n"
+"");
 
 #define TEST_DEPRECATE_POSITIONAL_POS2_LEN3_WITH_KWDONLY_METHODDEF    \
     {"test_deprecate_positional_pos2_len3_with_kwdonly", _PyCFunction_CAST(test_deprecate_positional_pos2_len3_with_kwdonly), METH_FASTCALL|METH_KEYWORDS, test_deprecate_positional_pos2_len3_with_kwdonly__doc__},
@@ -6388,4 +6427,4 @@ test_deprecate_positional_pos2_len3_with_kwdonly_impl(PyObject *module,
                                                       PyObject *c,
                                                       PyObject *d,
                                                       PyObject *e)
-/*[clinic end generated code: output=1154c2e3e798948c input=154fd450448d8935]*/
+/*[clinic end generated code: output=d32375ffce63d3db input=154fd450448d8935]*/

Tools/clinic/clinic.py

@@ -941,6 +941,12 @@ def deprecate_positional_use(
                 f"{func.full_name}() is deprecated. Parameters {pstr} will "
                 f"become keyword-only parameters in Python {major}.{minor}."
             )
+
+        # Append deprecation warning to docstring.
+        lines = textwrap.wrap(f"Note: {depr_message}")
+        docstring = "\n".join(lines)
+        func.docstring += f"\n\n{docstring}\n"
+
         # Format and return the code block.
         code = self.DEPRECATED_POSITIONAL_PROTOTYPE.format(
             condition=condition,