Skip to content

Argument Clinic: add support for deprecating positional use of parameters #95065

Closed
Closed
Argument Clinic: add support for deprecating positional use of parameters#95065
Labels
topic-argument-clinictype-featureA feature request or enhancement

Description

@erlend-aasland
erlend-aasland
opened on Jul 20, 2022

Feature or enhancement

Suggesting to add syntax for producing deprecation warnings for positional use of optional parameters.

I made a proof-of-concept patch for this where I introduced a new special symbol x. Example use:

/*[clinic input]
mod.func
    stuff: object
    /
    x
    optarg: int = 128

This will then generate code that emits a DeprecationWarning if optarg is passed as a positional argument, but not if it is passed as a keyword.

We can use this feature to introduce deprecation warnings for parameters that will become keyword-only in future releases. When the deprecation period is done, we can simply replace the x with *, to really make the optional params keyword-only.

Pitch

Quoting @serhiy-storchaka, in issue #93057:

It is recommended to make optional rarely used arguments keyword-only. I do not think it will break much code, but we need a deprecation period for this.

The problem is that sqlite3.connect() was converted to Argument Clinic, and it was much easier to add deprecation warning in the old code.

Previous discussion

Linked PRs

Activity

  1. erlend-aasland
    added
    type-featureA feature request or enhancement
    topic-argument-clinic
    on Jul 20, 2022

  2. erlend-aasland commented on Jul 20, 2022

    @erlend-aasland
    erlend-aasland
    on Jul 20, 2022
    ContributorAuthor

    If there is sufficient support for this feature, I'll create a PR.

  3. erlend-aasland commented on Jul 22, 2022

    @erlend-aasland
    erlend-aasland
    on Jul 22, 2022
    ContributorAuthor

    If there is sufficient support for this feature, I'll create a PR.

    Two Three thumbs up; I'll create the PR 😎

  4. zware commented on Jul 22, 2022

    @zware
    zware
    on Jul 22, 2022
    Member

    I'd suggest to go full warnings._deprecated on it, with an error if the specified removal version has reached beta without the change.

  5. erlend-aasland commented on Jul 23, 2022

    @erlend-aasland
    erlend-aasland
    on Jul 23, 2022
    ContributorAuthor

    I'd suggest to go full warnings._deprecated on it, with an error if the specified removal version has reached beta without the change.

    Maybe I'm misunderstanding you, but that would imply extending the new syntax with optional deprecated version and removed version fields, right?

  6. serhiy-storchaka commented on Jul 23, 2022

    @serhiy-storchaka
    serhiy-storchaka
    on Jul 23, 2022
    Member

    I think it is great idea, although I would like to use something more distinguishable and searchable than just x.

    We should consider more general problem, when we want to change parameters in incompatible way.

    1. Turn positional-or-keyword parameters into keyword-only parameters. A directive which means "the following positional-or-keyword parameters will be keyword-only parameters in future".
    2. Turn positional-or-keyword parameters into positional-only parameters. A directive which means "the preceding positional-or-keyword parameters will be positional-only parameters in future".
    3. Remove parameter. For some converters we can use NULL or something like to distinguish absent argument, but for others all values after conversion are correct, so we need a special directive for this. When remove positional-only or positional-or-keyword parameter, all following parameters should become keyword-only parameters.
    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.

    There may be other possible incompatible changes, but these four are common.

  7. erlend-aasland commented on Jul 23, 2022

    @erlend-aasland
    erlend-aasland
    on Jul 23, 2022
    ContributorAuthor

    I think it is great idea, although I would like to use something more distinguishable and searchable than just x.

    Thanks for the support! I'm up for any other symbol; x was just the first thing that popped up in my head when I did the first proof-of-concept implementation. OTOH, * and / are not very searchable either.

    We should consider more general problem, when we want to change parameters in incompatible way. [...]

    There may be other possible incompatible changes, but these four are common.

    +1 However, I think we should create separate issues for each feature :)

  8. terryjreedy
    added this to IDLE Issues and removed this from IDLE Issueson Jul 23, 2022
  9. erlend-aasland
    added
    triagedThe issue has been accepted as valid by a triager.
    on Jul 25, 2022

  10. hauntsaninja commented on Dec 1, 2022

    @hauntsaninja
    hauntsaninja
    on Dec 1, 2022
    Contributor

    Thanks for suggesting this! This would be nice, e.g. for #56166

    A quick bikeshed, do we need to use a new symbol? Something like the following seems pretty readable:

    posonlyarg
/
futureposonlyarg
/-in-future
posorkwarg
*-in-3.12
futurekwonlyarg
*
kwonlyarg

    Over here *-in-3.12 is a suggestion for how we could specify we want warnings._deprecated semantics.

  11. erlend-aasland commented on Dec 2, 2022

    @erlend-aasland
    erlend-aasland
    on Dec 2, 2022
    ContributorAuthor

    do we need to use a new symbol?

    I don't know; I just picked that path, because it was very easy to implement as a proof of concept :)

    Regarding the proposed extended format: I'd replace the hyphens with single whitespace to make it more readable.

  12. erlend-aasland commented on Jan 2, 2023

    @erlend-aasland
    erlend-aasland
    on Jan 2, 2023
    ContributorAuthor

    cc. @colorfulappl: this might be of interest to you.

  13. erlend-aasland
    removed
    triagedThe issue has been accepted as valid by a triager.
    on Apr 29, 2023

  14. 18 remaining items

  15. erlend-aasland
    added 6 commits that reference this issue on Aug 8, 2023

    pythongh-95065: Argument Clinic: Add comment to preprocessor warning …

    064b1d6

    gh-95065: Argument Clinic: Add comment to preprocessor warning code (#…

    5df8b0d

    pythongh-95065: Argument Clinic: Add functional tests of deprecated p…

    803f991

    pythongh-95065: Produce nicer deprecation messages in Argument Clinic

    a40315d

    gh-95065: Produce nicer deprecation messages in Argument Clinic (#107808

    0a7f48b

    gh-95065: Argument Clinic: Add functional tests of deprecated positio…

    39ef93e
  16. serhiy-storchaka
    added 2 commits that reference this issue on Aug 19, 2023

    pythongh-95065, pythongh-107704: Argument Clinic: support multiple '/…

    a52192a

    gh-95065, gh-107704: Argument Clinic: support multiple '/ [from ...]'…

    60942cc

  17. serhiy-storchaka commented on Aug 21, 2023

    @serhiy-storchaka
    serhiy-storchaka
    on Aug 21, 2023
    Member

    @erlend-aasland, do you mind to create issues for other two problems mentioned in #95065 (comment)? I could do them, but I am not sure about syntax.

  18. erlend-aasland commented on Aug 22, 2023

    @erlend-aasland
    erlend-aasland
    on Aug 22, 2023
    ContributorAuthor

    @erlend-aasland, do you mind to create issues for other two problems mentioned in #95065 (comment)? I could do them, but I am not sure about syntax.

    I'll get to it right away.

  19. erlend-aasland commented on Aug 22, 2023

    @erlend-aasland
    erlend-aasland
    on Aug 22, 2023
    ContributorAuthor

    I think we can close this now. The only thing missing is the preprocessor tests; I'm not sure it is worth it to add all the boilerplate code needed to get such tests up and running. If we feel it is needed, we can create a follow-up issue for that particular item, but I don't think it should keep blocking the resolution of this issue.

  20. erlend-aasland
    closed this as completedon Aug 22, 2023

  21. erlend-aasland commented on Aug 22, 2023

    @erlend-aasland
    erlend-aasland
    on Aug 22, 2023
    ContributorAuthor

    Thanks again, to everyone involved!

  22. AA-Turner
    added a commit that references this issue on Sep 13, 2023

    python/cpython#95065: Add Argument Clinic support for deprecating pos…

    eec5f46
  23. erlend-aasland
    added a commit that references this issue on Sep 26, 2023

    python/cpython#95065: Add Argument Clinic support for deprecating pos…

    62b9d34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    topic-argument-clinictype-featureA feature request or enhancement

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions