Skip to content

Migration Guides

Jump to bottom
Bryan Van de Ven edited this page Oct 20, 2022 · 30 revisions

Migration guides

3.0.0

Bokeh 3.0.0 is a major release with the following most notable changes:

  • Support for legacy web browser (e.g. IE, non-ES6 compliant) was removed (see ).
  • Support for Python 3.7 was removed and for 3.10 added.
  • Layout and CSS interoperability was redesigned and greatly improved (see ).
  • Serialization protocol was redesigned and vastly improved (see ).
  • CSS was modularized and all UI components are now Web components (see ).
  • Django integration was moved to bokeh_django (see ).

This release is primarily targetted at users of bokeh who are not authors of extensions or customized stylesheet. All Python public APIs, except those explicitly marked as experimental, are stable and will not undergo intentional breaking changes in bokeh 3.x.

However, we were unable to finalize CSS APIs and some of bokehjs' APIs in the 3.0 release, and we will continue working on those and stabilize them in bokeh 3.1. Thus we want to make advanced users aware of that fact, which potentially means holdng off migration until then. However, we will still uncourage trying out bokeh 3.0, reporting issues and helping us out with refinement of those APIs for bokeh 3.1.

Dependencies

Bokeh now requires pandas.

Bokeh now requires the package xyzservices for managing tile source metadata.

Deprecations

  • tile_providers.get_providers and tile_providers.Vendors are deprecated. Pass tile specifications (e.g. as string name) directly to add_tile instead.

Additions

  • Switch widget

    Provides a replacement for a checkbox input.

  • varying_alpha_palette

    Generates a palette that is a single color with linearly varying alpha.

Removals

  • bokeh.server.django was moved to a separate project bokeh_django, which should be a drop-in replacement in most cases. bokeh_django was also updated to work with Django 3.x and 4.x.

  • plot_width and plot_height

    These properties have been removed. Use standard width and height for all layout-able models.

  • AuthMixin is replaced by AuthRequestHandler, a sub-class of RequestHandler.

  • legend keyword argument to glyph methods has been removed. Use more specific legend_label, legend_group, and legend_field instead.

  • Oval glyph has removed. Use Ellipse instead.

  • GridSpec has been removed with no replacement.

  • names properties

    Previously, some models could be configured with both a names property and a renderers property. In all cases, names has been removed. Use the renderers property to specify renderers.

  • WidgetBox

    The WidgetBox model and associated convenience function widgetbox have been removed. Use row, column, and grid layouts instead.

  • Markers

    Individual scatter markers, e.g Square, DiamondX have been removed, along with their related glyph methods. Use Scatter and figure.scatter instead.

  • bokeh.util.session_id has been removed. Use bokeh.util.token instead.

  • WebSource model has been removed, use WebDataSource instead.

  • from_networkx function is now only available to import from bokeh.plotting.

  • Distance Specs

    ScreenDistanceSpec and DataDistanceSpec are removed. Use SizeSpec instead.

  • EditTool.custom_icon has been removed. Use Tool.icon property instead.

  • render_mode was removed from all annotations. Annotations were cleanly separated between those which render to canvas and those that use HTML and CSS. The default is canvas rendering. Use the new HTMLTitle, HTMLLabel and HTMLLabelSet models whenever previously css render mode was used. Note that Span and BoxAnnotation do not have an HTML equivalent anymore.

  • FuncTickFormatter has been renamed to CustomJSTickFormatter.

  • HasProps.__subtype__

    Explicit sub-typing support was removed both from models and the protocol. If you want to extend existing models without the need for providing an implementation, then use data models (e.g. extend from DataModel).

  • CDSView.source

    CDSView now implicitly uses the source provided by a glyph renderer it as assigned to. Previously providing a data source in both a glyph renderer and a source view was redundant.

  • CDSView.filters

    filters property was deprecated and replaced with filter property. The original behavior of filters can be replicated with setting filter to IntersectionFilter(operands=filters), or preferably using & operator like cds_view.filter &= other_filter.

  • RadioGroup / CheckboxGroup on_click

    RadioGroup and CheckboxGroup no longer supports on_click event handlers. Use on_change('active', cb) instead.

  • ToolbarProxy was removed. To replicate the original behavior, use ToolProxy in Toolbar model.

  • ToolbarBase abstract base class was merged into Toolbar model.

  • ToolButton abstract base class was merged into Tool model.

  • MyProperty(..., serialized=False)

    serialized argument was removed and serialized=False case was replaced width NotSerialized(MyProperty(...)).

  • MyProperty(..., readonly=True)

    readonly argument was removed and readonly=True case was replaced width Readonly(MyProperty(...)).

