When will the API be stable

Community Support
1

I looked a bit into bokeh yesterday and search for tutorials and reviews of it.

I found that half year old reviews use old API’s

The examples on the website are up do date which is nice. But I to use it on a regular basic I want stable API so that my notebooks would keep running in half a year after I update bokeh.

Is there a release target for when the API will be stable?

best Max

2

Hi Max,

Thanks for this important question. Bokeh has more than one API, and they each are at different frontiers of stability:

bokeh.models
  This is the low level object serialization layer. This is very stable at this point. Models
  may gain new properties for new features, but deletions or incompatibilities should be
  extremely rare at this point. Where they do happen, they should be extremely localized and
  not sweeping or general. The exact set of properties is largely covered in the test suite
  so that accidental changes cannot be introduced.

bokeh.plotting
  I would consider this API to be stable at this point. There was a big change in 0.7 to
  switch from a "implicit" interface, to an "explicit" one, a decision based on experience gained
  from usage of the first version of the API. There are no plans or even suggestions that
  anything about this API needs change or revision, and I would not expect there to be anything.
  The switch to "explicit" provided the better manageable interface we were looking for.

bokeh.charts
  This API is under active development, and there will be changes. There is a Bokeh developer meeting
  in Austin at the end of the month, and the plan (and hope) is to nail down the final version of the
  chart interface, so that many new chart types can start to be built on the best foundation.
  Stability here is a few months away.

All that said, Bokeh is still <1.0 and under active development. The above is my perspective on things, but it is possible some circumstance will dictate a change somewhere that I cannot foresee. When that happens, we do try to make deprecations (with DeprecationWarnings issued), although our deprecation cycles are currently fairly short (a release or two). However, we do intend to have a "1.0" release later this year, and that specifically means:

* rigid API versioning maintained under test
* complete documentation for all APIs

I hope this sheds some light on the current and future status of the various Bokeh interfaces.

Regards,

Bryan Van de Ven

···

On May 15, 2015, at 3:59 AM, Max Linke <[email protected]> wrote:

I looked a bit into bokeh yesterday and search for tutorials and reviews of it.

I found that half year old reviews use old API's

Interactive Plotting in IPython Notebook (Part 1/2): Bokeh | PyScience

The examples on the website are up do date which is nice. But I to use it on a regular basic I want stable API so that my notebooks would keep running in half a year after I update bokeh.

Is there a release target for when the API will be stable?

best Max

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/dc0e6856-3260-40d4-8ebe-a7e60f246ff1%40continuum.io\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.

3

Thanks for your answer.

the carts API looks like what I likely want to use in my normal work. It already looks nice but I'll wait until version 1.0 is released or I see a blog-post somewhere saying that the API is looking to be stable.

best Max

···

On 05/15/2015 05:28 PM, Bryan Van de Ven wrote:

Hi Max,

Thanks for this important question. Bokeh has more than one API, and they each are at different frontiers of stability:

bokeh.models
  This is the low level object serialization layer. This is very stable at this point. Models
  may gain new properties for new features, but deletions or incompatibilities should be
  extremely rare at this point. Where they do happen, they should be extremely localized and
  not sweeping or general. The exact set of properties is largely covered in the test suite
  so that accidental changes cannot be introduced.

bokeh.plotting
  I would consider this API to be stable at this point. There was a big change in 0.7 to
  switch from a "implicit" interface, to an "explicit" one, a decision based on experience gained
  from usage of the first version of the API. There are no plans or even suggestions that
  anything about this API needs change or revision, and I would not expect there to be anything.
  The switch to "explicit" provided the better manageable interface we were looking for.

bokeh.charts
  This API is under active development, and there will be changes. There is a Bokeh developer meeting
  in Austin at the end of the month, and the plan (and hope) is to nail down the final version of the
  chart interface, so that many new chart types can start to be built on the best foundation.
  Stability here is a few months away.

All that said, Bokeh is still <1.0 and under active development. The above is my perspective on things, but it is possible some circumstance will dictate a change somewhere that I cannot foresee. When that happens, we do try to make deprecations (with DeprecationWarnings issued), although our deprecation cycles are currently fairly short (a release or two). However, we do intend to have a "1.0" release later this year, and that specifically means:

* rigid API versioning maintained under test
* complete documentation for all APIs

I hope this sheds some light on the current and future status of the various Bokeh interfaces.

Regards,

Bryan Van de Ven

On May 15, 2015, at 3:59 AM, Max Linke <[email protected]> wrote:

I looked a bit into bokeh yesterday and search for tutorials and reviews of it.

I found that half year old reviews use old API's

Interactive Plotting in IPython Notebook (Part 1/2): Bokeh | PyScience

The examples on the website are up do date which is nice. But I to use it on a regular basic I want stable API so that my notebooks would keep running in half a year after I update bokeh.

Is there a release target for when the API will be stable?

best Max

--
You received this message because you are subscribed to the Google Groups "Bokeh Discussion - Public" group.
To unsubscribe from this group and stop receiving emails from it, send an email to [email protected].
To post to this group, send email to [email protected].
To view this discussion on the web visit https://groups.google.com/a/continuum.io/d/msgid/bokeh/dc0e6856-3260-40d4-8ebe-a7e60f246ff1%40continuum.io\.
For more options, visit https://groups.google.com/a/continuum.io/d/optout\.