Preview of 2.0 Changes

/ Bryan Van de Ven

Bokeh 2.0 is coming out soon! This post describes some of the changes (large and small) that will happen at that time. All of these changes will be re-iterated and explained in a Migration Guide that will accompany the Bokeh 2.0 release notes.

The first and most important change is that Python 3.6 will become the minimum supported Python version. Many core PyData projects have already moved forward to drop Python 2 support in 2019, and now Bokeh will do the same.

Additionally, Tornado 5 will become the minimum Tornado version for the Bokeh Server.

Given that the changes above necessitate a major number bump, we are also taking the opportunity to make other small breaking changes for the sake of future improvements and maintainability. Generally, the changes fall into these categories:

  • Obsolete and deprecated functions and attributes that will be removed

  • Usage that has resulted in silent errors may raise exceptions immediately

  • Small changes to enable new functionality that is not currently possible.

Hovertool Formatters

Until now, the formatters property accepted a CDS column name. For example a formatter for a tooltip for "@foo could be specied with just "foo":

hover_tool.formatters = { "foo": "datetime"}   # BAD

After 2.0, the full matching tooltip specification, including the "@", must be used:

hover_tool.formatters = { "@foo": "datetime"}   # GOOD

This syntax makes it more clear what the formatter key should match up to (many users tried to match the key with a tooltip label). More importantly, this change will allow tooltip formatters to be used with CDS columns and with “special variables”, e.g. "$x" (which is not possible now).

ColumnDataSource and Selection

  • Obsolete old-style selection dictionaries, i.e. selected['1d'] will be removed. Use the attributes on Selection models, e.g selected.indices.

  • The ColumnDataSource.selected property will become read-only. Only change attributes on the default Selection models, e.g. selected.indices, rather than attempting to replace an entire Selection itself. (Previously this generally resulted in silent errors.)

  • The property will only be settable from plain Python dicts, or Pandas DataFrames. Attempting to set from another CDS, i.e =, will raise an error. (Previously this generally resulted in silent errors.)

CustomJS and Callbacks

  • All deprecated functionality for CoffeeScript and PyScript (i.e. from_coffeescript and from_py_func methods) will be removed everywhere.

  • The callback_throttle and callback_policy properties will be removed from all sliders. Use value for continous updates and value_throttled for updates only on mouseup.

  • Old-style callback properties will be removed generally. Use modern on_change / on_event for Python callbacks in Bokeh server apps, or js_on_change / js_on_event for JavaScript callbacks.

  • The use_strict property will be removed from all models that it had been on previously. All JavaScript code, e.g. for CustomJS will always be rendered with "use_strict" added in all cases.

Tile Providers

The named tile properties in, e.g CARTODBPOSITRON will return a vendor id for that tile provider. This value can be passed to the get_provider method directly to return a new TileProvider instance.

Last Things

There are some other changes that are not expected to be noticeable by the vast majority of users, but we note them here for completeness:

  • The obsolete Sphinx confiuguration parameters bokeh_plot_use_relative_paths and bokeh_plot_pyfile_include_dirs and the unused PLOT_PAGE template will be removed.

  • Bokeh wire protocol messages will no longer express any revision, and URLs for server sessions will no longer specify "bokeh-protocol-version". It is assumed any client and server communicating are the same release version (which has always been true in any usage scenario to date).

  • Deprecated bokeh.client method ClientSession.loop_until_closed will be removed

  • Non-functional Plot properties Plot.h_symmetry and Plot.v_symmetry will removed

  • The bokeh.util.future module will be removed

  • The bokeh.util.string functions encode_utf8, decode_utf8, and escape will removed

The Bokeh team appreciates that changes can be disruptive. We strive to avoid all breaking changes within major-number version series (and to bump major numbers only rarely). The changes that are part of this major number bump will enable features that are currently blocked, and allow scarce contributor time to be utilized more effetively and efficiently in the future. We are grateful for your patience and understanding, and if you run into issues or questions, please come by the Project Discourse for help.

As always, anyone interested in helping out should drop by the Dev Chat Channel and say hello!


Bryan Van de Ven