Hi All,
I wanted to share a few thoughts with everyone about some (small) API changes that are on the horizon. While Bokeh is still 0.x, we have not made hard and fast guarantees about API stability---our formal target for permanent stability is a future 1.0 release. That said, we have tried to maintain a fairly high level of backwards compat with Bokeh. This concern has been reflected in the recent Bokeh Enhancement Proposals (BEPs) that codify and formalize our development and release processes. However, there are a few codebase changes that are currently necessary to move Bokeh forward. With the increasing interest in creating language bindings for Bokeh in other languages, it is important to get these changes out of the way sooner, rather than later, so I'd like to describe them here:
* BokehJS interface changes
The JSON interface to Bokeh has remained quite stable since 0.1. Without diving into too much detail, there is one vestigial inconsistency in the interface ("glyph specs") that has become too problematic. We are going to correct it in the 0.7 release in order to be able to move forward on some other important fronts. Technically, this will probably mean that BokehJS 0.7 will not display plots created with earlier versions. Practically speaking this should have actually very little effect. Standalone documents that embed BokehJS, for instance, will not be affected, nor any documents that load BokehJS from CDN (old versions of BokehJS will always be available on CDN). I mention it here just for the sake of completeness.
* bokeh.plotting interface changes
The original idea being the bokeh.plotting interface was to have a "stateful" matlab style interface. By stateful, it is meant that there is implicitly a "current plot" that all functions act on by default. This style of interface is simple and nice and familiar in some ways, but with a little experience, problems also become apparent. The problems are especially evident in the IPython notebook, where "out of order" cell execution means it is impossible to reliably know where the current plot is. We are going to move to a more object based interface that uses context managers to simplify things. So whereas today you might write:
figure(...)
hold()
circle(...)
rect(...)
wedge(...)
show()
In 0.7 code will look something more like this:
with figure(...) as p:
p.circle(...)
p.rect(...)
p.wedge(...)
With this style of interface, it is always made explicit and clear exactly what plot a given render function is applied to. We will make sure that all the documentation examples are updated and that the release notes contain migration information as well.
* Moving towards 1.0
Finally, I just wanted to mention some of the things we intend to have in place for a 1.0 release:
* versioned APIs with complete tests
* JSON interface validators
* formal deprecation policy described in a BEP
We very much look forward to reaching this point (best guess: 2015 Q2), and appreciate all the support, interest, feedback, and contributions that have helped Bokeh come so far in this past year!
As always please reach out with any questions, or desire to join the Bokeh dev team,
Bryan