PEP proposal optparse

[James]

Hi,

I would like to know your thoughts on a proposed change to optparse
that I have planned. It is possible to add default values to multiple
options using the set_defaults. However, when adding descriptions to
options the developer has to specify it in each add_option() call.
This results in unreadable code such as:

parser.add_option('-q', '--quiet' , action="store_false",
dest='verbose',
help = 'Output less information')
parser.add_option('-o', '--output' , type='string',
dest='castordir' , metavar='<DIR>' ,
help = 'specify the wanted CASTOR directory where to store the
results tarball')
parser.add_option('-r', '--prevrel' , type='string',
dest='previousrel' , metavar='<DIR>' ,
help = 'Top level dir of previous release for regression
analysis' )

The same code could become much more readable if there was an
equivalent method of set_defaults for the description/help of the
option. The same code could then become:

parser.set_description(
verbose = 'Output less information',
castordir = 'specify the wanted CASTOR directory where
to store the results tarball',
previousrel = 'Top level dir of previous release for
regression analysis')

parser.add_option('-q', '--quiet' , action="store_false",
dest='verbose')
parser.add_option('-o', '--output' , type='string',
dest='castordir' , metavar='<DIR>' )
parser.add_option('-r', '--prevrel' , type='string',
dest='previousrel' , metavar='<DIR>' )

Help descriptions can often be quite long and separating them in this
fashion would, IMHO, be desirable.

Kind Regards,
James Nicolson

 

[James Mills]

Hi James,

I can't say I really agree with your
proposal. I tend to keep the help
descriptions of my options short
and concise and to the point.

Also, one must use the language's
features (indentation) to your advantage,
as doing so ensure readability.

For example (from my bhimport tool):

<snippet>
def parse_options():
"""parse_options() -> opts, args

Parse any command-line options given returning both
the parsed options and arguments.
"""

parser = optparse.OptionParser(usage=USAGE, version=VERSION)

parser.add_option("", "--date-format",
action="store",type="str", default="%d/%m/%Y",
dest="dateFormat",
help="date format string")
parser.add_option("", "--time-format",
action="store", type="str", default="%H:%M:%S",
dest="timeFormat",
help="time format string")
parser.add_option("", "--datetime-format",
action="store", type="str", default="%H:%M:%S %d/%m/%Y",
dest="datetimeFormat",
help="datetime format string")

opts, args = parser.parse_args()

if len(args) < 2:
parser.print_help()
raise SystemExit, 1

return opts, args
</snippet>

As you can see (as long as you're
reading this in fixed-width fonts)
it _is_ very readable.

cheers
James

 

[James Nicolson]

Perhaps it is better to keep descriptions short and store longer
descriptions elsewhere, but there are many programs that have long
descriptions, for example try: ls --help (at least on my machine a lot
of these descriptions are quite long).

Hi James,

I can't say I really agree with your
proposal. I tend to keep the help
descriptions of my options short
and concise and to the point.

Also, one must use the language's
features (indentation) to your advantage,
as doing so ensure readability.

For example (from my bhimport tool):

<snippet>
def parse_options():
"""parse_options() -> opts, args

Parse any command-line options given returning both
the parsed options and arguments.
"""

parser = optparse.OptionParser(usage=USAGE, version=VERSION)

parser.add_option("", "--date-format",
action="store",type="str", default="%d/%m/%Y",
dest="dateFormat",
help="date format string")
parser.add_option("", "--time-format",
action="store", type="str", default="%H:%M:%S",
dest="timeFormat",
help="time format string")
parser.add_option("", "--datetime-format",
action="store", type="str", default="%H:%M:%S %d/%m/%Y",
dest="datetimeFormat",
help="datetime format string")

opts, args = parser.parse_args()

if len(args) < 2:
parser.print_help()
raise SystemExit, 1

return opts, args
</snippet>

As you can see (as long as you're
reading this in fixed-width fonts)
it _is_ very readable.

cheers
James

 

[Fredrik Lundh]

As you can see (as long as you're
reading this in fixed-width fonts)
it _is_ very readable.

given that it only relies on indentation from the left margin, it's no
less readable in a proportional font (unless you're using an font with
variable-width spaces, that is ;-).

</F>

 

[Steven D'Aprano]

Hi,

I would like to know your thoughts on a proposed change to optparse that
I have planned. It is possible to add default values to multiple options
using the set_defaults. However, when adding descriptions to options the
developer has to specify it in each add_option() call. This results in
unreadable code such as:

[snip]

I don't find it unreadable at all. I find it very helpful to have the
help text associated right there with the rest of the option, instead of
hidden in a different function call.

[...]

Help descriptions can often be quite long and separating them in this
fashion would, IMHO, be desirable.

If the help descriptions are so long that they are a problem, then the
solution I would choose is to put them in their own module, then do
something like this:

import docs
parser.add_option('-q', '--quiet', action="store_false",
dest='verbose', help=docs.quiet)
parser.add_option('-o', '--output', type='string',
dest='castordir', metavar='<DIR>', help=docs.output)


etc.

 

[Tim Chase]

While we're making suggestions, I've always wished that the
--help output displayed the default values for options in
addition to the help text specified by the user. I end up
having to enter the default values twice -- once as a keyword
argument and again in the help text. Then later when I decide
to change the default value, things get out-of-sync.

Tangential to this thread, what's the preferred way to get
changes into optparse? Based on the comments I've read in the
optparse.py file, it looks like it's the generated output of some
other process. I've patched my local version to include some
changes for handling newlines in help text (which has cropped up
on the list occasionally, as the current version eats newlines),
but am not sure whether I need to be patching against the
optparse.py or against the file that generated it (which I don't
have in my install, AFAIK).

Perhaps one of the core devs that works on optparse could tell me
how they'd prefer such changes submitted?

Thanks,

-tkc

 

[Marc 'BlackJack' Rintsch]

While we're making suggestions, I've always wished that the --help
output displayed the default values for options in addition to the help
text specified by the user. I end up having to enter the default values
twice -- once as a keyword argument and again in the help text.

'%default' in the help text will be replaced by the default value. See
the last option in the first example here:

http://docs.python.org/lib/optparse-generating-help.html

Ciao,
Marc 'BlackJack' Rintsch

 

[James Mills]

Perhaps it is better to keep descriptions short and store longer
descriptions elsewhere, but there are many programs that have long
descriptions, for example try: ls --help (at least on my machine a lot
of these descriptions are quite long).

The longer (program) description is generally
provided by the Usage help string. This
(in my tools) is generally a long-ish docstring
describing the tool, and it's usage.

cheers
James

 

[Pete Forman]

> I would like to know your thoughts on a proposed change to optparse
> that I have planned. It is possible to add default values to
> multiple options using the set_defaults. However, when adding
> descriptions to options the developer has to specify it in each
> add_option() call.

-1

I see no advantage to swelling optparse when the language offers many
solutions already. E.g.

desc = {
'verbose': 'Output less information',
'castordir': 'specify the wanted CASTOR directory where to store '
'the results tarball',
'previousrel': 'Top level dir of previous release for regression '
'analysis'}

parser.add_option('-q', '--quiet', action="store_false",
dest='verbose', help = desc['verbose'])
....


Or another approach might be like this.

for ... in zip(...):
parser.add_option(...)