Python changes

  • gridplot() return value

    Previously gridplot() returned a combination of Row and Column layouts, depending on the supplied arguments. Additionally, setting merge_tools now tells grid plots to actually merge tools instead of hidding the toolbar. To hide a toolbar, use toolbar_location=None.

  • Tooltip class hierarchy

    Tooltip model was previously exposed to the user, but it wasn't useful on its own. This changed and now Tooltip can be used in various places in bokeh. This required changing its type from Annotation (annotations are canvas specific models) to new UIElement, which is a base class for all user interface related models.

  • ColorBar new attributes

    ColorBar new attributes display_low and display_high can be used to limit the range of colors displayed in a color bar without affecting the underlying color mapping.

  • RGB.to_hex() includes alpha

    Previously RGB.to_hex() ignored the alpha value in the string it returned. Now it is included in the string if it is less than the default value of 1.0.

JavaScript changes

  • figure.xaxis, etc.

    xaxis, yaxis, axis, xgrid, ygrid and grid attributes of figure now return a model proxy object, which mimics the behavior of bokeh's plotting API. Arrays of axes/grids can be obtained using new xaxes, yaxes, axes, xgrids, ygrids and grids attributes.

  • Property changes push to server

    Previously all changes were pushed to server, even if no actual changes were made. Now only effective changes are pushed, which now matches the internal behavior of BokehJS.

  • Deserialization code was split-off from Document

    Now the purpose of Document is to manage models and deal with high-level serialization concerns. Low-level handling was split-off into Deserializer class.

  • HasProps.constructor

    The constructor of HasProps has now two clearly defined code paths, one for deferred and the other immediate initialization. The former is triggered with new HasProps({id}) syntax (it doesn't allow providing initial values) and the later with new HasProps(attrs), where attrs can not have an id field. As a side effect, duplicating model's identity is not permitted by default anymore, though one can still use deferred initializtion for this.

  • init_ModelName was removed

    This static initializer was added automatically by bokehjs' build system and extensions' compiler. This isn't needed anymore as TypeScript supports ES2022 static initialization blocks (static {}).

  • embed_items() and related functions

    Embedding functions now return an instance of ViewManager, instead of a list of constructed views. For backwards compatibility, ViewManager supports iterator protocol.

Layout changes

CSS changes

Shadow DOM and CSS modularization

Bokeh's UI components were migrated to use Shadow DOM and their CSS was modularized. This significantly affects how UI components are implemented.

  • Each UI component needs to provide its own styling.

    Previously it was possible to style UI components with global stylesheets. This is not possible anymore, because each component is isolated and has to provide its own complete set of stylesheets. Override DOMView.styles() method to provide styling for a component.

  • Can't use "global" selectors to access internals of a component.

    For example, one can not expect to set a CSS class on an DOM element and query it from a global stylesheet (this applies to JS querySelector() as well). The exception are CSS variables, which can "pierce" Shadow DOM boundaries. A set of well defined CSS variable will be defined in bokeh 3.1.

  • Use this.shadow_el.append(child_el) instead of this.el.append(child_el).

    Appending to this.el will not fail in any siginificant way, except child elements will not be visible on screen, which could be easily attributed to other issues, like missing or broken CSS stylesheets.

  • Use :host pseudo selector to style a component.

    :host or :host(.a-css-cls) (or another variation) is the only way to actually style the root element of a UI component. To style sub elements of a component, one uses normal CSS selectors.

  • Use Event.composedPath() instead of Event.target.

    Event.target can not "pierce" Shado DOM boundaries, so it will stop on the first boundary, giving unexpected results. Use Event.composedPath() which works with Shadow DOM. One can emulate Event.target by using Event.composedPath()[0].

Protocol changes

  • references attribute was removed and object definitions are now stored in-line
  • nan and +/-inf can be serialized
  • Dataclasses can be serialized
  • Dictionaries with arbitrary keys can be serialized (uses Map in JS)
  • Dictionaries and structures are ordered
  • Binary serialization is now available everywhere (not just for ndarrays)
  • Binary serialization is now bi-directional
  • array.array and be serialized as JS typed arrays
  • Added support for generic ndarrays (dtype=object)
  • Streaming and patching is allowed in any model and property
  • ColumnsStreamed, ColumnsPatched and ColumnDataChanged are now first-class events
  • Support for document event hints was removed
  • old attribute was removed from ModelChanged
  • HasProps is now responsible for model registry (use Local to prevent registration)
  • Model.to_json() and Model.to_json_string() were removed (use Serializer instead)

Serialization of numbers

Outside of ndarrays, nan, +inf and -inf are now systematically serialized as {"type": "number", "value": "nan"}, {"type": "number", "value": "+inf"} and {"type": "number", "value": "-inf"} respectively.

Other changes

  • Minimum.initial and Maximum.initial properties can now have intrinsic default values (infinity and minus infinity respectively) instead of None / null.

  • Tool.computed_overlays was moved to ToolView.overlays, to allow tool views to provide additional overlays.

  • copy_to_clipboard icon was renamed to copy

  • Theme support for color bars has had the key changed from ColorBar to BaseColorBar so that it also supports ContourColorBar.

2.4.0

Dependencies

Bokeh now requires Python 3.7 or higher.

Bokeh no longer requires the package python-dateutil.

Bokeh can optionally use the package xyzservices for managing tile source metadata.

Deprecations

  • ScreenDistanceSpec and DataDistanceSpec are deprecated, and now return a SizeSpec. Custom extensions using these should use SizeSpec instead.

  • PropertyUnitsSpec is deprecated. Use UnitsSpec instead (this is unlikely to impact any typical usage).

  • Document.delete_modules was deprecated and will be removed in the future. Use Document.models.destroy instead.

  • Raw string paths in Image property

    Use pathlib.Path instead.

  • gridplot(plot_width, plot_height) were deprecated

    Use width or height respectively instead.

  • static init_ModelName(): void {} was deprecated

    Use new TypeScript 4.4 static blocks static {} instead. Support for static init_ methods will be removed in bokeh 3.0. This change only affects model providing extensions.

Removals

  • Wikimedia Tile Provider

    Wikimedia has restricted their tile service to only function with Wikimedia domains, and no longer be publicly usable. Accordingly, the WIKIMEDIA tile provider has been removed. Use any of the other tile providers instead.

Python changes

  • curstate().file is now a dataclass

    Previously it was a dict-based ad-hoc data structure. Replace key indexing with attribute access.

  • Units Properties

    Units properties must now be configured with an units_enum that is an enumeration instead of a units_type that is an Enum property:

    units_enum=SpatialUnits # use this
units_type=Enum(SpatialUnits) # NOT this

    This is only of potential interest to custom extensions.

  • bokeh.core.query functions no longer accept callables and/or context in queries. This feature added unnecessary complication and was not used inside the Bokeh codebase (or ever demonstrated in docs or examples).

2.3.1

Python changes

  • HSL class deprecated

    The class bokeh.colors.HSL is deprecated and will be removed in a future release. Use the RGB class, RGB(a) strings, or named colors instead.

2.3.0

  • Properties are non-nullable by default

    Previously, all properties accepted None (null in BokehJS) as a value. As of this release, None is only accepted by properties explicitly marked as nullable, e.g.Nullable(Int) accepts integers and None. All current models and their properties were adjusted as needed, so there will be no difference from users’ perspective. However, custom extensions may require updates if they relied on the old behavior.

  • Primitive and derived properties have default values

    Some properties did not have sensible intrinsic default values (Int defaulted to None, for example). Now all properties have default values, such as 0 for Int, or "" for String. You can remove a default value by marking a property as non-nullable, e.g. NonNullable(Int). In this case, a user is required to set a property value. An attempt to retrieve the value of a non-nullable property before it is set will raise an UnsetValueException.

  • Use Readonly() to indicate readonly properties

    The old syntax, e.g. Int(readonly=True), is still accepted, but will be removed in the future. Use Readonly(Int) instead.

  • ArrowHead is not an annotation anymore

    ArrowHead no longer inherits from the Annotation base class. This will pave the way for vectorizable arrowheads.

  • Four of Bokeh’s base models are renamed

    Certain base models were renamed to unify naming convention with BokehJS:

    Old name New name
    WebSource WebDataSource
    Action ActionTool
    Gesture GestureTool
    Inspect InspectTool

    Old names are retained for compatibility but are deprecated and will be removed in Bokeh 3.0.

  • names properties were deprecated

    DataRange.names, SelectTool.names, and HoverTool.names are deprecated and will be removed in Bokeh 3.0. Use the renderers properties instead, possibly in combination with plot.select(name="renderer name").

  • BokehJS visuals have different semantics

    Previously Line, Fill, Text, and Hatch visuals were used across primitive, scalar, and vector properties. Those are now split into more specific versions, e.g. Line, LineScalar, and LineVector. This should only affect custom extensions that use visuals.

  • Marker models are deprecated

    Marker models like Asterisk, CircleX, X, etc. are deprecated. Use the Scatter glyph with a marker type instead, e.g. replace Asterisk() with Scatter(marker="asterisk"). Marker methods on figure will default to use Scatter glyph. Marker models were removed from BokehJS.

  • Tooltip deprecations

    EditTool.custom_tooltip, HelpTool.help_tooltip and CustomAction.action_tooltip were deprecated Use Tool.description, which can also be used with all other types tools, instead.

  • New "auto" defaults for color bar properties

    ColorBar properties orientation, ticker, and formatter now default to "auto". Previously, these properties had concrete defaults ("vertical", BasicTicker() and BasicTickFormatter() respectively). In most cases, this will not affect user code. However, if you relied on setting e.g. color_bar.ticker.base = 60, then the code will need to be replaced with color_bar.ticker = BasicTicker(base=60).

  • CartesianFrame is not a layout anymore

    This only affects extension creators. CartesianFrame is now responsible only for maintaining the coordinate system of a plot. Use the layout.center_panel of a plot to access any layout-related capability. Note you can still use CartesianFrame.bbox, so most code doesn’t have to change.

  • figure sizing fixed in BokehJS

    Previously, setting plot.frame_width while using sizing_mode:'fixed' did not resize the canvas as expected; the figure would only resize after changing plot.width or plot.plot_width. This behavior has been fixed and now setting plot.width to trigger the resize is no longer needed.

2.2.0

  • Oval glyph deprecated

    The Oval glyph is largely duplicative of the ellipse glyph, and will be removed in version 3.0. Use Ellipse instead.

  • Tooltip.inner_only deprecated

    This property was non-functional an unnecessary and has been removed. No replacement is provided.

  • scenterx and scentery deprecated

    Previosuly, glyphs could implement separate scenterx and scentery to report a “center” location that could anchor hovers. These have been combined in to a single Glyph.scenterxy() method that should be implemented instead. (This change is only relevant if you are implementing a new glyph in Bokeh or in a custom extension.)

  • Implement Renderer._render instead of Renderer.render

    Renderers must implement abstract method _render instead render, which is now “final”. This breaking change affects only extension developers.

2.1.0

  • Minimum Tornado Version

    The minimum tornado version is now 5.1.

  • render_mode deprecated

    Tool overlays are now implemented efficiently on the HTML5 canvas without any separate CSS rendering codepath. This makes the render_mode property obsolete. Accordingly, render_mode is deprecated (and ignored) everywhere it currently appears, and will be removed entirely for Bokeh 3.0 in the future.

2.0.0

  • Minimum Package Versions

    This release raises the minimum version for some packages

    Bokeh now requires Python 3.6 or higher.

    Bokeh now requires Numpy 1.11.3 or higher.

    The Bokeh server now requires Tornado 5.0 or higher.

  • Server Lifecycle Hooks

    Server lifecycle hooks should now goin in a file named app_hooks.py, which is also where new request hooks are to be defined. The previous module name server_lifecycle.py will continue to function, but is deprecated.

  • HoverTool Formatters Specification

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

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

    Now, the full matching tooltip specification, including the "@", should be used:

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

    This allows tooltip formatters to be used uniformly with both columns, as well as “special variables”, e.g. "$x".

  • Bokeh Sphinx Extension

    The obsolete Sphinx configuration parameters bokeh_plot_use_relative_paths and bokeh_plot_pyfile_include_dirs have been removed. The unused PLOT_PAGE template has also been removed.

  • PhantomJS usage retired

    The deprecated and unsupported PhantomJS dependency is no longer used for exporting Bokeh content. Bokeh will use Chromedriver by default, but can also be configured to use Geckodriver.

  • “Use Strict” for CustomJS

    The use_strict property has been 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.

  • require() in CustomJS

  • The require() function s not available from CustomJS anymore. It exposed the underlying module system, which should not be used by general users. Use APIs exposed on Bokeh object or (as a last resort), use Bokeh.require().

  • Bokeh Protocol Versioning

    Bokeh wire protocol messages no longer express any revision, and URLs for server sessions 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).

  • Selection Dicts

    The obsolete old-style selection dictionaries, i.e. selected['1d'] have been removed. Use selected.indices, etc. only.

  • Immutable Palettes

    Previously, Bokeh used a complicated copy-on-access scheme to return palettes as lists. The necessary “module hack” could confuse IDEs, complicated the docs build process, and sometimes lead to unexpected behavior. All palettes are now tuples, which is a simpler solution to the problem of mutable module attributes.

    The main difference is that palettes can no longer be modified in place, including reversing the palette. To reverse a palette, do:

    list(reverse(pal))

  • Tile Providers

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

  • ColumnDataSource Properties

    The ColumnDataSource.selected property is now read-only.

    The ColumnDataSource.data property can only be set from plain Python dicts. Attempting to set from another CDS, i.e s1.data = s2.data, will raise an error.

  • Date and Datetime Properties

    The Date property has been narrowed, in order to afford an unambiguous date type in the form of an ISO date string. The Date type accepts ISO date strings, and datetime.date objects.

    As a result, the DatePicker widget no longer accepts datetime values or timestamps. All values must be valid Date values.

  • The Datetime now accepts timestamps (milliseconds since epoch) directly.

  • Missing Renderers Warning

    The W-1000 (MISSING_RENDERERS) validation warning will no longer trigger for plots that have added annotations, even if no other glyphs are present.

  • UnitsSpec hierarchy

    The UnitsSpec class is now a base class and is not useful ln its own. If you were using UnitsSpec in an extension model, you should change to use the new PropertyUnitsSpec class, which affords the capability for adding separate *_units properties.

  • Broken Bokeh Commands

    The command line utilities bokeh html, bokeh png, and bokeh svg were early experimental tools that were never widely promoted. It was recently discovered that they have been broken since version 1.0, indicating that they are completely unused. To reduce codebase cruft, they have been removed.

  • BOKEH_VERSION

    The previous environment variable BOKEH_VERSION that could be use to specify which version of BokehJS should be loaded from CDN, has been renamed to BOKEH_CDN_VERSION.

  • API Removals

    The following modules and functions were previously deprecated or were internal and no longer needed:

    • bokeh.client Method ClientSession.loop_until_closed removed
    • bokeh.io Function create_webdriver removed, use webdriver_control instead.
    • bokeh.models.callbacks Methods CustomJS.from_py_func and CustomJS.from_coffeescript removed
    • bokeh.models.filters Methods CustomJSFilter.from_py_func and CustomJSFilter.from_coffeescript removed
    • bokeh.models.formatters Methods FuncTickFormatter.from_py_func and FuncTickFormatter.from_coffeescript removed
    • bokeh.models.plots Properties Plot.h_symmetry and Plot.v_symmetry removed
    • bokeh.models.tools Methods CustomJSHover.from_py_func and CustomJSHover.from_coffeescript removed
    • bokeh.models.transforms Methods CustomJSTransform.from_py_func and CustomJSTransform.from_coffeescript removed
    • bokeh.models.widgets.buttons Properties Dropdown.default_value, Dropdown.value and AbstractButton.clicks removed.
    • bokeh.models.widgets.sliders callback, callback_throttle, and callback_policy removed from all sliders. Use value for continuous updates and value_throttled for updates only on mouseup
    • bokeh.plotting.helpers Entire module removed
    • bokeh.protocol Entire versions module removed, messages.register function removed
    • bokeh.util.compiler Class CoffeeScript and related code removed
    • bokeh.util.future Entire module removed
    • bokeh.util.string Functions encode_utf8, decode_utf8, and escape removed

    Additionally, the callback property is removed from all Bokeh models except CustomAction, HoverTool TapTool, and OpenURL. Instead, the more general js_on_change or js_on_event methods should be used.

  • API Deprecations

    The following new deprecations are effective:

    bokeh.layouts.WidgetBox is deprecated use bokeh.layouts.Column instead.

    Importing from_networkx from bokeh.models.graphs is deprecated. Import from bokeh.plotting instead.

