argparse set_defaults

[daggaz]

Documentation

The documentation for set_defaults() in the argparse module states:

Note that parser-level defaults always override argument-level defaults

And gives the following snippet:

>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', default='bar')
>>> parser.set_defaults(foo='spam')
>>> parser.parse_args([])
Namespace(foo='spam')

However, swapping the order of add_argument() and set_defaults() gives a different result:

>>> parser = argparse.ArgumentParser()
>>> parser.set_defaults(foo='spam')
>>> parser.add_argument('--foo', default='bar')
>>> parser.parse_args([])
Namespace(foo='bar')

To me, the statement in the documentation implies that parser-level defaults take precedence over argument-level defaults, but that is not the case. In fact, they overwrite one another, and order is important.

Linked PRs

• GH-108009: Add clarification of parser and argument defaults in argparse docs #124154

[hpaulj]

This another of those cases where the docs don't capture all the nuances of the code.

set_defaults function sets (updates) the parser_defaults dict, but also sets the default attribute of any existing Action. Latter when defaults are added to the namespace, Action defaults are used (conditionally).

._defaults are conditionally added as a second step. I believe that's to insert defaults that aren't tied to any defined Action (such as documented use of set_defaults with subparsers). So if they differ, the Action default has priority over anything 'leftover' in ._defaults. (There's another issue about how SUPPRESS affects the action.)

The challenge when correcting the docs is to do so in way that doesn't confuse most readers. Most don't use set_defaults, so more details just add to an overwealming sense of complexity and confusion. Unless we can come up with a clear and concise wording, I'm not sure it's worth correcting this issue.