From: Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com>
Date: Sat, 26 Oct 2024 18:37:42 +0000 (+0200)
Subject: [3.12] gh-84545: Clarify the 'extend' action documentation in argparse (GH-125870... 
X-Git-Tag: v3.12.8~165
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=67b270142d58b8f9a64f8ae2b84a195e7e49adda;p=thirdparty%2FPython%2Fcpython.git

[3.12] gh-84545: Clarify the 'extend' action documentation in argparse (GH-125870) (GH-125965)

(cherry picked from commit da8673da362a2135cd621ac619d3aced6bb55100)

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
---

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index 87d9a45539a1..f72bd14d56fe 100644
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -690,6 +690,21 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args('--str --int'.split())
     Namespace(types=[<class 'str'>, <class 'int'>])
 
+* ``'extend'`` - This stores a list and appends each item from the multi-value
+  argument list to it.
+  The ``'extend'`` action is typically used with the nargs_ keyword argument
+  value ``'+'`` or ``'*'``.
+  Note that when nargs_ is ``None`` (the default) or ``'?'``, each
+  character of the argument string will be appended to the list.
+  Example usage::
+
+    >>> parser = argparse.ArgumentParser()
+    >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
+    >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
+    Namespace(foo=['f1', 'f2', 'f3', 'f4'])
+
+  .. versionadded:: 3.8
+
 * ``'count'`` - This counts the number of times a keyword argument occurs. For
   example, this is useful for increasing verbosity levels::
 
@@ -715,17 +730,6 @@ how the command-line arguments should be handled. The supplied actions are:
     >>> parser.parse_args(['--version'])
     PROG 2.0
 
-* ``'extend'`` - This stores a list, and extends each argument value to the
-  list.
-  Example usage::
-
-    >>> parser = argparse.ArgumentParser()
-    >>> parser.add_argument("--foo", action="extend", nargs="+", type=str)
-    >>> parser.parse_args(["--foo", "f1", "--foo", "f2", "f3", "f4"])
-    Namespace(foo=['f1', 'f2', 'f3', 'f4'])
-
-  .. versionadded:: 3.8
-
 Only actions that consume command-line arguments (e.g. ``'store'``,
 ``'append'`` or ``'extend'``) can be used with positional arguments.