Renderer, format and path API

[juba]

As for the general question, it seems a bit problematic that there is no one-to-one correspondence between format and path-extension. What I mean is that:

• there is no format="pdf" (I assume because displaying PDFs in something like Jupyter notebooks seems problematic)
• there are two formats for extension ".html", namely "widget", and "html".

Without knowing the internals it seems weird that

Plot.plot({}, format="png", path="out.svg") => ok
Plot.plot({}, format="widget", path="out.svg") => error.

I first thought that it would be best to completely decouple format and path: format dictates the display format, path dictates the export format. But this does not account for the html case...

Originally posted by @wirhabenzeit in #32 (comment)

[juba]

Your points are very valid, but even after thinking about it I don't see a way to solve the inconsistencies without going back to a "renderer" or "output" argument.

This would mean that instead of renderer="jsdom"|"widget" we would have output="widget"|"static". For the widget output only a "path" option with an HTML extension would be allowed. For the static output there could be either a "format" option which could be "html", "svg" or "png". or a "path" option with an "html", "svg", "png" or "pdf" extension.

This would be more like the previous API, but maybe it would cause less confusion ?

@wirhabenzeit, @harrylojames any feedback would be welcome if you have any.

[wirhabenzeit]

@juba To me this sounds like a good idea! Actually the output option would only be necessary for path=.html and format=html?

• For path=*.svg/*.png/*.pdf or format=svg/png it can be inferred that output=static
• For path=*.html or format=html the output can be specified, with default output=widget? (Maybe one could argue that the default for path=*.html should be output=static but not sure)

[juba]

@wirhabenzeit Indeed, I also thought that output could in general be inferred depending on the format and path values (or lack of), with a default of "widget".

• For path="*.html" I think we could raise an exception to force the user to specify an output.
• For format="html" I think the default could rather be "static", as there should not be any format option for output="widget". We can display a warning to inform the user.

Thanks for your feedback !

[harrylojames]

@juba The above all seems reasonable but apologies I've looked through the previous discussion and still feel as though I've missed a key detail!

What's stopping us from having just the arguments output and path? I had assumed if we were in a notebook with the static renderer we could simply always show a html - but perhaps that's not desired! Only at the point of exporting would the format become relevant at which point we could infer from path?

[juba]

@harrylojames I get your point but I think there are cases where you would want to specify an output format even when not directly exporting to a file. I think of notebook exports (for example if you commit an ipynb with outputs to gitlab it will save the images and make them available) or quarto documents, where you may prefer a png or svg output over another format.

[wirhabenzeit]

@juba @harrylojames I agree that is useful to have svg or png output also in notebooks. Some platforms displaying ipynb files seem to have issues with HTML output.

[juba]

New version of format and path API should be now implemented in the development version, and the documentation has been updated.

Closing this for now, don't hesitate to open a new issue for further discussion.