From e4b9fd544883b1a6aa044f5f5796c95f24a494b3 Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Mon, 30 Jun 2025 22:46:28 +0800 Subject: [PATCH 1/5] doc(argparse): fix description of BooleanOptionalAction --- Doc/library/argparse.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index a03d88092dbf1f..ea8b0fdf8e0ef3 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -839,15 +839,17 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args(['--version']) PROG 2.0 -Only actions that consume command-line arguments (e.g. ``'store'``, -``'append'`` or ``'extend'``) can be used with positional arguments. +Note that only actions that consume command-line arguments (e.g. ``'store'``, +``'append'`` or ``'extend'``) can be used with positional arguments. You may +also specify an arbitrary action by passing an :class:`Action` subclass or +other object that implements the same interface. .. class:: BooleanOptionalAction - You may also specify an arbitrary action by passing an :class:`Action` subclass or - other object that implements the same interface. The :class:`!BooleanOptionalAction` - is available in :mod:`!argparse` and adds support for boolean actions such as - ``--foo`` and ``--no-foo``:: + A subclass of :class:`Action` for handling boolean flags with positive + and negative options. Adding a single argument such as ``--foo`` automatically + creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and ``False`` + respectively:: >>> import argparse >>> parser = argparse.ArgumentParser() From 7157cd06cb002cbb1b64b643171195b2f01f7ac5 Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Tue, 1 Jul 2025 14:37:04 +0800 Subject: [PATCH 2/5] doc(argparse): tweak wording --- Doc/library/argparse.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index ea8b0fdf8e0ef3..68e9fa4cb7233d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -839,7 +839,7 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args(['--version']) PROG 2.0 -Note that only actions that consume command-line arguments (e.g. ``'store'``, +Only actions that consume command-line arguments (e.g. ``'store'``, ``'append'`` or ``'extend'``) can be used with positional arguments. You may also specify an arbitrary action by passing an :class:`Action` subclass or other object that implements the same interface. From b708956fe2a839afe14d58749f70864668b39019 Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Tue, 1 Jul 2025 14:52:25 +0800 Subject: [PATCH 3/5] doc(argparse): move BooleanOptionalAction to `Action classes` section --- Doc/library/argparse.rst | 29 ++++++++++++++--------------- 1 file changed, 14 insertions(+), 15 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 68e9fa4cb7233d..7d1d834beb4c59 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -844,21 +844,6 @@ Only actions that consume command-line arguments (e.g. ``'store'``, also specify an arbitrary action by passing an :class:`Action` subclass or other object that implements the same interface. -.. class:: BooleanOptionalAction - - A subclass of :class:`Action` for handling boolean flags with positive - and negative options. Adding a single argument such as ``--foo`` automatically - creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and ``False`` - respectively:: - - >>> import argparse - >>> parser = argparse.ArgumentParser() - >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction) - >>> parser.parse_args(['--no-foo']) - Namespace(foo=False) - - .. versionadded:: 3.9 - The recommended way to create a custom action is to extend :class:`Action`, overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` and :meth:`!format_usage` methods. You can also register custom actions using the @@ -1431,6 +1416,20 @@ this API may be passed as the ``action`` parameter to and return a string which will be used when printing the usage of the program. If such method is not provided, a sensible default will be used. +.. class:: BooleanOptionalAction + + A subclass of :class:`Action` for handling boolean flags with positive + and negative options. Adding a single argument such as ``--foo`` automatically + creates both ``--foo`` and ``--no-foo`` options, storing ``True`` and ``False`` + respectively:: + + >>> import argparse + >>> parser = argparse.ArgumentParser() + >>> parser.add_argument('--foo', action=argparse.BooleanOptionalAction) + >>> parser.parse_args(['--no-foo']) + Namespace(foo=False) + + .. versionadded:: 3.9 The parse_args() method ----------------------- From fbd30a51ce9de55bfc229212ef8b93f7a8e2a6fb Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Fri, 4 Jul 2025 03:23:36 +0800 Subject: [PATCH 4/5] doc(argparse): amend the description of action --- Doc/library/argparse.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 7d1d834beb4c59..76ed3c04871a38 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -839,10 +839,11 @@ how the command-line arguments should be handled. The supplied actions are: >>> parser.parse_args(['--version']) PROG 2.0 -Only actions that consume command-line arguments (e.g. ``'store'``, -``'append'`` or ``'extend'``) can be used with positional arguments. You may -also specify an arbitrary action by passing an :class:`Action` subclass or -other object that implements the same interface. +You may also specify an arbitrary action by passing an :class:`Action` subclass +(e.g. :class:`BooleanOptionalAction`) or other object that implements the same +interface. Only actions that consume command-line arguments (e.g. ``'store'``, +``'append'``, ``'extend'``, or custom actions with non-zero ``nargs``) can be used +with positional arguments. The recommended way to create a custom action is to extend :class:`Action`, overriding the :meth:`!__call__` method and optionally the :meth:`!__init__` and From 03b59ff99b9481255ba6dd0d46bc76e638efe9e5 Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Fri, 4 Jul 2025 03:44:16 +0800 Subject: [PATCH 5/5] doc(argparse): two empty line between sections --- Doc/library/argparse.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 76ed3c04871a38..f189f6b8fa8953 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1432,6 +1432,7 @@ this API may be passed as the ``action`` parameter to .. versionadded:: 3.9 + The parse_args() method -----------------------