gh-69223: Document that add_argument returns an Action object

[kovan]

Summary

• Documents that ArgumentParser.add_argument() returns an Action object
• This is useful for users who want to customize or inspect argument properties after creation

Test plan

• make check passed
• Documentation builds correctly

🤖 Generated with Claude Code

• Issue: argparse: document that add_argument returns an Action object #69223

---

📚 Documentation preview 📚: https://cpython-previews--144452.org.readthedocs.build/

[picnixz]

It cannot be used for customize the behavior. Action objects are immutable afterwards.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[kovan]

I tested this and Action objects are actually mutable, and modifications after add_argument() do take effect:

import argparse

# Modify help after adding
parser = argparse.ArgumentParser()
action = parser.add_argument('--foo', help='Original help')
action.help = 'Modified help'
parser.print_help()
# Shows: --foo FOO   Modified help

# Modify default after adding
parser2 = argparse.ArgumentParser()
action2 = parser2.add_argument('--bar', default=10)
action2.default = 99
args = parser2.parse_args([])
print(args.bar)  # Output: 99

# Modify choices after adding
parser3 = argparse.ArgumentParser()
action3 = parser3.add_argument('--choice', choices=['a', 'b'])
action3.choices = ['a', 'b', 'c']
args3 = parser3.parse_args(['--choice', 'c'])  # Works!

# Modify required after adding
parser4 = argparse.ArgumentParser()
action4 = parser4.add_argument('--opt')
action4.required = True
parser4.parse_args([])  # Raises error: --opt is required

All modifications (help, default, choices, required) take effect after the Action is added to the parser. Should I keep the original wording, or would you prefer a different phrasing?

[kovan]

I have made the requested changes; please review again

[bedevere-app]

Thanks for making the requested changes!

@picnixz: please review the changes made to this pull request.

[picnixz]

All modifications (help, default, choices, required) take effect after the Action is added to the parser. Should I keep the original wording, or would you prefer a different phrasing?

The question isn't whether it's possible to do it or not, but whether it's meant to be part of the public API or not. Argparse has lots of "public-looking interfaces" but not everything is meant to be public. The attributes may not even be themselves part of the public API (despite them not having underscores). So we should first decide whether Action is public and which part of Action is public.

cc @savannahostrowski