[3.14] GH-59633: Clarify dest collisions in argparse docs (GH-150987) (#151194)

(cherry picked from commit 82cb7d4bf62041b75a08628baa1f9fe761fd6a79)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 4623a3747ae58304b48b8e03021db987603b28de..7508aea2aed0840970089b9b71f766a3c5c840cf 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1363,6 +1363,10 @@ 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_.
 
 .. _deprecated:
 
@@ -1758,6 +1762,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