Hello! I’m just curious about the design choice of having both figure()
and Figure()
(and similar dual APIs). Furthermore, it seems that the documentation prefers figure
the function over Figure
the class initialization. As it seems like an object initialization from the user perspective, I would expect the common convention (and naming scheme) in Python would be figure = Figure()
to create a Figure
instance. Of course, this is not a problem, as Bokeh provides both. I’m just curious as to why figure()
seems to be the preferred approach in the documentation (and if there’s a good argument as to why I should switch to that convention as well). Thank you for your time!
cc @Timo
@jackwayneright This is a topical question, as we have just lately been discussion how to update the docs around this area. By and large the answer to your question is just “history”
-
When Bokeh was first conceived, one of the major priorities was to make it accessible to folks who are only incidentally coders, as part of their science/data science/analyst role, and not trained in computer science, or otherwise professional developers. Towards that end it was thought to center an API around simple functions, rather than starting from OO classes and objects.
-
There was also a time (in the past) when
figure
was needed in order to do real work. In addition to creating aFigure
, thefigure
function also put theFigure
inside a default layout and did some other things. These was necessary for uninteresting technical reasons that are no longer relevant. Nowadaysfigure
just returns a newFigure
and does nothing more.
However as far as I know, we don’t explicitly demonstrate Figure
anywhere in the docs (outside the reference guide) or examples. So figure
is by far the dominant and established API and it’s really not possible to consider changing that at this point, not even on a major release bump (not that I want to, either). It would still be good to find a way to simplify the situation to clarify the user documentation, but unfortunately there are drawbacks, problems, or breakages with all of these possible changes:
figure = Figure
class figure(Figure)
- renaming
Figure
→figure
and inheriting from a no-opFigure
I won’t get into the details but any real change is probably Bokeh 3.0 territory. What I would probably personally advocate for is just renaming Figure
to figure
and getting rid of Figure
entirely. It’s a little unorthodox to have a lower-case class name in Python APIs but it is also not unheard of and I think would be justified in this instance. [1]
As for why you should prefer figure
it is because that is what we have settled on as most supported, what we officially demonstrate, and what is most unlikely to ever change.
-
But to be clear this is not at all decided and just keeping the status quo (for compatibility even at 3.0) is also a highly likely outcome. ↩︎
Thanks for the answer. Makes sense.
I certainly prefer Figure
, but I can understand the difficulty of maintaining both or changing something so ingrained. Luckily, it’s not a major issue (from my side of things). In the worst case, if I was bothered by it enough, I could import figure as Figure
on my end anyway. Though, perhaps the right choice is me giving in to figure
. In any case, thanks again for the details!
This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.