Proposal: Make Panel objects explicitly compositional about panel HOT 10 CLOSED

Jean-Luc, Philipp and I just had a long discussion about the above issues, and we propose a multi-part solution:

1. pn.Pane() should be renamed to pn.create(), as a statement that it may or may not return a Pane -- it just returns something viewable, which may be a Layout.
2. Ordinarily, where interact() currently returns an object i, it should return i.layout, i.e. a container object matching what the user can see as the result. Users can then unpack and work with that container as they like.
3. pn.create() for something leading to a yt pane should return a Row or Column of PNG-based panes, for the user to recompose in some order as they like.
4. pn.create() for a HoloViews object should do the same for a HoloMap or DynamicMap or other HoloViews object whose representation includes multiple viewables -- it should return a Row or Column object containing the plot(s) and the widgets, etc. ready for unpacking.
5. pn.Row() and pn.Column() should call pn.create() on each item they are given, just as they currently call pn.Pane(), and so by default what users see will ordinarily be fully compositional, i.e. rows and columns of rows and columns of ... , and users can then unpack and repack the container they get as they wish.
6. This proposal so far has the problem that once an object like a HoloMap is decomposed into plot+widget for return in a container, the original linkage between those two items is lost, making it difficult to update the HoloMap while ensuring that both viewable components are correspondingly updated. So we propose that if someone needs to retain the mapping between the holoviews object and the resulting Panel objects, they should explicitly create a HoloViews pane (not using pn.create()), where the underlying plot and widgets will each be stored in wrapper containers that remain linked to each other by virtue of being inside this object, and can be updated there and thus automatically update any other object where those same wrapper containers are also included. (Hard to explain, but I think we know what should happen here.)
7. Everything returned by pn.create() will then be what is currently called a Layout, and with that in mind it makes sense to change the name of Layout to "Panel" -- that way everything displayed will normally be a Panel (a Panel of one HTML pane, a Row Panel, a Column Panel, etc.) Seems clear and easy to explain, and makes the name of the library make sense.

Philipp and Jean-Luc, please correct if I got anything wrong above or missed anything.

from panel.

That was largely my understanding although I had already forgotten some of the details you describe. I would like to elaborate a little bit why I think this proposal makes sense:

pn.Pane() should be renamed to pn.create() ...

I hugely prefer this as I hate factory functions that pretend to be classes when they are not. It is just a lot more honest as when you called pn.Pane you wouldn't get a pn.Pane, you would get a specific type of pane!

... they should explicitly create a HoloViews pane (not using pn.create())

This makes sense to me as it is consistent. The reason you would explicitly create any type of pane explicitly as a user (markdown, html etc) is because you want some extra control you wouldn't get with pn.create (e.g to specify height). In the case of the HoloViews pane, one of the affordances you get using it explicitly is that you can set the object directly to update all the children (i.e update the plot and widget together in the case of a holomap or dynamicmap).

One other thing I'll mention is this: I would expect pn.create to be the default way of creating objects (because it can conveniently condition on type). As a result, if I ever saw the use of of a HoloViews pane, I would assume the user chose to do this very explicitly in order to update the displayed holoviews object directly and easily. Another way to say this is that the use of a HoloViews pane is a very explicit indicator that the user wants to consider this a suitable level for a functional 'unit'.

... the object returned in that call is , which is opaque...

It is opaque partially because panel is lacking compositional reprs! That said, this is probably orthogonal to the point you were trying to make which (I think!) is that a compositional panel object should be returned instead.

from panel.

Right; we do need to have compositional reprs for our compositional objects. But interactive is not currently compositional, as it's a single pane, so it probably won't have a compositional representation regardless.

from panel.

Almost done with this but I have one question before finishing this off, if a Pane does not need to be wrapped in layout to be updatable should its .layout still wrap it? I'd prefer not to introduce unnecessary nesting but a consistent return type is also nice.

from panel.

That is a difficult question to answer, and I defer to your best judgment. I can see the advantages of both approaches.

But if it always returns a layout (which I argue should be called a Panel now), then arguably pn.create() should be called pn.panel(), because then it always returns a type of Panel. As a name, panel.panel or from panel import panel could potentially be confusing, but as we would normally suggest using it as pn.panel then I hope it would be ok.

from panel.

I have decided to keep the nesting for simplicity's sake. I have a slight preference for pn.create over pn.panel but would be happy to be overruled on that. The PR referenced above implements everything we discussed, but will need thorough testing before merging.

from panel.

Oh and I've left pn.Pane for backward compatibility for now, I'll start by eliminating it from the existing docs and will add a deprecation warning after a 0.2.0 release.

from panel.

@jlstevens, can you please break the tie on pn.create() vs pn.panel()? I have a preference for pn.panel(), because I read that as "give me a Panel (of some type) out of whatever I give this function". pn.create() doesn't tell me what I'm creating, though if I read it as "panel.create()" then it would. So I could go either way; do you have a strong preference?

from panel.

I do read it as panel.create, which is why I prefer it.

from panel.

Okay, I'm just going to go with pn.panel.

from panel.