classification
Title: Add "example" keyword argument to optparse constructor
Type: enhancement Stage:
Components: Library (Lib) Versions: Python 3.2
process
Status: closed Resolution: rejected
Dependencies: Superseder:
Assigned To: gward Nosy List: Mekk, bethard, eric.araujo, gward, rhettinger, waylonis
Priority: normal Keywords:

Created on 2009-07-09 23:54 by waylonis, last changed 2010-12-18 02:18 by gward. This issue is now closed.

Messages (10)
msg90364 - (view) Author: Daniel Waylonis (waylonis) Date: 2009-07-09 23:54
It's useful to see and example or two detailing how a program should be 
invoked and the expected results.

I'd like to add the "example" keyword which will be printed below the 
"options:" when the usage is displayed.  It would not be formatted like 
the "description" string.
msg90366 - (view) Author: Daniel Waylonis (waylonis) Date: 2009-07-10 00:01
Looking at the source, there's the undocumented "epilog" keyword, but it, 
unfortunately is automatically pushed through the formatter, which would 
not be desirable for the output.
msg93098 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2009-09-25 01:23
This seems like a reasonable request.
msg95472 - (view) Author: Marcin Kasperski (Mekk) Date: 2009-11-19 14:21
I found this bug while looking for suggestions how to add examples to
the optparse help call, but I feel there is a better and more general
solution - just provide some minimal formatting for description: treat
empty line as paragraph separator. Then I would be able to add example
or anything else to the description formatting it as necessary
msg95600 - (view) Author: Greg Ward (gward) (Python committer) Date: 2009-11-22 15:30
> but I feel there is a better and more general
> solution - just provide some minimal formatting for description: treat
> empty line as paragraph separator. Then I would be able to add example
> or anything else to the description formatting it as necessary

Agreed.  I have also been bitten by optparse munging paragraphs together
in the description, and it's annoying.  I *think* we could get away with
two simple rules:

  * blank lines separate paragraphs
  * indented lines don't get wrapped

Obviously no one wants to reinvent reStructuredText, but I think that
should do the trick.

If that works, I think the suggested 'examples' arg becomes unnecessary.
msg122623 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-28 04:18
This may be interesting for argparse too.
msg122642 - (view) Author: Steven Bethard (bethard) * (Python committer) Date: 2010-11-28 09:10
With argparse, you can specify formatter_class= RawDescriptionHelpFormatter and then format things however you want in the description.

http://docs.python.org/dev/library/argparse.html#formatter-class

So I think there's no need for this in argparse.
msg124118 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2010-12-16 09:15
The two principals on the two argument parsing modules both find this unnecessary.
msg124131 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-12-16 13:55
I understood Greg’s reply to mean that there was no need for an examples keyword if simple paragraph splitting was added.
msg124269 - (view) Author: Greg Ward (gward) (Python committer) Date: 2010-12-18 02:18
> I understood Greg’s reply to mean that there was no need for an examples 
> keyword if simple paragraph splitting was added.

Right, but optparse has been superseded by argparse.  So my opinion is even less important than it was before 2.7.
History
Date User Action Args
2010-12-18 02:18:46gwardsetnosy: gward, rhettinger, bethard, eric.araujo, waylonis, Mekk
messages: + msg124269
2010-12-16 13:55:50eric.araujosetnosy: gward, rhettinger, bethard, eric.araujo, waylonis, Mekk
messages: + msg124131
2010-12-16 09:15:47rhettingersetstatus: open -> closed

messages: + msg124118
resolution: rejected
nosy: gward, rhettinger, bethard, eric.araujo, waylonis, Mekk
2010-11-28 09:10:38bethardsetmessages: + msg122642
2010-11-28 04:18:52eric.araujosetnosy: + eric.araujo, bethard
messages: + msg122623
2009-11-22 15:30:19gwardsetmessages: + msg95600
2009-11-19 14:21:07Mekksetnosy: + Mekk
messages: + msg95472
2009-11-19 01:12:37rhettingersetassignee: rhettinger -> gward

nosy: + gward
2009-09-25 01:23:39rhettingersetassignee: rhettinger

messages: + msg93098
nosy: + rhettinger
2009-07-10 00:01:43waylonissetmessages: + msg90366
2009-07-09 23:54:19wayloniscreate