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_opti on('-q', '--quiet' , action="store_f alse",
dest='verbose',
help = 'Output less information')
parser.add_opti on('-o', '--output' , type='string',
dest='castordir ' , metavar='<DIR>' ,
help = 'specify the wanted CASTOR directory where to store the
results tarball')
parser.add_opti on('-r', '--prevrel' , type='string',
dest='previousr el' , 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_desc ription(
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_opti on('-q', '--quiet' , action="store_f alse",
dest='verbose')
parser.add_opti on('-o', '--output' , type='string',
dest='castordir ' , metavar='<DIR>' )
parser.add_opti on('-r', '--prevrel' , type='string',
dest='previousr el' , 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]

Re: PEP proposal optparse

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_option s() -opts, args

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

parser = optparse.Option Parser(usage=US AGE, version=VERSION )

parser.add_opti on("", "--date-format",
action="store", type="str", default="%d/%m/%Y",
dest="dateForma t",
help="date format string")
parser.add_opti on("", "--time-format",
action="store", type="str", default="%H:%M: %S",
dest="timeForma t",
help="time format string")
parser.add_opti on("", "--datetime-format",
action="store", type="str", default="%H:%M: %S %d/%m/%Y",
dest="datetimeF ormat",
help="datetime format string")

opts, args = parser.parse_ar gs()

if len(args) < 2:
parser.print_he lp()
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

On 9/18/08, James <jlnicolson@gma il.comwrote:

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_opti on('-q', '--quiet' , action="store_f alse",
dest='verbose',
help = 'Output less information')
parser.add_opti on('-o', '--output' , type='string',
dest='castordir ' , metavar='<DIR>' ,
help = 'specify the wanted CASTOR directory where to store the
results tarball')
parser.add_opti on('-r', '--prevrel' , type='string',
dest='previousr el' , 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_desc ription(
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_opti on('-q', '--quiet' , action="store_f alse",
dest='verbose')
parser.add_opti on('-o', '--output' , type='string',
dest='castordir ' , metavar='<DIR>' )
parser.add_opti on('-r', '--prevrel' , type='string',
dest='previousr el' , metavar='<DIR>' )
>
Help descriptions can often be quite long and separating them in this
fashion would, IMHO, be desirable.
>
Kind Regards,
James Nicolson
>
>
--

http://mail.python.org/mailman/listinfo/python-list

>

--
--
-- "Problems are solved by method"

[James Nicolson]

Re: PEP proposal optparse

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).

2008/9/18 James Mills <prologic@short circuit.net.au> :

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_option s() -opts, args
>
Parse any command-line options given returning both
the parsed options and arguments.
"""
>
parser = optparse.Option Parser(usage=US AGE, version=VERSION )
>
parser.add_opti on("", "--date-format",
action="store", type="str", default="%d/%m/%Y",
dest="dateForma t",
help="date format string")
parser.add_opti on("", "--time-format",
action="store", type="str", default="%H:%M: %S",
dest="timeForma t",
help="time format string")
parser.add_opti on("", "--datetime-format",
action="store", type="str", default="%H:%M: %S %d/%m/%Y",
dest="datetimeF ormat",
help="datetime format string")
>
opts, args = parser.parse_ar gs()
>
if len(args) < 2:
parser.print_he lp()
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
>
On 9/18/08, James <jlnicolson@gma il.comwrote:

>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_opti on('-q', '--quiet' , action="store_f alse",
> dest='verbose',
> help = 'Output less information')
> parser.add_opti on('-o', '--output' , type='string',
> dest='castordir ' , metavar='<DIR>' ,
> help = 'specify the wanted CASTOR directory where to store the
> results tarball')
> parser.add_opti on('-r', '--prevrel' , type='string',
> dest='previousr el' , 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_desc ription(
> 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_opti on('-q', '--quiet' , action="store_f alse",
> dest='verbose')
> parser.add_opti on('-o', '--output' , type='string',
> dest='castordir ' , metavar='<DIR>' )
> parser.add_opti on('-r', '--prevrel' , type='string',
> dest='previousr el' , metavar='<DIR>' )
>>
> Help descriptions can often be quite long and separating them in this
> fashion would, IMHO, be desirable.
>>
> Kind Regards,
> James Nicolson
>>
>>
> --
> http://mail.python.org/mailman/listinfo/python-list
>>

>
>
--
--
-- "Problems are solved by method"
>

[Fredrik Lundh]

Re: PEP proposal optparse

James Mills wrote:

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]

Re: PEP proposal optparse

On Thu, 18 Sep 2008 03:37:54 -0700, James wrote:

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_opti on('-q', '--quiet', action="store_f alse",
dest='verbose', help=docs.quiet )
parser.add_opti on('-o', '--output', type='string',
dest='castordir ', metavar='<DIR>' , help=docs.outpu t)


etc.



--
Steven

[Grant Edwards]

Re: PEP proposal optparse

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.

--
Grant Edwards grante Yow! Did you move a lot of
at KOREAN STEAK KNIVES this
visi.com trip, Dingy?

[Tim Chase]

Re: PEP proposal optparse

Grant Edwards wrote:

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]

Re: PEP proposal optparse

On Thu, 18 Sep 2008 11:07:45 -0500, Grant Edwards wrote:

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

[Grant Edwards]

Re: PEP proposal optparse

On 2008-09-18, Marc 'BlackJack' Rintsch <bj_666@gmx.net wrote:

On Thu, 18 Sep 2008 11:07:45 -0500, Grant Edwards wrote:
>

>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-...ting-help.html

Great! I guess I should scan the doc pages for changes more
often.

--
Grant Edwards grante Yow! The Korean War must
at have been fun.
visi.com

[James Mills]

Re: PEP proposal optparse

On Thu, Sep 18, 2008 at 9:02 PM, James Nicolson <jlnicolson@gma il.comwrote:

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

--
--
-- "Problems are solved by method"

[Pete Forman]

Re: PEP proposal optparse

James <jlnicolson@gma il.comwrites:

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_opti on('-q', '--quiet', action="store_f alse",
dest='verbose', help = desc['verbose'])
....


Or another approach might be like this.

for ... in zip(...):
parser.add_opti on(...)

--
Pete Forman -./\.- Disclaimer: This post is originated
WesternGeco -./\.- by myself and does not represent
pete.forman@wes terngeco.com -./\.- the opinion of Schlumberger or
http://petef.22web.net -./\.- WesternGeco.