classification
Title: argparse standard error usage for exit / error
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: bethard, docs@python, paul.j3, philiprowlands, vinayb21
Priority: normal Keywords: patch

Created on 2018-12-19 11:47 by philiprowlands, last changed 2019-02-08 05:44 by paul.j3.

Pull Requests
URL Status Linked Edit
PR 11622 vinayb21, 2019-01-19 17:52
Messages (3)
msg332128 - (view) Author: Philip Rowlands (philiprowlands) Date: 2018-12-19 11:47
Because error() mentions standard error and exit() does not, I assumed exit() did not use stderr, but it does.

Please mention standard error in the description of exit().

Relevant code at:
https://github.com/python/cpython/blob/3.7/Lib/argparse.py#L2482
msg334066 - (view) Author: Vinay Badhan (vinayb21) Date: 2019-01-19 17:52
Add documentation for exit() function
msg335059 - (view) Author: paul j3 (paul.j3) * (Python triager) Date: 2019-02-08 05:44
The proposed PR does not address this issue.  It just adds comments to the method code, which aren't really needed.  The method is short and obvious.  We don't need, at this time, to get into questions of whether comments in argparse.py conform to one of the PEPs.

All this issue needs is a change to the documentation.  Changing:

ArgumentParser.exit(status=0, message=None)

This method terminates the program, exiting with the specified status and, if given, it prints a message before that.

to:

ArgumentParser.exit(status=0, message=None)

This method terminates the program, exiting with the specified status and, if given, it prints a message to **standard error** before that.

While I'm not opposed to this change, I don't think it is important.  

The documentation makes these two methods public, which I believe serves two purposes:

- developers may want to issue their own `parser.error('...')` call, during post-parsing value checking, or issue their own `parser.exit()` call in a custom 'Action' class (much like what '_HelpAction' does).

- developers might want to modify one or both of these in a ArgumentParser subclass.  The unittesting code in argparse does this to capture and redirect errors.

In both cases I expect the developer will want to read the code as well as the documentation.  The fact that `exit()` uses stderr is quite obvious from the code.  

It's worth keeping in mind that the documentation never replicates the code.  For example, in this case the documentation says error(), "terminates the program with a status code of 2.", when what it really does is "terminates with a call to exit(status=2)".
History
Date User Action Args
2019-02-08 05:44:01paul.j3setmessages: + msg335059
2019-02-03 20:19:18paul.j3setnosy: + paul.j3
2019-01-19 17:52:24vinayb21setnosy: + vinayb21
messages: + msg334066
pull_requests: + pull_request11377

keywords: + patch
stage: patch review
2018-12-21 21:46:31terry.reedysetnosy: + bethard

versions: + Python 3.8
2018-12-19 11:47:10philiprowlandscreate