gh-132558: Improve argparse docs on combining type and choices
#133827
Conversation
argparse docs on combining type and choices
Doc/library/argparse.rst
Outdated
| 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_. |
There was a problem hiding this comment.
This should not be inbetween the choices notes.
There was a problem hiding this comment.
It was already with the choices documentation. Where would you move it to?
There was a problem hiding this comment.
You should move the text you added above it.
Doc/library/argparse.rst
Outdated
| Use of :class:`enum.Enum` is not recommended because it is difficult to | ||
| control its appearance in these messages. |
There was a problem hiding this comment.
I think it's previous place was fine, it continued naturally from the previous point.
| 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. | ||
|
|
There was a problem hiding this comment.
| 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 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. | |
| If you want *choices* to be compared against a formatted or transformed | |
| value, consider using a custom wrapper class for type_ that performs the | |
| conversion and formatting during parsing instead. | |
There was a problem hiding this comment.
@savannahostrowski The reason I included the line you suggest removing, was that during discussion on ODP, some people mentioned this specifically as advice. Also, in other places in the documentation of argparse, people recommend against making the type function do too much and limit it too simple types like float and int.
In general, the recommendation to not use type in this scenario seems sound. It leads to less lines of code in user space than creating a wrapper class as workaround. Also, when implementing wrapper classes I noticed that I typically had to cast the value from the wrapper back into the intended class. I would not want to point the user into the wrong direction without also pointing to a more pragmatic solution.
However, it is up to you if you think the last line is unacceptable.
This clarifies the documentation a bit to warn users of the potential side effects of using both
typeandchoiceson an action. It also suggests that it is better in those cases to do type conversion in application code.choiceswithtype#132558📚 Documentation preview 📚: https://cpython-previews--133827.org.readthedocs.build/