1.4.0

Deprecations

The overburdened legend keyword argument to glyph methods is deprecated. It is replaced with three purpose-specific keyword arguments:

legend_label="some_label"

This will always produce a legend item with exactly the given label.

legend_field="some_colname"

This will produce a “grouped” legend, where the grouping is done by JavaScript in the browser. Python code will only see a single legend item representing the grouping.

legend_group="some_colname"

This will produce a “grouped” legend, where the grouping is done by Python code, bedore the content is rendered in the browser. Python code will see individual legend items for each group.

These keywords remove the ambiguities due to the “automagic” operation of legend with respect to legend grouping. The existing legend keyword argument will continue to function until at least version 3.0 of Bokeh.

1.2.0

Discourse Site

The Google Groups mailing list has been retired. In its place, there is now a Discourse site for community discussions. All of the old content from the mailing list has been imported into the Discourse, and is searchable.

Callback Policy

Sliders add a value_throttled property that is updated (and triggers JS and Python callbacks) only according to the callback_policy:

slider.callback_policy = "mouseup"

# both of these will respect the callback policy now
slider.js_on_change('value_throttled', ...)
slider.on_change('value_throttled', ...)

The callbacks above will only execute when the user releases the mouse after adjusting a slider.

Note that the value property can also still be used to trigger callbacks —they will execute unconditionally on every movement.

