Skip to content

Commit 0a7f48b

Browse files
erlend-aaslanderlend-aasland
authored
gh-95065: Produce nicer deprecation messages in Argument Clinic (#107808)
1 parent 1b3f5f2 commit 0a7f48b

File tree

2 files changed

+211
-18
lines changed

2 files changed

+211
-18
lines changed

‎Lib/test/clinic.test.c

Lines changed: 192 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,11 @@ output preset block
44
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=3c81ac2402d06a8b]*/
55

66
/*[clinic input]
7+
module m
8+
class m.T "TestObj *" "TestType"
79
class Test "TestObj *" "TestType"
810
[clinic start generated code]*/
9-
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=fc7e50384d12b83f]*/
11+
/*[clinic end generated code: output=da39a3ee5e6b4b0d input=f761b4d55cb179cf]*/
1012

1113
/*[clinic input]
1214
test_object_converter
@@ -6437,3 +6439,192 @@ test_deprecate_positional_pos2_len3_with_kwdonly_impl(PyObject *module,
64376439
PyObject *d,
64386440
PyObject *e)
64396441
/*[clinic end generated code: output=383d56b03f7c2dcb input=154fd450448d8935]*/
6442+
6443+
6444+
/*[clinic input]
6445+
@classmethod
6446+
Test.__new__
6447+
* [from 3.14]
6448+
a: object
6449+
The deprecation message should use the class name instead of __new__.
6450+
[clinic start generated code]*/
6451+
6452+
PyDoc_STRVAR(Test__doc__,
6453+
"Test(a)\n"
6454+
"--\n"
6455+
"\n"
6456+
"The deprecation message should use the class name instead of __new__.\n"
6457+
"\n"
6458+
"Note: Passing positional arguments to Test() is deprecated. Parameter\n"
6459+
"\'a\' will become a keyword-only parameter in Python 3.14.\n"
6460+
"");
6461+
6462+
static PyObject *
6463+
Test_impl(PyTypeObject *type, PyObject *a);
6464+
6465+
static PyObject *
6466+
Test(PyTypeObject *type, PyObject *args, PyObject *kwargs)
6467+
{
6468+
PyObject *return_value = NULL;
6469+
#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
6470+
6471+
#define NUM_KEYWORDS 1
6472+
static struct {
6473+
PyGC_Head _this_is_not_used;
6474+
PyObject_VAR_HEAD
6475+
PyObject *ob_item[NUM_KEYWORDS];
6476+
} _kwtuple = {
6477+
.ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
6478+
.ob_item = { &_Py_ID(a), },
6479+
};
6480+
#undef NUM_KEYWORDS
6481+
#define KWTUPLE (&_kwtuple.ob_base.ob_base)
6482+
6483+
#else // !Py_BUILD_CORE
6484+
# define KWTUPLE NULL
6485+
#endif // !Py_BUILD_CORE
6486+
6487+
static const char * const _keywords[] = {"a", NULL};
6488+
static _PyArg_Parser _parser = {
6489+
.keywords = _keywords,
6490+
.fname = "Test",
6491+
.kwtuple = KWTUPLE,
6492+
};
6493+
#undef KWTUPLE
6494+
PyObject *argsbuf[1];
6495+
PyObject * const *fastargs;
6496+
Py_ssize_t nargs = PyTuple_GET_SIZE(args);
6497+
PyObject *a;
6498+
6499+
// Emit compiler warnings when we get to Python 3.14.
6500+
#if PY_VERSION_HEX >= 0x030e00C0
6501+
# error \
6502+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6503+
" 'Test.__new__' to be keyword-only."
6504+
#elif PY_VERSION_HEX >= 0x030e00A0
6505+
# ifdef _MSC_VER
6506+
# pragma message ( \
6507+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6508+
" 'Test.__new__' to be keyword-only.")
6509+
# else
6510+
# warning \
6511+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6512+
" 'Test.__new__' to be keyword-only."
6513+
# endif
6514+
#endif
6515+
if (nargs == 1) {
6516+
if (PyErr_WarnEx(PyExc_DeprecationWarning,
6517+
"Passing positional arguments to Test() is deprecated. Parameter "
6518+
"'a' will become a keyword-only parameter in Python 3.14.", 1))
6519+
{
6520+
goto exit;
6521+
}
6522+
}
6523+
fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser, 1, 1, 0, argsbuf);
6524+
if (!fastargs) {
6525+
goto exit;
6526+
}
6527+
a = fastargs[0];
6528+
return_value = Test_impl(type, a);
6529+
6530+
exit:
6531+
return return_value;
6532+
}
6533+
6534+
static PyObject *
6535+
Test_impl(PyTypeObject *type, PyObject *a)
6536+
/*[clinic end generated code: output=d15a69ea37ec6502 input=f133dc077aef49ec]*/
6537+
6538+
6539+
/*[clinic input]
6540+
m.T.__init__
6541+
* [from 3.14]
6542+
a: object
6543+
The deprecation message should use the class name instead of __init__.
6544+
[clinic start generated code]*/
6545+
6546+
PyDoc_STRVAR(m_T___init____doc__,
6547+
"T(a)\n"
6548+
"--\n"
6549+
"\n"
6550+
"The deprecation message should use the class name instead of __init__.\n"
6551+
"\n"
6552+
"Note: Passing positional arguments to m.T() is deprecated. Parameter\n"
6553+
"\'a\' will become a keyword-only parameter in Python 3.14.\n"
6554+
"");
6555+
6556+
static int
6557+
m_T___init___impl(TestObj *self, PyObject *a);
6558+
6559+
static int
6560+
m_T___init__(PyObject *self, PyObject *args, PyObject *kwargs)
6561+
{
6562+
int return_value = -1;
6563+
#if defined(Py_BUILD_CORE) && !defined(Py_BUILD_CORE_MODULE)
6564+
6565+
#define NUM_KEYWORDS 1
6566+
static struct {
6567+
PyGC_Head _this_is_not_used;
6568+
PyObject_VAR_HEAD
6569+
PyObject *ob_item[NUM_KEYWORDS];
6570+
} _kwtuple = {
6571+
.ob_base = PyVarObject_HEAD_INIT(&PyTuple_Type, NUM_KEYWORDS)
6572+
.ob_item = { &_Py_ID(a), },
6573+
};
6574+
#undef NUM_KEYWORDS
6575+
#define KWTUPLE (&_kwtuple.ob_base.ob_base)
6576+
6577+
#else // !Py_BUILD_CORE
6578+
# define KWTUPLE NULL
6579+
#endif // !Py_BUILD_CORE
6580+
6581+
static const char * const _keywords[] = {"a", NULL};
6582+
static _PyArg_Parser _parser = {
6583+
.keywords = _keywords,
6584+
.fname = "T",
6585+
.kwtuple = KWTUPLE,
6586+
};
6587+
#undef KWTUPLE
6588+
PyObject *argsbuf[1];
6589+
PyObject * const *fastargs;
6590+
Py_ssize_t nargs = PyTuple_GET_SIZE(args);
6591+
PyObject *a;
6592+
6593+
// Emit compiler warnings when we get to Python 3.14.
6594+
#if PY_VERSION_HEX >= 0x030e00C0
6595+
# error \
6596+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6597+
" 'm.T.__init__' to be keyword-only."
6598+
#elif PY_VERSION_HEX >= 0x030e00A0
6599+
# ifdef _MSC_VER
6600+
# pragma message ( \
6601+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6602+
" 'm.T.__init__' to be keyword-only.")
6603+
# else
6604+
# warning \
6605+
"In clinic.test.c, update parameter(s) 'a' in the clinic input of" \
6606+
" 'm.T.__init__' to be keyword-only."
6607+
# endif
6608+
#endif
6609+
if (nargs == 1) {
6610+
if (PyErr_WarnEx(PyExc_DeprecationWarning,
6611+
"Passing positional arguments to m.T() is deprecated. Parameter "
6612+
"'a' will become a keyword-only parameter in Python 3.14.", 1))
6613+
{
6614+
goto exit;
6615+
}
6616+
}
6617+
fastargs = _PyArg_UnpackKeywords(_PyTuple_CAST(args)->ob_item, nargs, kwargs, NULL, &_parser, 1, 1, 0, argsbuf);
6618+
if (!fastargs) {
6619+
goto exit;
6620+
}
6621+
a = fastargs[0];
6622+
return_value = m_T___init___impl((TestObj *)self, a);
6623+
6624+
exit:
6625+
return return_value;
6626+
}
6627+
6628+
static int
6629+
m_T___init___impl(TestObj *self, PyObject *a)
6630+
/*[clinic end generated code: output=ef43c425816a549f input=f71b51dbe19fa657]*/

