[Biopython-dev] Properties names in command line wrappers

[Cymon Cox]

2009/5/13 Peter <biopython at maubp.freeserve.co.uk>

> On Mon, May 4, 2009, Peter  wrote:
> >>> ... The (hardly used) existing blastall wrapper in
> >>> Bio/Blast/Applications.py gives the "-a" argument a human
> >>> readable name of "nprocessors", and "-A" gets "window_size".
> >>> With the old set_parameter call either alias could be used.
> >>> However, with a python property we need to pick one as a
> >>> preferred name - and I'm not 100% sure being helpful and
> >>> using "nprocessors" (e.g. cline.nprocessors=4) is actually
> >>> better than using the actual argument name (e.g. cline.a = 4).
>
> On Tue, May 5, 2009, Brad wrote:
> >> Could we support both the original argument and optional human
> >> readable arguments? I know the code in Application is a bit
> >> hard coded for the first argument as the real name and the last
> >> argument as the readable name; the cleanest solution would be to
> >> generalize this to have multiple names where it makes sense.
> >> ...
>
> On Tue, May 5, 2009, Peter wrote:
> > ...
> > I favour using only a single property for each parameter, with the
> > name as similar as possible to the actual command line switch (i.e.
> > property name "a" for "-a", not "nprocessors").  Note each property
> > would have a docstring which will say what is it for ("Number of
> > processors to use.").
>
> I still favour only using a single python property for each parameter,


A confusing issue arises where we have alternative names for options. That
the following example from _Probcons.py:


            _Option(["-c", "c", "--consistency", "consistency" ], ["input"],
                    lambda x: x in range(0,6),
                    0,
                    "Use 0 <= REPS <= 5 (default: 2) passes of consistency
transformation",
                    0),

>>> cmd = cmdline = ProbconsCommandline("probcons", input="blah")
>>> cmd.c = 1
>>> str(cmd)
'probcons blah '
>>> cmd.set_parameter("c", 1)
>>> str(cmd)
'probcons -c 1 blah '
>>> cmd.consistency = 2
>>> str(cmd)
'probcons -c 2 blah '
>>> cmd.c = 5
>>> str(cmd)
'probcons -c 2 blah '

That is, the user needs to look at the code to figure out what the correct
name is to use when assigning to the property. Is it possible to restrict
the binding of attributes to the cmdline to only valid property names? An
alternative would be to restrict all parameters to only one name and
document the alternatives it covers (dont like this idea - see below).

but after some work on the blastall wrapper last night, I am
> beginning to come round to your point of view.
>
> If a command line tool provides a long parameter name (some tools
> provide both short and long names for important parameters) we
> should use that rather than inventing our own [so no change here].
>
> However, for tools like BLAST which *only* have cryptic single letter
> command line options (case sensitive), maybe we should be using
> a sensible human readable name for the associated property in the
> Biopython wrapper (i.e. "nprocessors" for "-a", and "window_size"
> for "-A").  Having actually now tried using properties "a" and "A",
> the resulting python code is very cryptic - and only makes sense
> if you are familiar with the blastall arguments (and given there are
>
so many of them, this is difficult!).


I dont agree. If you want to make your python code legible to people who are
not familar with the command line options, you can just comment it. I think
the interfaces should stick as close as possible to the application
documentation. I see these interfaces being used mostly by people who are
familar with the applications, in which case the command line construction
should be fairly intuitive.

Cheers, C.
--