GH-139067: Add example for argparse's append action

[moshekaplan]

Add an example for argparse's append action when a default value is provided. Fixes #139067.

---

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

• Issue: Clarify argparse's append action #139067

[StanFromIreland]

Do we really need it? Maybe both could be combined? The provided explanation is clear to me:

If the default value is non-empty, the default elements will be present
in the parsed value for the option, with any values from the
command line appended after those default values.

[moshekaplan]

The issue that drove this PR is that until I tested it, it was unclear that the default needed to be a list, and it couldn't be a single value. While this may be obvious in hindsight, I realized that a short example would entirely remove this source of confusion.

>>> import argparse
>>> parser = argparse.ArgumentParser()
>>> parser.add_argument('--foo', action='append', default='0')
_AppendAction(option_strings=['--foo'], dest='foo', nargs=None, const=None, default='0', type=None, choices=None, required=False, help=None, metavar=None)
>>> parser.parse_args('--foo 1 --foo 2'.split())
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "Python\Python311\Lib\argparse.py", line 1862, in parse_args
    args, argv = self.parse_known_args(args, namespace)
                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Python\Python311\Lib\argparse.py", line 1895, in parse_known_args
    namespace, args = self._parse_known_args(args, namespace)
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Python\Python311\Lib\argparse.py", line 2107, in _parse_known_args
    start_index = consume_optional(start_index)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "Python\Python311\Lib\argparse.py", line 2047, in consume_optional
    take_action(action, args, option_string)
  File "Python\Python311\Lib\argparse.py", line 1971, in take_action
    action(self, namespace, argument_values, option_string)
  File "Python\Python311\Lib\argparse.py", line 1043, in __call__
    items.append(values)
    ^^^^^^^^^^^^
AttributeError: 'str' object has no attribute 'append'

[StanFromIreland]

I see, you are correct, that should be clarified, but not as an example in my opinion as it is not very clear, and the text remains not clear.

[moshekaplan]

Unfortunately, there are several other parts of the argparse documentation which I think could be much clearer. Would it be valuable to make a separate PR for those?

[savannahostrowski]

Hey, thanks for the PR. I recommend adding a note in the describing paragraph that this should be a list instead. The code example is a bit duplicative as is.

If you have other ideas for documentation improvements, you're welcome to open issues so we can discuss the changes/areas where you think things could be clearer!

[moshekaplan]

@savannahostrowski : Sorry for the long follow-up on this. I've rewritten the description for append to what I think is slightly clearer. I've also removed the original example. Could you please take another look at this?

[savannahostrowski]

Thank you for this, this is much clearer!

[savannahostrowski]

@moshekaplan Was there an issue number for this? If not, could you please create one and relate the issue to this PR?

[moshekaplan]

@moshekaplan Was there an issue number for this? If not, could you please create one and relate the issue to this PR?

I'll create one now.

[moshekaplan]

I've documented the associated issue in #139067

[miss-islington-app]

Thanks @moshekaplan for the PR, and @savannahostrowski for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-139068 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-139069 is a backport of this pull request to the 3.13 branch.