The old-style callback property still works for JS callbacks, but will be removed in Bokeh 2.0 in the near future. The general js_on_change and on_change methods should be used going forward.

Stacked Areas and Lines

New varea and harea methods add support for single directed areas (filled regions between two series that share a common index). Also added:

  • varea_stack and harea_stack for stacking directed areas,
  • vline_stack and hline_stack for stacking lines.

For example:

colnames = ['y0', 'y1', 'y2', 'y3', 'y4', 'y5', 'y6']

p.varea_stack(colnames, x='index', color=colors, source=df,
            legend=[value(x) for x in colnames])

p.vline_stack(colnames, x='index', color="black", source=df)

Legend Titles

Legends now support displaying a title:

p.legend.title = "Things"

1.1.0

The js_link function was added to make it simpler to link two Bokeh model properties together:

slider.js_link('value', r.glyph, 'radius')

See Linked properties for more information.

The Slider.value_as_date method was added to conveniently retrieve Slider values as date objects when appropriate.

Deprecations

The following features or APIs were deprecated in version 1.1 and will be removed in a future 2.0 release:

  • Support for CoffeeScript in CustomJS or custom extensions. Use JavaScript or Typescript instead.

  • Support for ClientSession.loop_until_closed. This function is intended to support testing only, and will be removed from the public API. Bokeh applications should be run directly on a Bokeh server.

  • Support for “transpiling” Python code to JavaScript. All from_py_func methods will be removed. Use JavaScript or Typescript instead.

