Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Mark parameter as deprecated #2263

Open
Tracked by #2789
stmlange opened this issue Apr 28, 2022 · 5 comments · May be fixed by #2271
Open
Tracked by #2789

Mark parameter as deprecated #2263

stmlange opened this issue Apr 28, 2022 · 5 comments · May be fixed by #2271
Assignees
@peacock0803sz
Milestone
8.2.0

Comments

@stmlange
Copy link

Thanks for this great project!
Perhaps it's just me who feels that it is rather cumbersome mark a single parameter as deprecated (the closet I found was https://stackoverflow.com/a/50402799). Is there perhaps a more official method to mark a single parameter as deprecated?
That would somewhat be similar to #1507.

Possible scenarios:

  • the parameter was renamed (e.g. a previous version was using --name as option, but now a dev want's to make sure it's the --sur-name.
  • the parameter is not needed anymore

Perhaps as an example consider:

import click

@click.command()
@click.option('--count', default=1, help='Number of greetings.')
@click.option('--name', prompt='Your name',
              help='The person to greet.')
def hello(count, name):
    """Simple program that greets NAME for a total of COUNT times."""
    for x in range(count):
        click.echo(f"Hello {name}!")

if __name__ == '__main__':
    hello()

and I want to rename --count to --greetings-count.
However I don't want to remove --count instantly, instead when users use --count prompt a message that they should use the new --greetings-count. The usage of --count and --greetings-count should be forbidden.

Thanks.
@peacock0803sz
Copy link

I'll work on this

@peacock0803sz
Copy link

@davidism I just implemented to show the message with --help.
Is it better to show same message running without --help?

@peacock0803sz peacock0803sz linked a pull request May 2, 2022 that will close this issue
Open
6 tasks
@adam-tokarski
Copy link

adam-tokarski commented Sep 30, 2022 •
edited
Loading

Hi, @peacock0803sz, what's the status of this issue?

You've linked that PR which has to fix the issue, but it's not clear how exactly - I mean the PR is rather about printing the thing out in help, right?

Is the more appropriate PR maybe already merged? Or it's not created yet?

edited:
Or rather that PR is only for covering deprecated attrs when used in custom Option classes like it is in linked example from SO?

@adam-tokarski adam-tokarski mentioned this issue Oct 1, 2022
Merged
1 task
@petrem petrem mentioned this issue Jan 5, 2023
Closed
@davidism davidism added this to the 8.2.0 milestone Jun 30, 2023
@thornto4 thornto4 mentioned this issue Mar 29, 2024
Merged
4 tasks
@wpietri
Copy link

wpietri commented Sep 16, 2024

Just wanted to share an example of the second use case, the one where an option is being removed. I changed the option line to look like this:

@click.option("--parallel", default=False, help="Obsolete flag, soon to be removed")

and then added this at the top of the command function:

    if parallel:
        click.echo("--parallel option unnecessary; benchmarks are now always run in parallel")

If click were to add a deprecated flag for options, I'd want to use it like this:

``
@click.option("--parallel", default=False, deprecated="--parallel option unnecessary; benchmarks are now always run in parallel")


That would a) remove the option from the help listing, and b) print the text I give it if somebody tries to call it. It should also skip as much validation as possible, so that users don't get negative feedback that doesn't really matter.

@wpietri wpietri mentioned this issue Sep 16, 2024
Merged
@AndreasBackx AndreasBackx mentioned this issue Oct 20, 2024
Open
39 tasks
@AndreasBackx
Copy link
Collaborator

AndreasBackx commented Nov 2, 2024 •
edited
Loading

Those that are interested in having this added to Click. I've updated #2271 to make it cover hopefully everything that is desired. The only thing I think of still adding is allowing the customisation of the deprecation message as highlighted by @wpietri. (Done) Any feedback on the PR is welcome.

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

@peacock0803sz peacock0803sz

Labels
None yet
Projects
None yet
Milestone
8.2.0
Development

Successfully merging a pull request may close this issue.

Introduce Parameter.deprecated + Command.deprecated message customization peacock0803sz/click
6 participants
@wpietri @davidism @AndreasBackx @adam-tokarski @stmlange @peacock0803sz