‎Tools/clinic/clinic.py

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -928,7 +928,7 @@ def deprecate_positional_use(
928928
if first_pos:
929929
preamble = f"Passing {first_pos+1} positional arguments to "
930930
depr_message = preamble + (
931-
f"{func.full_name}() is deprecated. Parameter {pstr} will "
931+
f"{func.fulldisplayname}() is deprecated. Parameter {pstr} will "
932932
f"become a keyword-only parameter in Python {major}.{minor}."
933933
)
934934
else:
@@ -939,7 +939,7 @@ def deprecate_positional_use(
939939
f"argument{'s' if first_pos != 1 else ''} to "
940940
)
941941
depr_message = preamble + (
942-
f"{func.full_name}() is deprecated. Parameters {pstr} will "
942+
f"{func.fulldisplayname}() is deprecated. Parameters {pstr} will "
943943
f"become keyword-only parameters in Python {major}.{minor}."
944944
)
945945

@@ -1673,14 +1673,7 @@ def render_function(
16731673

16741674
full_name = f.full_name
16751675
template_dict = {'full_name': full_name}
1676-
1677-
if new_or_init:
1678-
assert isinstance(f.cls, Class)
1679-
name = f.cls.name
1680-
else:
1681-
name = f.name
1682-
1683-
template_dict['name'] = name
1676+
template_dict['name'] = f.displayname
16841677

16851678
if f.c_basename:
16861679
c_basename = f.c_basename
@@ -2678,6 +2671,21 @@ def __post_init__(self) -> None:
26782671
self.self_converter: self_converter | None = None
26792672
self.__render_parameters__: list[Parameter] | None = None
26802673

2674+
@functools.cached_property
2675+
def displayname(self) -> str:
2676+
"""Pretty-printable name."""
2677+
if self.kind.new_or_init:
2678+
assert isinstance(self.cls, Class)
2679+
return self.cls.name
2680+
else:
2681+
return self.name
2682+
2683+
@functools.cached_property
2684+
def fulldisplayname(self) -> str:
2685+
if isinstance(self.module, Module):
2686+
return f"{self.module.name}.{self.displayname}"
2687+
return self.displayname
2688+
26812689
@property
26822690
def render_parameters(self) -> list[Parameter]:
26832691
if not self.__render_parameters__:
@@ -5522,13 +5530,7 @@ def format_docstring_signature(
55225530
self, f: Function, parameters: list[Parameter]
55235531
) -> str:
55245532
text, add, output = _text_accumulator()
5525-
if f.kind.new_or_init:
5526-
# classes get *just* the name of the class
5527-
# not __new__, not __init__, and not module.classname
5528-
assert f.cls
5529-
add(f.cls.name)
5530-
else:
5531-
add(f.name)
5533+
add(f.displayname)
55325534
if self.forced_text_signature:
55335535
add(self.forced_text_signature)
55345536
else:

0 commit comments

Comments
 (0)