Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 8, 2023
Merged

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 57 additions & 18 deletions Lib/test/clinic.test.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]
Expand All @@ -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__},
Expand Down Expand Up @@ -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]*/
6 changes: 6 additions & 0 deletions Tools/clinic/clinic.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down