gh-155403: Document that store_true/store_false are affected by argument_default

[shoutoutuoadi325]

Issue

Issue #155403: The argparse documentation implies that store_true and store_false always have default values of False and True respectively, but this is only true when argument_default is not set. When argument_default=argparse.SUPPRESS is used, these defaults are also suppressed.

Reproduction

import argparse

# Without argument_default - defaults apply
parser1 = argparse.ArgumentParser()
parser1.add_argument('--spam', action='store_true')
print(parser1.parse_args([]))  # Namespace(spam=False)

# With argument_default=SUPPRESS - no attribute when flag not provided
parser2 = argparse.ArgumentParser(argument_default=argparse.SUPPRESS)
parser2.add_argument('--spam', action='store_true')
print(parser2.parse_args([]))  # Namespace() (no 'spam' attribute)

Fix

Updated the documentation to:

1. Clarify that the defaults mentioned are affected by argument_default
2. Added an example demonstrating the behavior with argument_default=SUPPRESS

Changes

• Updated Doc/library/argparse.rst to document the interaction between store_true/store_false actions and argument_default
• Added NEWS entry in Misc/NEWS.d/next/Documentation/

Testing

• All argparse tests pass (1966 tests)
• Verified documentation examples work correctly
• make patchcheck passes

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

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[Copilot]

Pull request overview

Updates the argparse documentation to clarify that the implicit defaults for action='store_true' / action='store_false' depend on the parser-wide argument_default setting (notably SUPPRESS), aligning the docs with actual behavior.

Changes:

• Document that store_true / store_false defaults are suppressed when argument_default=SUPPRESS.
• Add an example demonstrating the suppressed-default behavior.
• Add a documentation NEWS fragment for the change.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
Doc/library/argparse.rst	Clarifies and demonstrates how argument_default=SUPPRESS affects store_true/store_false defaults.
Misc/NEWS.d/next/Documentation/2026-08-09-12-00-00.gh-issue-155403.wX8kR2.rst	Adds a NEWS entry describing the documentation update.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3d4244626e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Mention only arguments registered on the second parser

The second example replaces parser and registers only foo and bar, so baz is not suppressed—it does not exist on this parser at all. This makes the new explanation factually misleading; either register baz again or state only that bar is suppressed.

Useful? React with 👍 / 👎.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #33977875 | 📁 Comparing 3d42446 against main (998b890)

  🔍 Preview build  

2 files changed

± library/argparse.html
± whatsnew/changelog.html