Added HTML repr for Parameterized

[jbednar]

Parameterized's repr works well for small numbers of parameters, but as it's all on a single line of text, quickly becomes not very useful for larger classes:

import param
class A(param.Parameterized):
   b = param.Integer(5)
   c = param.Selector([param.Parameterized(name="Z"), param.Parameterized(name="X")])

a = A()
repr(a)

"A(b=5, c=Parameterized(name='Z'), name='A00108')"

This PR adds an HTML representation that is similar to the parameter listing in the help output:

but as a table listing only the parameters:

[coveralls]

Coverage decreased (-0.6%) to 75.966% when pulling 391e4dcbca9f5bf2180080f9449b1de0bcc97198 on htmlrepr into 97a26a7f364ec3d2ba4bccb6e33e81f277411651 on master.

[jbednar]

It's still WIP, with various open issues:

• [x] What should happen to Parameterized subobjects? Right now they are shown as closed details items, but expanding them doesn't format well and presumably there will be problems for any circular references as for the string repr:
• [x] Can we include the docstrings somehow as hover text or as details to expand? It would be great to be able to show the full details for any parameter as in the example at https://datatables.net/ , but I haven't found a suitable pure-CSS or at least simple JS way to achieve that.
• [x] Should we use something like this to support automatically generated reference material for the various HoloViz projects? E.g. instead of saying "For full documentation and the available style and plot options, use hv.help(hv.Area)" as we do now in the Reference Gallery for e.g. hv.Area, we could add a section of actual (auto-generated) HTML that lets users see what parameters are defined on that object. We might also consider extending this HTML representation to something HoloViews specific, also displaying the list of supported options. I think that could solve some of the gaps between our explicit reference material and our API docs, with a representation like this concisely documenting the full set of available parameters (and options, for hv) without us having to maintain it.
• [x] I've mapped the HTML representation to Parameterized._html_repr_, but that probably needs updating to use a mimebundle because otherwise it will cause issues with HoloViews by overriding the mimebundle-based representation it already has:
• [x] The implementation is currently py3 only, and probably needs some attention to make it not cause errors on py2 (though of course it could easily be made py2/3 compatible).

[jbednar]

I've mapped the HTML representation to Parameterized.html_repr, but that probably needs updating to use a mimebundle because otherwise it will cause issues with HoloViews by overriding the mimebundle-based representation it already has:

Actually, should I be focusing on making an HTML repr for obj.param, not obj? That way there would never be any conflict with the repr for the object itself; this would be a repr for the Parameterized aspects of the object. Hmm..

[philippjfr]

Actually, should I be focusing on making an HTML repr for obj.param, not obj? That way there would never be any conflict with the repr for the object itself; this would be a repr for the Parameterized aspects of the object. Hmm..

Yes, I like this, it's also less discoverable but on balance I think this is nice. Alternatively just do both and then if the Parameterized repr is overridden you can still view it via .param.

[jbednar]

Sounds good; always have obj.param's repr available, but also by default have it as the repr for the object itself. For that to work, any idea how to avoid Param's repr hiding the HoloViews repr (which it does in the current implementation)?

[philippjfr]

Rebased and did a few things:

• Implemented the repr for classes
• Implemented the repr on Parameterized.param
• Display bounds and valid objects (for Selectors) in the same column:

[philippjfr]

any idea how to avoid Param's repr hiding the HoloViews repr (which it does in the current implementation)?

Not sure why but this no longer appears to be an issue.

[MarcSkovMadsen]

A way to see the doc string would be very valuable. For example for interactive docs and cheat sheets

[jbednar]

This looks great, thanks! Any answers for the checklist items above? On a quick scan they nearly all still appear to be valid issues.

[maximlt]

@jbednar @philippjfr do you think this is going to be ready for 2.0?

[philippjfr]

I think it's a huge usability improvement so I'd like to push this over the finish line.

[philippjfr]

Docstring now displayed as tooltips:

And recursion is handled:

[maximlt]

Just noticed that pn.panel would now display Parameterized objects with the HTML pane, calling _repr_html_, instead of building a Param pane:

[philippjfr]

Damn, need to give higher precedence to the Param pane.

[jbednar]

I think the precedence is a Panel issue rather than a Param issue, so is it safe to merge this? I'm assuming Panel 1.0 will fix the precedence and that Panel 1.0 will be out before Param 2.0.

[philippjfr]

The precedence change was merged into Panel and released in v1.0.3.

[maximlt]

Almost 3 years in the making, great work @jbednar and @philippjfr !

[jbednar]

@philippjfr , the intention was to require .param to invoke this, right? Right now it's using the HTML repr for the instance or class itself, as well as for .param. I'm not sure whether that's a bad thing, but I don't think it's what we agreed on.

[maximlt]

Sounds good; always have obj.param's repr available, but also by default have it as the repr for the object itself. For that to work, any idea how to avoid Param's repr hiding the HoloViews repr (which it does in the current implementation)?

Didn't you agree there the rich display should be used in both cases?

[philippjfr]

Yep, what @maximlt said.

[maximlt]

Ah! I know what happened with your HoloViews examples @jbednar in https://github.com/holoviz/param/pull/425#issuecomment-674586931.

So when you forget to load the extension it will fallback to displaying the rich representation.

Same for Panel objects, except that an informative warning is displayed:

Presumably HoloViews should also display the same warning?

[philippjfr]

Ah! I know what happened with your HoloViews examples @jbednar in #425 (comment).

For HoloViews that's a problem, because the custom HoloViews repr is meant to show the structure and dimensions of the object. We probably need to find a clean entrypoint for extending the repr with that info.

[maximlt]

Isn't it always a mistake not to load the HoloViews extension in a notebook?

Usually when I want to see the custom HoloViz repr I simply print the object, calling repr works too of course:

[hoxbro]

I would not expect to see this output when calling type on the object:

[philippjfr]

Why not?

[philippjfr]

That said, I do think if we're displaying the class it should include the module like a regular type repr would.

[hoxbro]

I would expect it to show me the type that is what I asked for. It did not ask to show all the param objects.

[philippjfr]

Personally don't feel super strongly about it but in the discussion above we did agree to implement the repr for classes, instances and for the .param accessor.

[hoxbro]

I would say this is an unexpected side effect of the discussion made above.

[philippjfr]

How so? type(obj) just returns the class and we explicitly enabled the repr on a class. @jbednar made the point to me that the class is precisely the point at which you want to see the parameters since it gives you information about what you can set in the constructor.