Repository navigation
Argument Clinic: add support for renaming a parameter #108271
Description
Activity
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:func: char as c rename ch in 3.14: intSomething like this would be cleaner:
func: char as c: int # rename to ch in 3.14Here's another alternative, which require changes to
state_parameter():func: @rename to ch in 3.14 char as c: intAn
betteralternative can be to add that support toCConverter:func: char as c: int(rename=("ch", 3.14)I considered similar variants:
- Special comment or
[...]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. - Decorator-like directive. There is a precedence of using decorator-like directives (from
@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 useinstead of@from 3.14 ** [from 3.14] - As keyword argument to converter , like
unused=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?
- Special comment or
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.
I worry that the decorator variant will be too complex for little gain. I agree it also looks weird.
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.
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.
Reacted by Gregory P. SmithI propose syntax to support parameter aliases:
func: name1: object = None name2 as name1: object = Noneor
func: name1 as name: object = None name2 as name: object = NoneAfter adding support for that we only need a syntax to deprecate one of names -- this will cover renaming and deletion.
I ruled out
[...]at the end of the line, but[...]at the beginning of the line does not have such issues.
Originally posted by @serhiy-storchaka in #95065 (comment):
Linked PRs