Allow to deprecate CLI arguments in argparse

[4383]

BPO	39467
Nosy	@rhettinger, @serhiy-storchaka, @4383, @shihai1991
PRs	bpo-39467: allow user to deprecate CLI arguments #18208

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

fields:

assignee = None
closed_at = None
created_at = <Date 2020-01-27.18:14:11.742>
labels = ['type-feature', 'library', '3.9']
title = 'Allow to deprecate CLI arguments in argparse'
updated_at = <Date 2020-03-03.12:57:11.058>
user = 'https://.com/4383'

bugs.python.org fields:

activity = <Date 2020-03-03.12:57:11.058>
actor = '4383'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Library (Lib)']
creation = <Date 2020-01-27.18:14:11.742>
creator = '4383'
dependencies = []
files = []
hgrepos = []
issue_num = 39467
keywords = ['']
message_count = 6.0
messages = ['360786', '360827', '360861', '361155', '361158', '363256']
nosy_count = 6.0
nosy_names = ['rhettinger', 'djarb', 'paul.j3', 'serhiy.storchaka', '4383', 'shihai1991']
pr_nums = ['18208']
priority = 'normal'
resolution = None
stage = ' review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue39467'
versions = ['Python 3.9']

Linked PRs

• gh-83648: Support deprecation of options, arguments and subcommands in argparse #114086
• gh-83648: Add missing deprecated arg in argparse.rst #115640
• gh-83648: Use versionadded in 'deprecated' description #121877
• [3.13] gh-83648: Use versionadded in 'deprecated' description (GH-121877) #121878

[4383]

Today it's not possible to deprecate CLI arguments designed with argparse, it could be useful to introduce deprecation feature in argparse to allow developers to inform their apps's users when an argument is planed to be removed in the future.

[rhettinger]

Will leave this open for a while so that many people can comment on the proposal before we act on it.

My initial take is:

• Having a way to deprecate seems useful.

• In practice, I haven't seen this done very much (in big tooling such as GCC perhaps, but everyday command-line tools don't seem to do this AFAICT).

• The warnings module is likely not the right implementation tool. The warnings module doesn't make as much sense for CLIs as it does for libraries. In particular, the warnings module is all about the ability of consumer code to filter, ignore, or escalate warnings. Also, we've so far been good about minimizing inter-module dependencies so that start-up time remains fast.

• The PR is aggressive in providing *deprecated*, *deprecated_reason*, and *deprecated_pending*. Perhaps a simpler hook or flag would suffice. The overall module API is already large enough to be a barrier to learning all the features.

• There is some question as to whether this belongs in argparse at all or whether it should be in downstream, post-parsing logic. For example:

  parser.add_argument('--throw', action='store_true',
  help = '(deprecated use "toss" instead) causes ball to move')
  ...
  args = parser.parse_args()
  if args.throw:
  print('"throw" has been deprecated, use "toss" instead',
  file=sys.stderr)

[4383]

First, thanks Raymond for your worth useful comment.

• Concerning the usage of the warning module what do you suggest to use then? To use "print"?

• Concerning "hook or flag" and the 3 new params in my PR, I think developers would appreciate to give a customized message to their users to inform that something will be removed for X reasons in the X release. The "pending" notion could be removed to keep the API lightweight, but with a well documented feature I don't seen terrible thing to understand here, maybe we need to put more effort on documentation and example (related to my changes).

• Concerning the fact to move deprecation management outside the declaration of the argument, I think it could be misleading to deprecate something in another place in the code, in other words it could introduce some more difficulties to understand the code. If the deprecation is declared in the argument declaration then all the info are centralized in one place and the parser know what to do in this situation.

Thoughts?

[shihai1991]

IMHO, cli should only support atomic function.What is atomic functin? (if downstream software's feature can not keep alive without upstream fucntion, it must be an atomic function).

[serhiy-storchaka]

In general I agree with Raymond, although I am warmer to this feature. And I think we should have a mechanism to deprecate not only options, but subcommands.

• The warnings module is used for warning about the use of API. It outputs the file and the line number of the caller to help the developer to fix his code. It allows to hide warnings from non-developers.

But warnings about deprecated CLI options and commands are purposed to be shown to the user of the CLI. They should not contain references to source code, because it is not the cause of the warning. The argparse module should use the same mechanism for warnings and errors: output to stderr.

• I do not understand the purpose of deprecated_pending. The feature is either deprecated or not. If it is deprecated, using it will produce a warning. If it is not deprecated -- no warning. In case of silent deprecation you can manually add a note in the help.

• I am not sure about deprecated_reason. We do not have a way to specify error message for standard errors (such like about missed required argument). If you need a custom warning, do not use the standard deprecation mechanism and emits a warning manually.

• As for moving the output of a warning to post-parsing logic, this is not always convenient and possible.

Let you have options "--verbose" which increments the verbosity level and "--verbosity-level" which sets it directly. One of them is deprecated. We can't easily use a post-parsing logic because they set the same destination. In this case we can workaround this by rewriting the logic to use different destinations, but there this is not always possible. Imagine you have options --add and --append which append the argument to the list and want to deprecate one of them. You can't use different lists and merge them in post-parsing, because the relative order matters.

[4383]

hello,

First thanks everyone to took time to discute about this proposal.

This topic is now opened since ~1 months so I don't think we will more feedback about this, then I will address all your comments in my changes soon to match an implementation more consensually based.