Changes to bokeh.sphinxext

  • In order to support a longer term goal of moving Bokeh docs to ReadTheDocs, some changes to the bokeh-plot Sphinx directive were necessary. These are:

  • Plot script files are now always placed immediately adjacent to the document they are for, and loaded using relative URLs.

  • The config values bokeh_plot_pyfile_include_dirs and bokeh_plot_use_relative_paths are no longer needed. Setting them will have no effect (but will not break existing builds). These config values will be removed in a future 2.0 release.

  • We believe that there are very few users of bokeh.sphinxext outside the project itself, and that these changes will not cause any breakage for any of those users. However, please reach out for support if any unforeseen issues arise.

1.0.0

Handling of Selections

Previous versions of Bokeh mistakenly had code paths that could replace data source Selection objects with entirely new instances. This was a mistake, and resulted in several regressions and other problems. Unfortunately, the problem persisted for a few releases, and now that the situation has been fixed, it will require some code changes for some users to adapt to correct usage.

In general, you should NOT ever listen for a change of selections objects themselves, i.e. do not do this (anymore):

source.on_change('selected', callback)  # BAD, DON'T DO THIS

Instead, you should listen for changes to the individual properties that are on Selection objects. For instance, to execute a callback when the indices on a selection change, (e.g. when a selection is made on a scatter plot), do this:

