[IPython-dev] [nbconvert] Specifying output filename/target directory: feedback needed

Matthias BUSSONNIER bussonniermatthias@gmail....
Mon Dec 3 10:19:04 CST 2012


Le 3 déc. 2012 à 16:21, W Gong a écrit :

> Hi, 
> 
> here is my wishful spec:
> 
>    nbconvert --output <folder or file> --format <html (default) | rst | ...> foo.ipynb
> 
> default format is html, so --format is optional
> default output is ./foo.html so --output is also optional
> internally you determine if the value of output is a folder or file:
> 
>      case 1: if input is single file, output is folder, then output is folder/foo.<fmt>
>      case 2: if input is single file, output is file, then output is the given file
>      case 3: if input is multiple (folder or glob), output is a file, then error out, 
>      case 4: if input is folder or glob, output is folder, then generate multiple files as folder/*.<fmt>
> 
> Thanks,
> 
> Wen

There is a discussion on using IPython Configurable class to handle that. 
As with IPython, you would be able to pass --MyClass.myoption=myconfiguration 
It will allow to avoid to pass all the flags around and would come for free with anyone subclassing.

IMHO and as I already said somewhere,  nbconvert is a nice tool, but the command line part is only secondary.
Also unix philosophy is "do one thing, do it well".
And we won't be able to fit everything in nbconvert, not as command line parameters.

Everyone is speaking of files, but the biggest use of nbconvert will be integrated in notebook/ nbviewer/other tools.
There you will have the option to "download as pdf/html …" I hope those will not be done with subprocess calling nbconvert.

If the choice where only mine, I would totally hide the file part in nbconvert classes.
Not even the constructor would take a filename but a Json object.
I've always learned to hide IO as much as possible, and for me, converting from A to B does not even involve files.

Then you just expose some attributes of converter object. 
After you just have to create a thin wrapper around theses object that act the way you want in 10 lines and take folder/filesname as parameter.

For what it is worth.
-- 
Matthias



> 
> 
> 
> On Mon, Dec 3, 2012 at 8:43 AM, Maximilian Albert <maximilian.albert@gmail.com> wrote:
> Hi all,
> 
> a while ago I submitted a pull request (see [1]) to add a "--output" switch to nbconvert which would allow the user to specify the output directory and/or output filename of the converted file. At the time I received a number of really helpful comments, but it turned out that my original implementation was too complicated and attempted to achieve too much, so it needed reworking.
> 
> Since then I have spent quite a bit of time thinking about it and reworking it, but I haven't uploaded a new PR because I continuously stumbled upon certain design questions that have kept me from coming up with a solution that I'd be happy with (and also I was flooded with work over the past couple of weeks). In the meantime, there has also been another PR [2] implementing very similar functionality (namely, specifying an output filename). However, even though in itself it looks good, I presume it will suffer from related problems when we try to extend it to support target directories.
> 
> So I figured it would be a good idea to gather some thoughts from the community before we rush into implementing a quick solution which is hard to improve later on (e.g. due to concerns about backward compatibility etc.).
> 
> There appear to be two main use cases for an --output flag:
> 
> (i) Specifying a target *filename* for the converted file.
> (ii) Specifying a destination *directory* for the converted file.
> 
> It seems natural to handle these with the same flag. However, this raises a few questions:
> 
> (a) How do we decide whether the --output argument is a filename or a directory?
> 
> We could say that if the argument has a valid extension (e.g. '.rst' or '.html') then it should be interpreted as a filename, otherwise as a directory. A minor drawback might be that the user is then forced to use filenames whose suffix matches the output format, which is is probably ok in most cases but perhaps not always. Also, what if the --output argument has a valid extension but the "--format" argument specifies a different output format? For example:
> 
>    nbconvert --format rst --output foo.html foo.ipynb
> 
> I guess in this case the "--format" argument should have precedence, but then the logical thing to do interpret foo.html not a filename but as a directory, so the resulting output file would be foo.html/foo.rst. This is not very intuitive. Thus the next question is:
> 
> (b) Should we deduce the output format automatically from the filename extension or always rely on the --format switch? As mentioned, the former is quite intuitive in most cases but could sometimes lead to subtle annoyances. But either solution would force us to do a bit of "intelligent guesswork" as to whether the --output argument is supposed to be a filename or a directory.
> 
> So it seems that allowing the --output argument to be interpreted as either a filename or a directory would work well for 98% of the cases, but there are corner cases where it would behave in unexpected and/or annoying ways.
> 
> The alternative is to always and unconditionally interpret the --output argument as a directory and have another switch such as "--output-filename" to specify the filename. This is a slightly cleaner solution in that it doesn't require us to guess what the user intended to do. However, it seems unnecessarily awkward for most use cases. I for one would certainly quickly get annoyed by it.
> 
> In all this, we shouldn't forget that any solution should be easily extendable to handle the conversion of multiple files, à la:
> 
>    nbconvert --output foo/ *.ipynb
> 
> Any thoughts? It seems that it can't be *that* difficult to design a good CLI for such a simple task. Am I totally overthinking this? And how do other programs handle it?
> 
> Sorry for this long email and thanks in advance for any comments!
> 
> Best wishes,
> Max
> 
> 
> [1] https://github.com/ipython/nbconvert/pull/44
> [2] https://github.com/ipython/nbconvert/pull/62
> 
> _______________________________________________
> IPython-dev mailing list
> IPython-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev
> 
> 
> 
> 
> -- 
> 
> Thanks,
> 
> - Wen
> 
> 
> 
> 
> _______________________________________________
> IPython-dev mailing list
> IPython-dev@scipy.org
> http://mail.scipy.org/mailman/listinfo/ipython-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/ipython-dev/attachments/20121203/c22e4d41/attachment-0001.html 


More information about the IPython-dev mailing list