[3.13] gh-126676: Expand argparse docs for type=bool with warning and alternatives...

gh-126676: Expand argparse docs for type=bool with warning and alternatives (GH-146435)
(cherry picked from commit 80d0a85d969d305c7436dc54f8939d7b6f441b5f)

Co-authored-by: Joshua Swanson <22283299+joshuaswanson@users.noreply.github.com>
Co-authored-by: joshuaswanson <joshuaswanson@users.noreply.github.com>
Co-authored-by: Savannah Ostrowski <savannah@python.org>

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index c1df9c25450cca7af795e0290d47c37d3ba6766a..84a242d29a059afbc6ac279e192a49ab8bd36130 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1017,7 +1017,15 @@ User defined functions can be used as well:
 
 The :func:`bool` function is not recommended as a type converter.  All it does
 is convert empty strings to ``False`` and non-empty strings to ``True``.
-This is usually not what is desired.
+This is usually not what is desired::
+
+   >>> parser = argparse.ArgumentParser()
+   >>> _ = parser.add_argument('--verbose', type=bool)
+   >>> parser.parse_args(['--verbose', 'False'])
+   Namespace(verbose=True)
+
+See :class:`BooleanOptionalAction` or ``action='store_true'`` for common
+alternatives.
 
 In general, the ``type`` keyword is a convenience that should only be used for
 simple conversions that can only raise one of the three supported exceptions.

diff --git a/Misc/NEWS.d/next/Documentation/2026-03-25-00-00-00.gh-issue-126676.052336.rst b/Misc/NEWS.d/next/Documentation/2026-03-25-00-00-00.gh-issue-126676.052336.rst
new file mode 100644 (file)
index 0000000..d2e275f
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2026-03-25-00-00-00.gh-issue-126676.052336.rst
@@ -0,0 +1,2 @@
+Expand :mod:`argparse` documentation for ``type=bool`` with a demonstration
+of the surprising behavior and pointers to common alternatives.