From 0bbe65c690602b82add79a080d1b199323945a28 Mon Sep 17 00:00:00 2001 From: Hans Then Date: Sat, 10 May 2025 10:27:41 +0200 Subject: [PATCH 1/4] Improve docs on *type* and *choices*. --- Doc/library/argparse.rst | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 8d0116d8c060b8..70bc2750966542 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1124,21 +1124,28 @@ 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. - 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 many choices), just specify an explicit metavar_. +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. This may interfere with +the display of the choices in usage, help and error messages, because the +*choices* may not be familiar to the end-user. + +Use of :class:`enum.Enum` is not recommended because it is difficult to +control its appearance in these messages. + +If you have to use both *type* and *choices* you can use a wrapper class +that formats the value after type conversion back to the vocabulary of the +end-user. However, it is usually easier to not specify *type* and perform +type conversion in application code. + .. _required: From 615e96f14a0e7d5fe1b48016fe5da43d9946c39f Mon Sep 17 00:00:00 2001 From: Hans Then Date: Sat, 10 May 2025 16:20:03 +0200 Subject: [PATCH 2/4] Updated after review comments --- Doc/library/argparse.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index 70bc2750966542..e9096ed6a78e16 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1127,10 +1127,8 @@ if the argument was not one of the acceptable values:: Any sequence can be passed as the *choices* value, so :class:`list` objects, :class:`tuple` objects, and custom sequences are all supported. -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 -many choices), just specify an explicit metavar_. +Use of :class:`enum.Enum` is not recommended because it is difficult to +control its appearance in usage, help, and error messages. 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* @@ -1138,14 +1136,16 @@ sequence should match the type_ specified. This may interfere with the display of the choices in usage, help and error messages, because the *choices* may not be familiar to the end-user. -Use of :class:`enum.Enum` is not recommended because it is difficult to -control its appearance in these messages. - If you have to use both *type* and *choices* you can use a wrapper class that formats the value after type conversion back to the vocabulary of the end-user. However, it is usually easier to not specify *type* and perform type conversion in 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 +many choices), just specify an explicit metavar_. + .. _required: From ecd4c5f2e4ce62567a6089a3ec7f24dd64cd9abe Mon Sep 17 00:00:00 2001 From: Hans Then Date: Tue, 1 Jul 2025 21:01:46 +0200 Subject: [PATCH 3/4] Update Doc/library/argparse.rst Co-authored-by: Savannah Bailey --- Doc/library/argparse.rst | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 deletions(-) diff --git a/Doc/library/argparse.rst b/Doc/library/argparse.rst index e9096ed6a78e16..44ae27349b671d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1130,17 +1130,14 @@ Any sequence can be passed as the *choices* value, so :class:`list` objects, Use of :class:`enum.Enum` is not recommended because it is difficult to control its appearance in usage, help, and error messages. -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. This may interfere with -the display of the choices in usage, help and error messages, because the -*choices* may not be familiar to the end-user. - -If you have to use both *type* and *choices* you can use a wrapper class -that formats the value after type conversion back to the vocabulary of the -end-user. However, it is usually easier to not specify *type* and perform -type conversion in application code. - +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 From 37274cc75f7bdc4e1b904e45191a5a1b4bb7a821 Mon Sep 17 00:00:00 2001 From: Hans Then Date: Tue, 1 Jul 2025 21:09:53 +0200 Subject: [PATCH 4/4] Fixed trailing space. --- 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 44ae27349b671d..d6e3d38d80442d 100644 --- a/Doc/library/argparse.rst +++ b/Doc/library/argparse.rst @@ -1130,13 +1130,13 @@ Any sequence can be passed as the *choices* value, so :class:`list` objects, 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* +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 +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