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.