mathisonian/lightning-python — pull request #3 by freeman-lab (2014-11-13 23:21:25+00:00)
Title: Refactoring

This PR contains a significant refactoring of the python client API, based on offline discussions with @mathisonian .

### Benefits of the new design

- Adding new plot types now requires minimal boilerplate: simply create a subclass of `types.plots` or `types.images` and implement the appropriate cleaning/parsing method. A method with the provided name will automatically be added to the primary lightning object (via decorators), and use otherwise generic plotting and updating methods from `types.base`.

- Design encourages a one-to-one mapping between API calls and visualization types, which will provide a simpler model for developing similar APIs in other languages.

- Generating, updating, or appending to a plot can now all reuse the same data parsing routines; this was previously a key missing feature.

- More modular organization: generic parsing operations now in `types.utils`, visualization-specific parsing occurs in `types.plots` or `types.images`, whereas `lightning.main` contains functions for top-level interfacing (e.g. enabling iPython, creating a session)

### Challenges / quirks

- Not obvious how to have a single top-level function call point to two different named visualization types. For example, using `spatialnetwork` to refer to both the `node-link` type and the `force-bundle` type depending on an input argument setting like `bundling=True`. This is tricky because the plot type is determined by the class definition before any data (and options) are parsed. On the other hand, perhaps this is good, as it encourages the one-to-one mapping. It's easy to have e.g. `BundledNetwork` and `SpatialNetwork` functions.

- Might require some trickery to generate automatic API docs with Sphinx. We only want to document the top-level plot calls, so need to somehow map signatures and docstrings from, e.g. `types.plots.Scatter` -> `lightning.scatter`.

@mathisonian take a look and see what you think?