[3.13] gh-132558: Improve `argparse` docs on combining `type` and `choices` (GH-13382...

gh-132558: Improve `argparse` docs on combining `type` and `choices` (GH-133827)
(cherry picked from commit dd0840bf67e194ab64f340b8a7fbda24cb25e177)

Co-authored-by: Hans Then <hans.then@gmail.com>
Co-authored-by: Savannah Bailey <savannahostrowski@gmail.com>

diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst
index c470cd1adef8413a5c636e8762f47892d02f36a9..11b3b2a7e9b2f1dd4cd690b9d906e64c88df13b2 100644 (file)
--- a/Doc/library/argparse.rst
+++ b/Doc/library/argparse.rst
@@ -1058,16 +1058,21 @@ if the argument was not one of the acceptable values::
    game.py: error: argument move: invalid choice: 'fire' (choose from 'rock',
    'paper', 'scissors')
 
-Note that inclusion in the *choices* sequence is checked after any type_
-conversions have been performed, so the type of the objects in the *choices*
-sequence should match the type_ specified.
-
 Any sequence can be passed as the *choices* value, so :class:`list` objects,
 :class:`tuple` objects, and custom sequences are all supported.
 
 Use of :class:`enum.Enum` is not recommended because it is difficult to
 control its appearance in usage, help, and error messages.
 
+Note that *choices* are checked after any type_
+conversions have been performed, so objects in *choices*
+should match the type_ specified. This can make *choices*
+appear unfamiliar in usage, help, or error messages.
+
+To keep *choices* user-friendly, consider a custom type wrapper that
+converts and formats values, or omit type_ and handle conversion in
+your application code.
+
 Formatted choices override the default *metavar* which is normally derived
 from *dest*.  This is usually what you want because the user never sees the
 *dest* parameter.  If this display isn't desirable (perhaps because there are