argparse standard error usage for exit / error

[philiprowlands]

BPO	35533
Nosy	@vinayb21
PRs	Add documentation for exit() function #11622

^{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 2018-12-19.11:47:10.876>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'argparse standard error usage for exit / error'
updated_at = <Date 2019-02-08.05:44:01.649>
user = 'https://bugs.python.org/philiprowlands'

bugs.python.org fields:

activity = <Date 2019-02-08.05:44:01.649>
actor = 'paul.j3'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-12-19.11:47:10.876>
creator = 'philiprowlands'
dependencies = []
files = []
hgrepos = []
issue_num = 35533
keywords = ['patch']
message_count = 3.0
messages = ['332128', '334066', '335059']
nosy_count = 5.0
nosy_names = ['bethard', 'docs@python', 'paul.j3', 'philiprowlands', 'vinayb21']
pr_nums = ['11622']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35533'
versions = ['Python 3.7', 'Python 3.8']

Linked PRs

• GH-79714: Add mention of stderr for clarity to ArgumentParser.exit() #123932
• [3.13] GH-79714: Add mention of stderr for clarity to ArgumentParser.exit() (GH-123932) #124331
• [3.12] GH-79714: Add mention of stderr for clarity to ArgumentParser.… #124356

[philiprowlands]

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

[vinayb21]

Add documentation for exit() function

[paulj3]

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)".