source.selected.on_change('indices', callback)  # GOOD

Any code that looks like the first version above should be updated to use the second version. This applies to both Python or JavaScript callbacks for selections.

While this breaking incompatibility is regrettable, there are now much more extensive integration tests in place to maintain that the second version will always function as expected from now on.

New Dependencies

“Pillow>=4.0” has been added to the list of Bokeh runtime dependencies.

Examples

The following examples have been removed or updated:

  • app/pivot: This large example was unfocused and unmaintained and has been removed
  • embed/simple: Old example removed
  • howto/us_marriages_divorces: Redundant notebook removed, script moved to plotting/file/us_marriages_divorces_hover.py
  • models/file/colorspec.py Old example removed
  • models/file/external_resources.py Moved to latex_extension.py
  • models/file/glyph1.py Moved to basic_plot.py
  • models/file/grid.py Old example removed
  • models/file/line.py Old example removed
  • models/file/transform_jitter_coffee.py Discouraged coffeescript example removed
  • plotting/file/bar_chart.py Removed old/duplicative example
  • plotting/file/brewer.py: Moved to stacked_area.py
  • plotting/file/bollinger.py Old example removed
  • plotting/file/joyplot.py Moved to ridgeplot.py

Pretty printing functions

The pprint and pretty methods depended on IPython pretty-printing in order to function. Recent changes to IPython pretty-printing machinery made it impossible to use unless the “pretty” repr was also enabled. This caused ipython console to be spammed with very large amounts of output, making it unusable. As a result, both pprint and pretty methods have been removed. A “pretty” HTML repr still functions in Jupyter notebooks. This change is not expected to affect any normal usage.

