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

(cherry picked from commit 82cb7d4bf62041b75a08628baa1f9fe761fd6a79)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 32e5ab9fc23a923b0e8175869ac50e96dab2af1c..5d0a13e0c8f4f79f6c8f1f25ba45ec7c9e2941d9 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1269,6 +1269,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:
 
@@ -1664,6 +1668,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