From: Savannah Ostrowski <savannah@python.org>
Date: Tue, 9 Jun 2026 17:07:03 +0000 (-0700)
Subject: GH-59633: Clarify dest collisions in argparse docs (#150987)
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=82cb7d4bf62041b75a08628baa1f9fe761fd6a79;p=thirdparty%2FPython%2Fcpython.git

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

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 4c588d447a9a..e4a5f4d109b4 100644
--- 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