Introduce Parameter.deprecated + Command.deprecated message customization

[peacock0803sz]

Implement of #2263, Showing deprecation message with --help for @click.option

• fixes Mark parameter as deprecated #2263

Checklist:

• Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
• Add or update relevant docs, in the docs folder and in code.
• Add an entry in CHANGES.rst summarizing the change and linking to the issue.
• Add .. versionchanged:: entries in any relevant code docs.
• Run pre-commit hooks and fix any issues.
• Run pytest and tox, no tests failed.

[saroad2]

Hello @peacock0803sz , thanks for the PR and sorry for the long delay.

This seems fine to me, and very helpful for user to use click in a backward compatible way.

However, this PR lacks a very important compnant: Once someone does use a deprecated option, a warning should be printed. This is done today with deprecated commands. You can look here for inspiration.

Please fix this issue before I review this PR again.

[AndreasBackx]

I just updated the PR and made the following changes:

• deprecated has been moved to Parameter meaning an Argument can also be deprecated now. This can be helpful when one wants to perhaps replace an argument with an option.
  • Parameters have an added ! in their usage to indicate that they're deprecated. Anyone know how to make this more clear? I kind of want to make it show up in red, but I'm unsure if that's entirely possible right now without issues.
• A warning is now shown when the parameter is used, though not when it's a default value.
• An error is shown (in debug mode) when deprecated=True and required=True. It would be silly to have a deprecated argument be required. How does one otherwise move away from it?
  • Also when deprecated=True and Option.prompt is truthy.
• Tests to cover these use cases.

I noticed that Option's constructor raises TypeErrors for bad values. Shouldn't those be ValueError?

I'm thinking it's a good idea to allow passing a str instead of solely a boolean to give the user some context. (Added)

[ThiefMaster]

What's the reason for disallowing prompt w/ deprecated args?

[AndreasBackx]

@ThiefMaster as with required=True. When setting deprecated=True, there needs to be an avenue for the user to move away from it. How can they move away when they will be automatically prompted for it?

Correct me if my understanding around the use of prompt is incorrect. I am not a frequent user of it.

[AndreasBackx]

Follow-up question: should Command.deprecated not also allow a string to be passed so a custom message can be printed?

Done

[ThiefMaster]

Ah yes, I thought it prompts for a value when specifying the option. But it prompts when the option is not provided so I guess it makes more sense to disallow it.

[AndreasBackx]

There seem to be no comments so I am merging this.