From 6324868f99be9afb491824d8165458d73df85781 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 23 Oct 2024 11:52:52 +0300 Subject: [PATCH 1/2] gh-84545: Clarify the 'extend' action documentation in argparse --- Doc/library/argparse.rst | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index ef0db3e9789c98..3d2d9d7cb9d1e0 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -741,6 +741,21 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args('--str --int'.split()) Namespace(types=[, ]) +* ``'extend'`` - This stores a list, and appends each item from the multi-value + argument list to the list. + The ``'extend'`` action is typically used with the nargs_ keyword argument + value ``'+'`` or ``'*'``; + note that when nargs_ is ``None`` (by default) or ``'?'``, separate + characters 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:: @@ -766,17 +781,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. From 58241e8a3d7b4cc03a7c89ac37596cc02fed530f Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Fri, 25 Oct 2024 11:12:56 +0300 Subject: [PATCH 2/2] Update Doc/library/argparse.rst Co-authored-by: Savannah Ostrowski --- Doc/library/argparse.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 3d2d9d7cb9d1e0..9b860744eb1e15 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -741,12 +741,12 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args('--str --int'.split()) Namespace(types=[, ]) -* ``'extend'`` - This stores a list, and appends each item from the multi-value - argument list to the list. +* ``'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`` (by default) or ``'?'``, separate - characters of the argument string will be appended to the list. + 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()