Docstring of optparse.OptionParser incomplete

[sanders]

BPO	8158
Nosy	@orsenthil, @bitdancer, @sandrotosi
Files	issue8151-default.patch: Add 'description' to docstring of OptionParser class. issue8151-2.7.patch: Add 'description' to docstring of OptionParser class (2.7).

^{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 = <Date 2011-05-05.01:10:23.356>
created_at = <Date 2010-03-16.18:21:04.811>
labels = ['easy', 'type-bug', 'docs']
title = 'Docstring of optparse.OptionParser incomplete'
updated_at = <Date 2011-05-05.01:10:23.354>
user = 'https://bugs.python.org/sanders'

bugs.python.org fields:

activity = <Date 2011-05-05.01:10:23.354>
actor = 'r.david.murray'
assignee = 'docs@python'
closed = True
closed_date = <Date 2011-05-05.01:10:23.356>
closer = 'r.david.murray'
components = ['Documentation']
creation = <Date 2010-03-16.18:21:04.811>
creator = 'sanders'
dependencies = []
files = ['21486', '21487']
hgrepos = []
issue_num = 8158
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['101177', '101179', '101575', '117455', '117456', '130928', '130931', '132630', '132631', '135163', '135167', '135168']
nosy_count = 8.0
nosy_names = ['orsenthil', 'r.david.murray', 'sandro.tosi', 'sanders', 'docs@python', 'louiscipher', 'python-dev', 'jramnani']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue8158'
versions = ['Python 3.1', 'Python 2.7', 'Python 3.2', 'Python 3.3']

[sanders]

The class optparse.OptionParser supports a number of useful keyword arguments to the initializer, which are not documented in the Python Standard Library documentation, here: http://docs.python.org/library/optparse.html

This is a bit unfortunate. For example, I wanted to add a description to the top of my script's help page and a copyright notice to the foot, and was already about to subclass OptionParser in order to override the format_help method, when I noticed that optional keyword arguments 'description' and 'epilog' are provided for precisely this purpose.

The 'epilog' attribute is at least mentioned in the class's docstring, while the 'description' argument is completely undocumented. I doubt that this was done on purpose.

I'd suggest to go over the documentation page for optparse and fill in the missing bits; at minimum, list all keyword arguments to optparse.OptionParser.__init__.

[bitdancer]

Would you care to submit a patch? The docs are in the svn repository in the 'Doc' subdirectory. See http://www.python.org/dev for how to get a checkout and create a patch.

That said, note that 2.7/3.2 will have argparse, which is pretty much a superset of optparse and recommended for use instead of optparse, and it does document those options.

[bitdancer]

Senthil documented epilog in bpo-8209.

[sandrotosi]

Hello,
since 2.7 optparse is deprecated in favor of argparse: is this bug still worth to be fixed? If so, I can work on a patch for the doc.

Regards,
Sandro

[sandrotosi]

Sorry, I probably overlooked at the situation. After a quick chat with Antoine on IRC, it's clear optparse is here to stay for all the lifetime of 2.7 (quite a long and prosper, we hope :) so yes, it's worth work on its documentation, hence I'll start preparing a patch and I'll submit it asap.

Cheers,
Sandro

[jramnani]

I've read through the doc and the code. All keyword arguments for OptionParser.__init__() are in the documentation for branches 2.7 and default (as of ecc176488349).

Does that mean this issue can be closed?

[bitdancer]

It looks to me like description is still missing from the docstring, at least on python3 tip.

[jramnani]

You are correct.

I have added 'description' to the docstring of the OptionParser class for 2.7 and default (python3 tip).

Here is the patch for python3 tip.

[jramnani]

Attaching the same patch for 2.7.

[louiscipher]

Applied patch cleanly. Also the description reads clearly and makes sense.

[python-dev]

New changeset c13d2552eb51 by R David Murray in branch '2.7':
bpo-8158: add missing 'description' description to optparse docstring.
http://hg.python.org/cpython/rev/c13d2552eb51

New changeset f559b88bcaa0 by R David Murray in branch '3.1':
bpo-8158: add missing 'description' description to optparse docstring.
http://hg.python.org/cpython/rev/f559b88bcaa0

New changeset b4b0a1458638 by R David Murray in branch '3.2':
Merge bpo-8158: add missing 'description' description to optparse docstring.
http://hg.python.org/cpython/rev/b4b0a1458638

New changeset 2a403afc4a76 by R David Murray in branch 'default':
Merge bpo-8158: add missing 'description' description to optparse docstring.
http://hg.python.org/cpython/rev/2a403afc4a76

[bitdancer]

Thanks everyone.