classification
Title: Docstring of optparse.OptionParser incomplete
Type: behavior Stage: committed/rejected
Components: Documentation Versions: Python 3.3, Python 3.2, Python 3.1, Python 2.7
process
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.

Files
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: 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__.
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 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.
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
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
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.

Cheers,
Sandro
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) 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.
http://hg.python.org/cpython/rev/c13d2552eb51

New changeset f559b88bcaa0 by R David Murray in branch '3.1':
#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 #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 #8158: add missing 'description' description to optparse docstring.
http://hg.python.org/cpython/rev/2a403afc4a76
msg135168 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-05-05 01:10
Thanks everyone.
History
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 -> committed/rejected
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