GH-59633: Clarify dest collisions in argparse docs (#150987)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 4c588d447a9a7cf030f87a54733c0451dacb9e57..e4a5f4d109b4992c62fccb897ab272781dd34f8c 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1372,6 +1372,11 @@ behavior::
    >>> parser.parse_args('--foo XXX'.split())
    Namespace(bar='XXX')
 
+Multiple arguments may share the same ``dest``.  By default, the value from the
+last such argument given on the command line wins.  Use ``action='append'`` to
+collect values from all of them into a list instead.  For conflicting *option
+strings* rather than ``dest`` names, see conflict_handler_.
+
 .. versionchanged:: 3.15
    Single-dash long option now takes precedence over short options.
 
@@ -1780,6 +1785,11 @@ Subcommands
    present, and when the ``b`` command is specified, only the ``foo`` and
    ``baz`` attributes are present.
 
+   If a subparser defines an argument with the same ``dest`` as the parent
+   parser, the two share a single namespace attribute, so the parent's value
+   won't be retained. Users should give them  distinct ``dest`` values to
+   keep both.
+
    Similarly, when a help message is requested from a subparser, only the help
    for that particular parser will be printed.  The help message will not
    include parent parser or sibling parser messages.  (A help message for each