467,188 Members | 1,431 Online
Bytes | Developer Community
Ask Question

Home New Posts Topics Members FAQ

Post your question to a community of 467,188 developers. It's quick & easy.

PEP proposal optparse

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

Sep 18 '08 #1
  • viewed: 1200
Share:
10 Replies
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

On 9/18/08, James <jl********@gmail.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_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
--
http://mail.python.org/mailman/listinfo/python-list

--
--
-- "Problems are solved by method"
Sep 18 '08 #2
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 <pr******@shortcircuit.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_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

On 9/18/08, James <jl********@gmail.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_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
--
http://mail.python.org/mailman/listinfo/python-list


--
--
-- "Problems are solved by method"
Sep 18 '08 #3
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>

Sep 18 '08 #4
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_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.

--
Steven
Sep 18 '08 #5
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?
Sep 18 '08 #6
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

Sep 18 '08 #7
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

Ciao,
Marc 'BlackJack' Rintsch
Sep 18 '08 #8
On 2008-09-18, Marc 'BlackJack' Rintsch <bj****@gmx.netwrote:
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
Sep 18 '08 #9
On Thu, Sep 18, 2008 at 9:02 PM, James Nicolson <jl********@gmail.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"
Sep 19 '08 #10
James <jl********@gmail.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_option('-q', '--quiet', action="store_false",
dest='verbose', help = desc['verbose'])
....
Or another approach might be like this.

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

--
Pete Forman -./\.- Disclaimer: This post is originated
WesternGeco -./\.- by myself and does not represent
pe*********@westerngeco.com -./\.- the opinion of Schlumberger or
http://petef.22web.net -./\.- WesternGeco.
Sep 19 '08 #11

This discussion thread is closed

Replies have been disabled for this discussion.

Similar topics

8 posts views Thread by Hans-Joachim Widmaier | last post: by
7 posts views Thread by Henry Ludemann | last post: by
3 posts views Thread by Karlo Lozovina | last post: by
3 posts views Thread by Bob | last post: by
reply views Thread by Steven Bethard | last post: by
2 posts views Thread by mbeachy@gmail.com | last post: by
reply views Thread by Robert Kern | last post: by
By using this site, you agree to our Privacy Policy and Terms of Use.