[Biopython-dev] Properties names in command line wrappers

[Peter]

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

It should be trivial to extend to documentation strings automatically
to include something like "This maps onto the XXX command line
argument" so that the mapping is clear to the user without having to
look at our source code.

Hopefully this gets the balance right between giving nice python
code, and staying faithful to the actual command line tool API.

Peter