Figure() vs figure() design choice question

[jackwayneright]

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!

[Bryan]

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 a Figure, the figure function also put the Figure inside a default layout and did some other things. These was necessary for uninteresting technical reasons that are no longer relevant. Nowadays figure just returns a new Figure 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-op Figure

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.

---

1. 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. ↩︎

[jackwayneright]

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!