argparse: fix inconsistency in `add_argument()` API when using positional argument with `dest=` parameter

Feature or enhancement

Proposal:

Current behaviour is ugly and inconsistent between options and positional arguments:

parser.add_argument("--option-foo",    dest="my_foo_option_var")
parser.add_argument(metavar="BAR_ARG", dest="my_bar_arg_var")
# or even worse
parser.add_argument("my_bar_arg_var",  metavar="BAR_ARG")

Proposed change streamlines the library API

parser.add_argument("--option-foo", dest="my_foo_option_var")
parser.add_argument("BAR_ARG",      dest="my_bar_arg_var")

I think a small patch could fix this without breaking any existing code.

--- a/Lib/argparse.py
+++ b/Lib/argparse.py
@@ -1423,7 +1423,7 @@
     # =======================
     def add_argument(self, *args, **kwargs):
         """
-        add_argument(dest, ..., name=value, ...)
+        add_argument(arg, ..., name=value, ...)
         add_argument(option_string, option_string, ..., name=value, ...)
         """
 
@@ -1433,7 +1433,11 @@
         chars = self.prefix_chars
         if not args or len(args) == 1 and args[0][0] not in chars:
             if args and 'dest' in kwargs:
-                raise ValueError('dest supplied twice for positional argument')
+                if 'metavar' not in kwargs:
+                    kwargs['metavar'] = args[0]
+                else:
+                    raise ValueError('`arg` supplied with both `dest` and `metavar` for positional argument')
+                args = (kwargs.pop('dest'), )
             kwargs = self._get_positional_kwargs(*args, **kwargs)
 
         # otherwise, we're adding an optional argument

Has this already been discussed elsewhere?

This is a minor feature, which does not need previous discussion elsewhere

Links to previous discussion of this feature:

No response

Start in Lib/argparse.py at the add_argument entry point and review the current positional-argument handling against the proposal. Check the existing argparse tests and confirm that the new positional dest and metavar behavior works while existing forms remain compatible.