Repository navigation
Argument Clinic: add support for renaming a parameter #108271
Description
Originally posted by @serhiy-storchaka in #95065 (comment):
- Rename positional-or-keyword or keyword-only parameters. In meantime the function should accept both old and new keyword names, but raise an exception if both are passed or if the argument is passed as positional and keyword. For example see Wrong keyword parameter name in regex pattern methods #64482.
Activity
erlend-aasland commentedon Aug 22, 2023
Brainstorming regarding syntax, my first thought would be to modify
parse_parameter(). Currently, we support theaskeyword, to rename the C argument of a parameter. I think it would be too messy if we added another keyword before:. Messy example where we want to renamecharasch:Something like this would be cleaner:
Here's another alternative, which require changes to
state_parameter():erlend-aasland commentedon Aug 22, 2023
An
betteralternative can be to add that support toCConverter:serhiy-storchaka commentedon Aug 22, 2023
I considered similar variants:
[...]at the end of the line, like in* [from ...]. It will be not easy to parse, because parameter declarations are longer, can span multiple physical lines, and we need to specify at least two options: the new name and the final version.@classmethodto@text_signature), but there is no precedence of using them for parameters, so it will look weird. Perhaps we should use other prefix than@for parameter decorators. We could also useunused=True. It is the simplest way. Although I am unsure about mixing converter arguments and parameter arguments, but we already do this. Perhaps in future we will change syntax to differentiate them.In addition to adding this feature we can add also allow add a parameter alias without deprecating the old name. One feature can be considered an extension of the other. What are ideas for this syntax? How can it be extended to add the deprecation of the old name? Should we support more than two names for the same parameter?
erlend-aasland commentedon Aug 22, 2023
I think there is value in keeping the DSL simple, so perhaps an argument to converter is the best option. I agree it is not ideal mixing converter and param arguments, but as you say, we already do.
erlend-aasland commentedon Aug 22, 2023
I worry that the decorator variant will be too complex for little gain. I agree it also looks weird.
gpshead commentedon May 31, 2025
Without having read this issue beforehand, the syntax variant I came up with for this was:
data|string[from 3.15] as data_obj: object(blah) = NULLstyle.
The need that made me ponder it came out of #134713 where hashlib has a param that pre-dates positional only but always should've been positional only (too late for that) that is alternatively called data or string in various places and we want to settle on the single data= name.
I threw a Claude Code at adding easier support for this multi-name argument feature into argument clinic. It got something basic working but it wasn't sufficient for me to push forward with as it was getting tangled up on some of the generated C details and I didn't want to spend time on that myself. If my branch has anything worth sharing I'll attach a draft PR of it here for reference.
The hashlib need isn't quite one of renaming a parameter as this was opened for. It is more one of accepting multiple names for the same thing (exclusively, making it an error to supply more than one of the positional & names) and while optionally deprecating some of them. Very similar in spirit though.
serhiy-storchaka commentedon May 31, 2025
Currently,
* [from 3.15]and/ [from 3.15]means that*and/will be active here from 3.15, but currently they are ignored. From this point of view,data|string[from 3.15]is wrong -- it looks likestringis not accepted now, but will be accepted since 3.15.Two first items from my plan has already been implemented. Removing and renaming a parameter are related, removing can be considered as renaming to null. So the syntax and the implementation can be similar.
serhiy-storchaka commentedon Aug 5, 2026
I propose syntax to support parameter aliases:
or
After adding support for that we only need a syntax to deprecate one of names -- this will cover renaming and deletion.
serhiy-storchaka commentedon Aug 5, 2026
I ruled out
[...]at the end of the line, but[...]at the beginning of the line does not have such issues.gh-108271, gh-108270: Argument Clinic: parameter aliases and deprecat…
pythongh-108271, pythongh-108270: Argument Clinic: parameter aliases …