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

[Paul Ivanov]

On Fri, Nov 30, 2012 at 4:34 PM, David Warde-Farley
<d.warde.farley at gmail.com> wrote:
> 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:
>
> 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.

Well, the inheritance would be made clear, and a dev could follow that. One
could argue in the other direction - what if I want to know *only* the
arguments that are unique to a given converter subclass, and not all of the
arguments it "inherited" (in some manner, whether by virtue of subclassing or
de-facto having the same paramters used in multiple places).


>>>  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.

yes, this is along the lines of my thinking as well, and since all our
converters subclass from Converter, it's easy to ensure that they all have such
a method ;). The iteration over classes would only be need in the case where
the user wanted all possible flags, whereas I'd argue getting only the
converter class which is implied by the --format argument would be sufficient
in the simple -h case.


>> 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.

>From a perspective of a user, it's better to get an error in this case rather
having to somehow guess whether --some-random-flag has any effect or not.
Warnings are easier to miss, since suppose you do a run but had a typo for one
of the parameters, and *some* result is produced, but it doesn't reflect the
effect of the flag that you had a typo in. Now you sort of have to go back and
figure out what actually happend.

Another precedent, as an example is the -j flag, at least for GNU's ls

$ ls -j
ls: invalid option -- 'j'
Try 'ls --help' for more information.

better,
--
Paul Ivanov
314 address only used for lists,  off-list direct email at:
http://pirsquared.org | GPG/PGP key id: 0x0F3E28F7