Ipywidgets: API for getting URLs for JavaScript files?

[mgeier]

There is ipywidgets.embed.DEFAULT_EMBED_REQUIREJS_URL, but is there also an API to get the require.js URL?

I could probably use ipywidgets.embed.load_requirejs_template, but I don't know if that's part of the public API. Is it?

I'm also not quite sure if I'm supposed to use crossorigin="anonymous" or not. In load_requirejs_template it is hard-coded for one URL, and optional for the other.

In the end, I want to use those URLs in Sphinx, see https://github.com/spatialaudio/nbsphinx/issues/84.

[mgeier]

A little update:

require.js is probably loaded separately (e.g. in my case with https://github.com/spatialaudio/nbsphinx/pull/327), so I think it would be OK to only get the needed information for the ipywidgets JS URL.

Is ipywidgets.embed.DEFAULT_EMBED_REQUIREJS_URL supposed to be the official API for that?

If yes, this issue can be closed.

[vidartf]

I'm in favor of making DEFAULT_EMBED_SCRIPT_URL and DEFAULT_EMBED_REQUIREJS_URL part of the API, but I would want others to chime in here as well before declaring that as final.

[vidartf]

TBH, I'm not sure what is currently considered our source of truth about what is part of the API, and what is not..

[mgeier]

I have just realized that this URL can be used to automatically get the latest version:

https://unpkg.com/@jupyter-widgets/html-manager/dist/embed-amd.js

Is it a bad idea to use this as a default (and provide an option to override or completely disable)?

Would a browser still be able to cache this if the URL doesn't contain a version number?

I'm still unsure whether loading the widget JS should be opt-in or opt-out in nbsphinx ... any opinions?

[vidartf]

Is it a bad idea to use this as a default (and provide an option to override or completely disable)?

I think using the URL in ipywidget.embed is a lot more robust. It uses the caret semver (^0.18.0) for the widget manger it knows it supports. This ensures:

• It will pick up bug fixes and new features.
• It will not break the documentation if there is a new, backwards incompatible version of the manager (unless the installed ipywidgets is also updated to support it).

In either case, having the ability to override it is a good thing to have.

[mgeier]

Thanks for the insights! This totally makes sense, so I will use (and recommend using) the URL provided by ipywidget.embed.

I've updated the nbsphinx documentation: https://nbsphinx.readthedocs.io/en/latest/code-cells.html#Interactive-Widgets-(HTML-only)

from ipywidgets.embed import DEFAULT_EMBED_REQUIREJS_URL

html_js_files = [
    DEFAULT_EMBED_REQUIREJS_URL,
]

Users are of course free to use any other URL of their choice, or a local JS file, or nothing.

Does that make sense?

[vidartf]

Does that make sense?

Seems smart. My only questions would be:

• Is html_js_files just a global in conf.py? Should it maybe be on the app config somewhere? I might be missing some info from another section of the docs..
• Would it make sense for html_js_files to have this as a default value if not specified? (haven't thought this fully through)

[mgeier]

Is html_js_files just a global in conf.py?

That's just how the Sphinx configuration works. The global variables are somehow automatically turned into Sphinx options (if those options exist).
See http://www.sphinx-doc.org/en/master/usage/configuration.html.

Would it make sense for html_js_files to have this as a default value if not specified?

Well that's the question!

The problem, as I see it, is that I would always need to import ipywidgets, even for projects which don't use widgets.
I don't want to have ipywidgets as unconditional dependency.

However, now that I think about it, I might be able to check if widget states are used in any notebook and only import ipywidgets (and in turn include the .js URL) in this case ...

In that case though, I shouldn't use html_js_files, because I cannot detect user overrides (because it might be used for completely different JS files). But I could use a new configuration value, just like I've done for nbsphinx_requirejs_path (see https://github.com/spatialaudio/nbsphinx/pull/327).
Something like nbsphinx_widgets_path?

Do you think this would be worthwhile?

It sounds promising ... fully automatic widget support, but without overhead if widgets are not used.

[dgasmith]

+1 for not requiring an explicit ipywidgets dependency.

[vidartf]

You could do an
python try: import ipywidgets.embed default_value= ... except ImportError: pass

[mgeier]

Thanks!

I've implemented automatic widgets support in https://github.com/spatialaudio/nbsphinx/pull/345.

If you have suggestions for improvements, please comment over there.

[vidartf]

Thanks for referring back to the implementation. Are there anything left to be done on this issue (docs?) or can it be closed?

[mgeier]

I think it would be helpful to mention in the docs that DEFAULT_EMBED_REQUIREJS_URL is considered part of the API.

And it would be good to know if I'm supposed to use crossorigin="anonymous" or not.

[mgeier]

FYI, I've just made a new nbsphinx release: https://pypi.org/project/nbsphinx/0.5.0/

From now on, widgets should work automatically for everyone.

I've updated the instructions in #2577.