gh-110131: Document how a non-empty default works with append and extend

[v0ropaev]

Closes #110131.

@serhiy-storchaka already settled what this is:

the behavior is correct and pretty straightforward. Reclassified this issue as the documentation issue.

So this only touches the docs. Two things were off.

The append section explains that a non-empty default is kept and command-line values are appended after it, but it says "the parsed value" without saying whose, which reads as if it were about the list being appended to rather than the option's final value. That now says "the parsed value for the option".

The extend section had no such note at all, even though it behaves identically:

>>> p.add_argument('--foo', action='extend', nargs='+', default=['0'])
>>> p.parse_args(['--foo', '1', '2'])
Namespace(foo=['0', '1', '2'])

Same shape as append, and the surprise in the issue is the same one, so the same note now appears there.

A test pins both, since the whole point is that the documented behaviour is the real one and nobody had written it down.

./python.exe -m test test_argparse is 1,978 passing. Docs plus one test, no behaviour change, so no news entry.

• Issue: Argparse: "Default" interacts incorrectly/non-intuitively with action='append' and action='extend' #110131

[bedevere-app]

Most changes to Python require a NEWS entry. Add one using the blurb_it web app or the blurb command-line tool.

If this change has little impact on Python users, wait for a maintainer to apply the skip news label instead.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #34768928 | 📁 Comparing 844bb63 against main (b954645)

  🔍 Preview build  

7 files changed · ± 7 modified

± Modified

• c-api/init_config.html
• c-api/interp-lifecycle.html
• c-api/slice.html
• howto/free-threading-python.html
• library/argparse.html
• whatsnew/3.16.html
• whatsnew/changelog.html

[savannahostrowski]

We probably want to update this to show the behaviour with a non-empty default, since that's what we're documenting here.

[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.

[v0ropaev]

Both done. Test is gone, and the extend example now has a second block with a non-empty default.

>>> parser.add_argument("--foo", action="extend", nargs="+", type=str,
...                     default=["d1"])
>>> parser.parse_args(["--foo", "f1", "f2"])
Namespace(foo=['d1', 'f1', 'f2'])

Docs only now.

[savannahostrowski]

Can we keep it to one example for extend? I think the new one you've added covers our bases and we can remove the old one.

[v0ropaev]

Done, one example now. I folded the repeated --foo from the old one into it so that part isn't lost.

>>> parser.add_argument("--foo", action="extend", nargs="+", type=str,
...                     default=["d1"])
>>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
Namespace(foo=['d1', 'f1', 'f2', 'f3', 'f4'])