[IPython-dev] [nbconvert] Reining in the number of constructor arguments

[David Warde-Farley]

I'm wondering how to solve (and how you guys think I should solve) a
certain problem I foresee, of a potentially rapidly growing number of
constructor arguments for Converter classes, which need to be
maintained across constructors in order to keep the front-end calling
code generic (one could use *args and **kwargs catch-alls but that's
pretty ugly).

A pull request that @Jovani started and I have finished off adds a
highlight_source argument to the constructors for all of the classes.
I have some features in mind that control fine-grained output
behavior. Passing these as either positional or keyword arguments
requires every other Converter class to know about every possible
argument, which is a maintenance nightmare, and doesn't necessarily
make sense: part of the problem is that not every backend even
*supports* all of the options, e.g. the ConverterPy can't highlight
source in code blocks because that doesn't make any sense in terms of
the output type.

My thought on solving this goes something like this:
- on the front-end, delegate all but very core functions that are
backend-agnostic to a sub-parser
- on the back-end, have either the "namespace" object produced by
argparse or a dictionary constructed from it passed as a *single*
argument to the constructor.
- have each class examine this namespace

Questions:
- Should a backend that can't highlight source, or perform optional
function X, raise an error, a warning, or fail silently? My gut says
warning is the right balance of informative and yet annoying. (should
I use the warnings module, logging.warn, ...?)

This raises one problem, though, in that some defaults as per argparse
will raise warnings automatically in some backends, e.g. without
--no-highlight, the default argument of `True` will raise a warning
when the output type is a Python script.

A possible solution: make argparse's default be 'None' for options
even when True/False is the default. Have converter classes expose a
class-level `config_defaults` dict, where values are 2-tuples:
(default value, legal_values), which the class uses to address its
configuration needs for things that come up as None in the
configuration object passed in, and raise warnings for invalid values
where appropriate.

Thoughts? Am I off my rocker?

David