Argument Clinic: add support for renaming a parameter

[erlend-aasland]

Originally posted by @serhiy-storchaka in #95065 (comment):

4. 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.

[erlend-aasland]

Brainstorming regarding syntax, my first thought would be to modify parse_parameter(). Currently, we support the as keyword, 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 rename char as ch:

func:
    char as c rename ch in 3.14: int

Something like this would be cleaner:

func:
    char as c: int  # rename to ch in 3.14

Here's another alternative, which require changes to state_parameter():

func:
    @rename to ch in 3.14
    char as c: int

[erlend-aasland]

An better alternative can be to add that support to CConverter:

func:
    char as c: int(rename=("ch", 3.14)

[serhiy-storchaka]

I considered similar variants:

1. 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.
2. Decorator-like directive. There is a precedence of using decorator-like directives (from @classmethod to @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 use

   @from 3.14
   *
   

   instead of

   * [from 3.14]
   

3. 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?

[erlend-aasland]

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]

I worry that the decorator variant will be too complex for little gain. I agree it also looks weird.

[gpshead]

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) = NULL

style.

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]

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 like string is 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.