gh-59330: Improve error message for dest= for positionals (GH-125215)

Also improve the documentation. Specify how dest and metavar are derived
from add_argument() positional arguments.

Co-authored-by: Simon Law <sfllaw@sfllaw.ca>

1 files changed, 19 insertions, 0 deletions

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index d337de8..19f8320 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -636,6 +636,25 @@ be positional::
    usage: PROG [-h] [-f FOO] bar
    PROG: error: the following arguments are required: bar
 
+By default, argparse automatically handles the internal naming and
+display names of arguments, simplifying the process without requiring
+additional configuration.
+As such, you do not need to specify the dest_ and metavar_ parameters.
+The dest_ parameter defaults to the argument name with underscores ``_``
+replacing hyphens ``-`` . The metavar_ parameter defaults to the
+upper-cased name. For example::
+
+   >>> parser = argparse.ArgumentParser(prog='PROG')
+   >>> parser.add_argument('--foo-bar')
+   >>> parser.parse_args(['--foo-bar', 'FOO-BAR']
+   Namespace(foo_bar='FOO-BAR')
+   >>> parser.print_help()
+   usage:  [-h] [--foo-bar FOO-BAR]
+
+   optional arguments:
+    -h, --help  show this help message and exit
+    --foo-bar FOO-BAR
+
 
 .. _action: