bipy/pyqi — pull request #120 by jrrideout (2013-08-09 00:08:50+00:00)
Title: Flexible naming

Lots of changes in this pull request. The main idea is to support flexible naming schemes of options/parameters so that we can support existing option names with QIIME and related projects, while keeping this knowledge completely separate from the Command/Parameter level (we can create whatever names we want at the API level because QIIME has never had an official API before).

At the API level: a Parameter's Name is now enforced to be a valid Python name. We enforce this because we want users to have the flexibility to use our API in the following two ways:

```
c = Command()
c(**{'foo': 42, 'bar': 'baz'})
```

and

```
c = Command()
c(foo=42, bar='baz)
```

The latter is only possible if ```Parameter.Name``` is enforced to be valid Python (e.g., no dashes in the name).

```Parameter.Help``` has been renamed ```Parameter.Description```. This is more fitting at the API level because a Parameter should have a description (some text) associated with it, which is not necessarily "help". I feel that ```Help``` is more of a user-interface thing (associated with an Option), which is why ```InterfaceOption``` and its subclasses still have ```Help```.

Flexible naming at the interface level: ```InterfaceOption``` can still be associated with a ```Parameter```, and many of the Parameter's attributes are automatically copied to the Option (this was already put in place before my changes). Now, the user has the ability to override any of those Option attributes while still associating the Option with a Parameter. This is important because we may not always want to forward an API-level description, default, or even name to the interface level. The default is to forward the Parameter's attributes to the Option (interface level) and convert the Parameter's Name to a dashed name (e.g., ```biom_table``` would become ```biom-table```). The user has control to disable this if they really want options to have underscores instead of dashes, but I think in general we're starting to move into a world that embraces dashes.

This design allows us to name Parameters as we'd like (using new names, not tied to QIIME or whatever), while still supporting QIIME's existing command-line option names. When we get to QIIME 2.0 and drop support for these, it'll be really easy to remove these deprecated names from the command config files, and everything *should just work*.

```BelovedFunctionality``` has been killed (sadly) because I actually had to maintain the code that it touched, and its name prevented me from thinking clearly. Now, ```Interface._input_handler``` returns a dictionary mapping Parameter Names to inputs that have been handled by ```InputHandler```. This dictionary can then be passed to ```Command.__call__``` as kwargs. The parsed options (previously ```BelovedFunctionality```) are a separate dictionary that is made available to ```Interface._output_handler```. This separation between parsed options (optparse option name -> value) and Command kwargs allows us the flexibility in naming that is discussed above.

Optparse options now support actions. ```OutputHandler``` is much simpler but should still have the same capabilities as before. The code and documentation has been cleaned up a bit as well. All unit tests pass and the three pyqi commands work.