Repository navigation
Missing documentation for argparse.ArgumentTypeError #64238
Description
| BPO | 20039 |
|---|---|
| Nosy | @nchammas, @rahul-kumi, @ukarroum |
| PRs |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2013-12-21.10:40:25.122>
labels = ['type-feature', 'docs']
title = 'Missing documentation for argparse.ArgumentTypeError'
updated_at = <Date 2022-02-04.07:08:15.442>
user = 'https://bugs.python.org/arnaut-billings'bugs.python.org fields:
activity = <Date 2022-02-04.07:08:15.442>
actor = 'ukarroum'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2013-12-21.10:40:25.122>
creator = 'arnaut-billings'
dependencies = []
files = []
hgrepos = []
issue_num = 20039
keywords = ['patch']
message_count = 5.0
messages = ['206723', '206768', '206783', '327986', '363839']
nosy_count = 7.0
nosy_names = ['bethard', 'docs@python', 'paul.j3', 'arnaut-billings', 'nchammas', 'rahul-kumi', 'ukarroum']
pr_nums = ['31125']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue20039'
versions = ['Python 3.3']
Activity
arnaut-billings commentedon Dec 21, 2013
There is no documentation for argparse.ArgumentTypeError:
http://docs.python.org/3/library/unittest.html
Though it does appear in an example and its usage is simple enough to decipher what it means, it would none the less look more professional if there was formal documentation for it. Not only on what it is, but when it should actually be used, etc...
paulj3 commentedon Dec 21, 2013
In argparse.py the status of ArgumentTypeError is ambiguous.
ArgumentError is listed as a public class, ArgumentTypeError is not. It also says 'All other classes in this module are considered implementation details.'
ArgumentTypeError is a subclass of Exception (with no added functionality).
ArgumentTypeError is raised only once, in the FileType class (which is both a scripting convenience and example of a custom type). As you note it is also used in the documentation example. There is also one such example in test_argparse.py.
It is caught once, where it is converted into an ArgumentError. It is handled much like a ValueError or TypeError - except that its message is passed through unchanged.
In http://bugs.python.org/issue13824 I use it several times in the FileContext class for just this reason.
In fact ArgumentTypeError could be documented as a footnote to the
typeblock, saying to the effect: 'An ArgumentTypeError may be raised (instead of a ValueError or TypeError) to produce a custom error message.'Normally an ArgumentTypeError is not passed back to the user code, consistent with the claim that it is not public.
--------------
Along the same line, should ArgumentError be documented better? Currently it is just mentioned at the end, as a replacement for an optparse error class.
As best I can tell, the user code will only see an ArgumentError if the ArgumentParser.error method is customized. Otherwise that error is caught and converted into a system exit. Maybe the
errorparagraph in the documentation should get a sentence about ArgumentError.In test_argparse.py, ArgumentError is used extensively (with a custom error method).
arnaut-billings commentedon Dec 21, 2013
It seems what you're saying is that the ArgumentTypeError class should not be public, but being able to raise is should be public. If that's the case, I think it would be more clear to have an argparse.raiseArgumentTypeError method and document when it should be used.
If such classes are meant to be private, why not prepend their names with an underscore and remove them from the __all__ list? (I thought a leading underscore meant that a module level variable was private to that module.)
paulj3 commentedon Oct 18, 2018
A related closed request: https://bugs.python.org/issue30220
that wants to test ValueError for non-generic message, instead of using ArgumentTypeError.
nchammas commentedon Mar 10, 2020
Just a note that I also went looking for the docs for argparse.ArgumentTypeError after coming across it in this (highly viewed) post:
https://stackoverflow.com/a/14117511/877069
slateny commentedon Nov 19, 2023
Added to
argparseby #103289