Title: Docstring of optparse.OptionParser incomplete
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 3.3, Python 2.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, jramnani, louiscipher, orsenthil, python-dev, r.david.murray, sanders, sandro.tosi
Priority: normal Keywords: easy, patch

Created on 2010-03-16 18:21 by sanders, last changed 2011-05-05 01:10 by r.david.murray. This issue is now closed.

File name Uploaded Description Edit
issue8151-default.patch jramnani, 2011-03-31 02:46 Add 'description' to docstring of OptionParser class. review
issue8151-2.7.patch jramnani, 2011-03-31 02:48 Add 'description' to docstring of OptionParser class (2.7). review
Messages (12)
msg101177 - (view) Author: Simon Anders (sanders) Date: 2010-03-16 18:21
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:

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__.
msg101179 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-03-16 19:17
Would you care to submit a patch?  The docs are in the svn repository in the 'Doc' subdirectory.  See 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.
msg101575 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-03-23 11:56
Senthil documented epilog in issue 8209.
msg117455 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2010-09-27 18:02
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.

msg117456 - (view) Author: Sandro Tosi (sandro.tosi) * (Python committer) Date: 2010-09-27 18:13
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.

msg130928 - (view) Author: Jeff Ramnani (jramnani) * Date: 2011-03-14 23:15
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?
msg130931 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-03-14 23:31
It looks to me like description is still missing from the docstring, at least on python3 tip.
msg132630 - (view) Author: Jeff Ramnani (jramnani) * Date: 2011-03-31 02:46
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.
msg132631 - (view) Author: Jeff Ramnani (jramnani) * Date: 2011-03-31 02:48
Attaching the same patch for 2.7.
msg135163 - (view) Author: Bryce Verdier (louiscipher) Date: 2011-05-04 23:13
Applied patch cleanly. Also the description reads clearly and makes sense.
msg135167 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-05-05 01:09
New changeset c13d2552eb51 by R David Murray in branch '2.7':
#8158: add missing 'description' description to optparse docstring.

New changeset f559b88bcaa0 by R David Murray in branch '3.1':
#8158: add missing 'description' description to optparse docstring.

New changeset b4b0a1458638 by R David Murray in branch '3.2':
Merge #8158: add missing 'description' description to optparse docstring.

New changeset 2a403afc4a76 by R David Murray in branch 'default':
Merge #8158: add missing 'description' description to optparse docstring.
msg135168 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-05 01:10
Thanks everyone.
Date User Action Args
2011-05-05 01:10:23r.david.murraysetstatus: open -> closed
versions: + Python 3.3
messages: + msg135168

resolution: fixed
stage: needs patch -> resolved
2011-05-05 01:09:24python-devsetnosy: + python-dev
messages: + msg135167
2011-05-04 23:13:58louisciphersetnosy: + louiscipher
messages: + msg135163
2011-03-31 02:48:36jramnanisetfiles: + issue8151-2.7.patch

messages: + msg132631
2011-03-31 02:46:46jramnanisetfiles: + issue8151-default.patch
keywords: + patch
messages: + msg132630
2011-03-14 23:31:00r.david.murraysetnosy: orsenthil, r.david.murray, sandro.tosi, sanders, docs@python, jramnani
messages: + msg130931
2011-03-14 23:15:12jramnanisetnosy: + jramnani
messages: + msg130928
2010-11-19 15:30:46eric.araujosettitle: documentation of 'optparse' module incomplete -> Docstring of optparse.OptionParser incomplete
2010-11-19 14:33:45eric.araujosetkeywords: + easy
nosy: + docs@python, - georg.brandl
versions: - Python 2.6
2010-10-29 10:07:21adminsetassignee: georg.brandl -> docs@python
2010-09-27 18:13:15sandro.tosisetmessages: + msg117456
2010-09-27 18:02:03sandro.tosisetnosy: + sandro.tosi
messages: + msg117455
2010-03-29 19:36:39orsenthilsetnosy: + orsenthil
2010-03-23 11:56:51r.david.murraysetmessages: + msg101575
2010-03-16 19:17:31r.david.murraysetnosy: + r.david.murray

messages: + msg101179
versions: + Python 2.7, Python 3.2
2010-03-16 18:42:25brian.curtinsetpriority: normal
stage: needs patch
type: behavior
versions: + Python 3.1
2010-03-16 18:21:04sanderscreate