[Python-checkins] bpo-38843: Document behavior of default when the attribute is already set (GH-23653)

[rhettinger]

https://github.com/python/cpython/commit/752cdf21eb2be0a26ea6a34a0de33a458459aead
commit: 752cdf21eb2be0a26ea6a34a0de33a458459aead
branch: master
author: Raymond Hettinger <rhettinger at users.noreply.github.com>
committer: rhettinger <rhettinger at users.noreply.github.com>
date: 2020-12-06T18:29:08-08:00
summary:

bpo-38843: Document behavior of default when the attribute is already set (GH-23653)

files:
M Doc/library/argparse.rst

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index a32b99901a7b4..02cd70f4f71cd 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -696,7 +696,7 @@ The add_argument() method
    * const_ - A constant value required by some action_ and nargs_ selections.
 
    * default_ - The value produced if the argument is absent from the
-     command line.
+     command line and if it is absent from the namespace object.
 
    * type_ - The type to which the command-line argument should be converted.
 
@@ -1006,6 +1006,14 @@ was not present at the command line::
    >>> parser.parse_args([])
    Namespace(foo=42)
 
+If the target namespace already has an attribute set, the action *default*
+will not over write it::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> parser.add_argument('--foo', default=42)
+   >>> parser.parse_args([], namespace=argparse.Namespace(foo=101))
+   Namespace(foo=101)
+
 If the ``default`` value is a string, the parser parses the value as if it
 were a command-line argument.  In particular, the parser applies any type_
 conversion argument, if provided, before setting the attribute on the