From 34954b72a26ab64c4c856168c99fe0e6a4079ab3 Mon Sep 17 00:00:00 2001
From: Savannah Ostrowski <savannah@python.org>
Date: Wed, 21 Oct 2026 10:15:07 -0700
Subject: [PATCH] gh-155403: Clarify argparse default precedence

---
 Doc/library/argparse.rst | 14 ++++++++++----
 1 file changed, 10 insertions(+), 4 deletions(-)

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index b2318ddace8514b..99c308dbfcc4605 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -789,6 +789,9 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args('--foo --bar'.split())
     Namespace(foo=True, bar=False, baz=True)
 
+  These defaults apply when the options are absent. They can be overridden
+  by default_ or argument_default_.
+
 * ``'append'`` - This appends each argument value to a list.
   It is useful for allowing an option to be specified multiple times.
   If the default value is a non-empty list, the parsed value will start
@@ -1010,10 +1013,8 @@ default
 
 All optional arguments and some positional arguments may be omitted at the
 command line.  The ``default`` keyword argument of
-:meth:`~ArgumentParser.add_argument`, whose value defaults to ``None``,
-specifies what value should be used if the command-line argument is not present.
-For optional arguments, the ``default`` value is used when the option string
-was not present at the command line::
+:meth:`~ArgumentParser.add_argument` specifies what value should be used if the
+command-line argument is not present. For example::
 
    >>> parser = argparse.ArgumentParser()
    >>> parser.add_argument('--foo', default=42)
@@ -1022,6 +1023,11 @@ was not present at the command line::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+If ``default`` is omitted, :meth:`~ArgumentParser.add_argument` uses a value
+previously set for the dest_ with :meth:`~ArgumentParser.set_defaults`, or
+otherwise a non-``None`` argument_default_. If neither is set, the action's
+own default is used.
+
 If the target namespace already has an attribute set, the action *default*
 will not overwrite it::