From: Savannah Ostrowski <savannah@python.org>
Date: Tue, 9 Jun 2026 17:26:45 +0000 (-0700)
Subject: [3.13] GH-59633: Clarify dest collisions in argparse docs (GH-150987) (#151196)
X-Git-Tag: v3.13.14~13
X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=848b9823bc667ff29fe5eb14e595b36feeec8311;p=thirdparty%2FPython%2Fcpython.git

[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 32e5ab9fc23a..5d0a13e0c8f4 100644
--- 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