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

David Warde-Farley d.warde.farley at gmail.com
Fri Nov 30 19:34:12 EST 2012


On Fri, Nov 30, 2012 at 6:52 PM, Paul Ivanov <pivanov314 at gmail.com> wrote:
> On Fri, Nov 30, 2012 at 3:05 PM, David Warde-Farley
> <d.warde.farley at gmail.com> wrote:
>> 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).
>
> I don't think it's ugly - I think it's the right way to do it. It allows
> one to easily add keyword arguments to all of the subclasses of
> Converter, for example, by writing the relevant code only in one place.
> See the --stdout flag I've proposed in
> https://github.com/ipython/nbconvert/pull/62

The annoying thing about it is that it makes introspection harder. The
generated docs and the obj? help in IPython end up telling less of the
story, and if the docstring is not kept up to snuff there's no canary
in the mine.

>>  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.
>
> And for this reason, that flag should not be exposed globally, the same
> way that all possible flags to ipython notebook aren't exposed when one
> does just "ipython --help".
>
> The solution I think makes sense is to have formatter specific flags be
> exposed only when a specific formatter is selected.
>
> So `nbconvert -f html -h` should show --highlight-source  as an option,
> whereas `nbconvert -f py -h` should not.

So a separate, delegated parser for each output mode is the way to go,
you think?

It seems like the right place for this code would be in a class method
attached to each
Converter class. Then nbconvert.py could iterate over the classes it
knows about and
call cls.cli_argument_parser(), and add that to the global one.

> The nice thing about kwargs is that it's evident from the method
> signature where they are being used, whereas passing around an opaque
> "namespace" object as a single argument doesn't really buy you anything,
> since **kwarg is a single argument, anyway ;)
>
> But I haven't thought about this very carefully yet.
>
>> 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, ...?)
>
> I think it should fail, the same way `ipython -X` fails with
>
> [TerminalIPythonApp] Bad config encountered during initialization:
> [TerminalIPythonApp] Unrecognized flag: '-X'

Okay, didn't realize there was precedent. Thanks.

> In summary, I think it would be annoying to expose all of the flags that
> don't apply to all the converters globally. If the Converter base class
> accepts it as a flag, we have it show up in the docs, whereas formatter
> specific flags should only show up in the help printout for specific
> formatters.

Yes, that sounds like a better solution.

Cheers,
David



More information about the IPython-dev mailing list