[argparse] action='store_true' and action='store_false' are affected by argument_default

Documentation

While the docs seem to imply that False and True are always the defaults for the store_true and store_false actions respectively, that is only true if argument_default is not passed. This should be more clearly documented.

>>> import argparse
>>> parser = argparse.ArgumentParser(prog='baz', argument_default=argparse.SUPPRESS)
>>> parser.add_argument('-s', '--spam', action='store_true')
_StoreTrueAction(option_strings=['-s', '--spam'], dest='spam', nargs=0, const=True, default='==SUPPRESS==', type=None, choices=None, required=False, help=None, metavar=None, deprecated=False)
>>> parser.parse_args()
Namespace()
>>> parser.parse_args(['-s'])
Namespace(spam=True)

Linked PRs

I don't understand the problem here. The docs say:

For example, to globally suppress attribute creation on parse_args() calls, we supply argument_default=SUPPRESS:

So what is wrong here?

Maybe SUPPRESS was not a good example because it was explicitly mentioned in the argument_default reference. But the lines that confused me were elsewhere, in the actions reference (the precedence is not the most obvious):

'store_true' and 'store_false' - These are special cases of 'store_const' that respectively store the values True and False with default values of False and True:

@jonathandung

I think OP has a point that the precedence order is slightly ambiguous, but the initial example is confusing.

I would express it thusly:

import argparse
p = argparse.ArgumentParser(argument_default=1)
p.add_argument("-a", default=2)
p.add_argument("-b", action='store_true')

p.parse_args([])  # Namespace(a=2, b=1)

-a gets 2 (an explicit default) , but -b gets 1 (argument_default), because the precedence order is default > argument_default > action.

I don't see a clear way to improve the docs. Making them longer is likely to make things confusing without really clarifying anything for the typical reader. @jonathandung, do you have something particular in mind?

"... with default values of False and True, unless overridden by argument_default."

This should not be only for store_true/store_false. We should document the priority order first.

Unless overridden by argument_default or default.
That doesn't fit comfortably if you look at where it is in the page. It's not the end of a sentence: that phrase precedes a colon, followed by example usage.

I'm not a huge fan of this method of clarifying. It puts a lot of detail into the same text that a new reader is relying on to form their initial understanding.

If there is to be a clarification, I'd rather it be about the general interplay of default, argument_default, Action, and potentially other values like type.

That doesn't fit comfortably if you look at where it is in the page.

Agreed. I think the precedence of the various ways to declare defaults deserves its own section, as I am by no means the only one to have been confused by the documentation (see, for example, #69786).

pythongh-155403: Simplify default precedence explanation

pythongh-155403: Link directly to default documentation

pythongh-155403: Clarify when boolean defaults apply

pythongh-155403: Remove repeated default explanation

pythongh-155403: Clarify argparse default precedence

Merge branch 'main' into pythongh-155403-argparse-default-precedence

gh-155403: Clarify argparse `default` precedence (#160064)

[3.14] gh-155403: Clarify argparse `default` precedence (GH-160064) (#…

[3.15] gh-155403: Clarify argparse `default` precedence (GH-160064) (#…

Navigation Menu

Repository navigation

[`argparse`] `action='store_true'` and `action='store_false'` are affected by `argument_default` #155403

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

[argparse] action='store_true' and action='store_false' are affected by argument_default #155403

Description

Documentation

Linked PRs

Activity

picnixz commented on Aug 9, 2026

jonathandung commented on Aug 10, 2026

sirosen commented on Aug 14, 2026

jonathandung commented on Aug 15, 2026

picnixz commented on Aug 15, 2026

sirosen commented on Aug 15, 2026

jonathandung commented on Aug 15, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

[`argparse`] `action='store_true'` and `action='store_false'` are affected by `argument_default` #155403