Bokeh Object IDs

Previously Bokeh generated unique UUIDs for every Bokeh object. Starting with this release, Bokeh generates simple increasing integer IDs by default. You can set the environment variable BOKEH_SIMPLE_IDS=no to restore the previous behavior. The generation of simple IDs is faster than UUIDs, otherwise this change is not expected to affect any normal usage. However, if you are creating Bokeh objects for a single Document in separate processes, i.e. by using the multiprocessing module, then you will want to turn off simple IDs. (This is expected to be a rare and unusual usage.)

  • bokeh.util.plot_utils

    The bokeh.util.plot_utils module has been removed. This module contained only private functions used internally. This change is not expected to affect any normal usage.

  • bokeh.server.application_context

    The bokeh.server.application_context module has been renamed to bokeh.server.contexts. This change is not expected to affect any normal usage.

  • arguments parameter for server_session

    The server_session function accepted an arguments parameter that did not (and could not) have any actual effect. It has been removed, immediately. Since the parameter did not function, it is not expected that this change will affect any normal usage.

  • Codebase Tests

    The Pytest “quality” mark has been changed to “codebase”. Now to run the codebase tests, execute pytest -m codebase. If you have installed a pre-commit hook to run quality tests before allowing a commit, the hook code should be updated as above. This change is only expected to affect those who are developing the Bokeh codebase.

Clone this wiki locally