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 regretable, 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 py.test -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.

Max Websocket Message Size¶

A new command line option --websocket-max-message-size for the Bokeh server can be used to configure the Tornado websocket_max_message_size option. The default value is now 20mb, an increase from the previous 10mb implicit default.

New Hover fields¶

Two new hover tooltip fields are now available:

• $name will preint the value of the name property of a glyph that is being hovered over.
• @$name will look up values from a column like a normal @ field, but will use $name as the name of the column.

Both of these are espeically useful in conjunction with stacked bar plots.

BokehJS Build¶

The gulp tool was previously used as the build system for BokehJS. This has been replaced with a smaller and simpler build script. This greatly reduced the number of dependencies required to build BokehJS and a completely clean NPM package security audit was obtained as a side effect.

To build now, run the commandf node make build instead of gulp build. Task names remained unchanged. If you want preserve the old workflow, e.g. to aid git bisect, it is suggested to create an alias for node make, e.g. in bash this would be alias gulp='node make'.

Line Join Default¶

The default line_join style has been changed from miter to bevel, to avoid exaggerating corners where connected lines meet at a sharp angle. The HTML Canvas miterLimit property is meant to prevent such issues, but it does not appear to be respected by current browsers.

Deprecations Removed¶

The following functions, arguments, or features have were previously deprecated with warnings and instructions for new usage, and have now been permanently removed:

• --host argument to bokeh serve
• responsive argument to plots and layout functions
• Plot.toolbar_sticky property
• Tool.plot property
• bokeh.sampledata.population.load_population function
• bokeh.util.notebook module

Release History¶

To support publishing all release information on one page, the bokeh_index_toctree module and contents have been immediately moved to bokeh_releases. Since this facility had no use outside building official Bokeh documentation, no deprecation was given.

CDS column_names property¶

ColumnDataSource models had a Bokeh property column_names for specifying the list of column names in source.data. This information was duplicative and had to be explicitly maintained in a fragile way. It has been replaced by read-only properties in both Python and JavaScript that always accurately report the current column names automatically. Setting column_names is no longer supported, however as this possibility has never been officially documented or demonstrated, it is not expected to affect any standard usage.

Tools renderers property¶

Previously the default value, an empty list, corresponded to automatically choosing all available renderers for hit testing. Now, a new default value "auto" is used for that, so that an empty list can mean “hit test no renderers”. A value of None may also be used to indicate no hit testing should occur. Since there is typically no reason to explicitly set a property to its default value, it is not expected that this change impacts any standard usage.

bokehjs’ source directory renamed¶

To finalize the rewrite of bokehjs in TypeScript, the source directory was renamed from src/coffee to src/lib. This change affects only bokehjs’ contributors or other advanced users (e.g. when repackaging bokehjs with Webpack or other JavaScript module bundler).

BOKEH_DOCS_MISSING_API_KEY_OK environment variable¶

This environment variable is no longer used by Bokeh. Previously, the bokeh.sphinxext plot directive would always fail by default if a GOOGLE_API_KEY environment variable was not defined, and this environment variable could be set to override that default behavior. Now, builds will succeed by default, even witout a Google API key defined (but Google Maps plots will not fully render). To require an API be defined (i.e. to restore the previous behavior) you can now set bokeh_missing_google_api_key_ok = False in the Sphinx config file.

DataTable¶

The mis-named property DataTable.row_header has been deprecated. This property confusingly controlled the presence of an index column in a DataTable. Now, use the index_position property to specify where an index column should be located in the table (use None to suppress the index column).

Additionally, new properties index_header and index_width are now available to further customize the index column appearance.

Selections¶

The handling of selections has needed attention in Bokeh for some time. This release adds a new Bokeh model Selection to represent selections on data sources. Having a proper Bokeh model makes selections simpler to use and to synchronize in apps than the previous “bare dict” that represented selections.

The new Selection model is found in the same location on data sources, i.e. source.selected. It has the following properties:

.indices            # which scatter typer indices have been hit
                    # previously selected["1d"].indices

.line_indices       # which point(s) on a line have been hit
                    # previously selected["0d"].indices

.multiline_indices  # which points on which line of a MultiLine
                    # previously selected["2d"].indices

In the near future, a property image_indices will be added to support hit testing of image glyphs.

All code should update to use these new properties. For now read only access to things like selected['1d'].indicies will continue to function as before for compatibility. However, programmtically setting selections must now go through the mode properties, i.e. .indices, .line_indices, etc.

Grid Bounds¶

Grids now automatically defer to any existing axis bounds when their own bounds are set to “auto”. Previously grids used always used the full range bounds. This change makes it simpler to have axes and grids both use a consistent set of bounds.

Minor Ticks¶

Minor ticks are no longer displayed outside explicitly set axis bounds. Previously minor ticks would display one extra “major tick” distance outside explicit range bounds.

NO_DATA_RENDERERS¶

This validation warning resulted in false or irrelevant warnings in many reasonable configurations, and has been removed.

Document and ServerContext callbacks¶

All Document and ServerContext methods that add callbacks can now add the same callback multiple times. Methods that remove callbacks now receive the value returned from a previous method call that added the callback. Example:

# Was
doc.add_next_tick_callback(my_cb)
doc.remove_next_tick_callback(my_cb)

# Now
cb_id = doc.add_next_tick_callback(my_cb)
doc.remove_next_tick_callback(cb_id)

Sphinx Version¶

The bokeh.sphinxext Sphinx extension has been updated to work with currnt versions. Sphinx >= 1.6 is now required to use the extension.

Deprecations Removed¶

The following deprecated features have been removed in this release:

• DynamicImageRenderer (consider GeoViews instead)
• BokehJS support for *.tsx templates (not typically user-facing)
• autoload_server (use server_document or server_session instead)

New Runtime Dependency¶

The package packaging, available via both conda and pip, was added as a new runtime dependency.

Mapping of Unknown Catgorical Factors¶

Previously, data (e.g in a CDS column) referring to a categorical factor that did not exist in the relevant FactorRange, would cause an error in the browser. Now, any such attempted mappings will silently return NaN. Any data points with these factors as coordinates will not render.

The practical motivation for this change is that updating a FactorRange to have a new set of factors could result in an inconsistency triggering the error condition, causing plots to fail to render. With this change, the use-case of updating factor ranges should work more smoothly, however there will be no immediate indication of problems in case “bad” factors are included accidentally in data other than the data points not being rendered.

Change To Text Glyph Legend¶

Previously Text Glyphs added to legends would always unconditionally render the word “text” as the visual symbol, which was not useful. Now, text glyphs render an empty space in legends. This is helpful when it is desired to use an interactive legend mute or hide both a primary glyph, as well as some associated text that goes with it. For more discssion, see #7337.

MercatorTileSource change¶

MercatorTileSource models previously snapped to the closest zoom level resulting in user supplied axis ranges to be largely ignored. The default behavior has now been changed from snapping to the closest zoom level to simply maintaining the correct aspect ratio, while keeping the user defined bounds contained within the axis ranges.

The old behavior may be restored by setting enabling the snap_to_zoom property.

Defining views’ CSS classes¶

This was previously done through MyView.prototype.className, which didn’t respect class structure, so it was often necessary to duplicate CSS rules in sub-views. The new approach is to override css_classes() method, e.g.:

class MyView extends MyOtherView {
    css_classes() {
        return super.css_classes().concat("my-view")
    }
}

This change affects only creators of custom extensions.

HasProps.initialize()¶

Previously HasProps.initialize() took attrs and options as its arguments. This was nearly never used and so it was removed. The preferred way to configure values of attributes is to use bokehjs’ properties system. This change affects only creators of custom extensions.

BokehJS Changes¶

bokehjs doesn’t require custom styles to make “responsive” layout modes work anymore. This means that there are no additional styles added a page, like margins. This results in margins working differently and now default to browser defaults. If you want to restore the previous behavior, then add the following to your HTML:

<style>
  html {
    width: 100%;
    height: 100%;
  }
  body {
    width: 90%;
    height: 100%;
    margin: auto;
  }
</style>

BokehJS Changes¶

To help with the eventual migration to TypeScript, we have switched to the new CoffeeScript compiler. This should be completely transparent to standard users but custom extensions may need small changes in some specific cases, for example, the “Ion Range Slider” required the following change:

-      onChange: @slide,
-      onFinish: @slidestop
+      onChange: (data) => @slide(data),
+      onFinish: (data) => @slidestop(data),

Shorthand initialization syntax for Range1d(start, end) in bokehjs was removed due to technical difficulties. Use full new Range1d({start, end}) syntax instead. The short syntax may be restored at some point as a part of bokeh-api package.

The coordinate system of canvas layout and related infrastructure (positioning, hit testing, etc.) is new “screen”, where the origin is left-top corner of the canvas. This change shouldn’t affect users, however it affects custom model developers. Follow updated examples for new development patterns.

Deprecations Removed¶

The following previous deprecations have been removed:

• app_path from functions in bokeh.client.session and bokeh.embed
• standalone_html_page_for_models from bokeh.embed
• 'patch' and 'stream' event names (use 'patching' and 'streaming')
• webgl, x_mapper_type, y_mapper_type, and tool_events from Plot
• Glyphs methods now only accept either all sequence literals, OR all column names
• ResizeTool (previously made a no-op) has been removed

New Deprecations¶

The boolean responsive parameter to Figure and bokeh.layouts has been deprecated. The sizing_mode enum should be used instead. Use sizing_mode='fixed' for responsive=False and sizing_mode='scale_width' for responsive=True instead.

The function bokeh.sampledata.population.load_population has been deprecated. Use the attribute bokeh.sampledata.population.data instead.

Code Moves¶

The module bokeh.util.notebook has been deprecated. The functions it contains have been moved to bokeh.io.notebook.

The function bokeh.io.set_curdoc is now bokeh.io.doc.set_curdoc.

Named color objects now live in bokeh.colors.named instead of directly in bokeh.colors. Additionally color utilities such as NamedColor have been moved inside the package, and marked as internal API. Using string names for colors works exactly as before.

Dead Code Removal¶

The following unused code was removed immediately:

• Aggregation from bokeh.core.enums
• PyPy detection functions from bokeh.util
• Zeppelin related code (support should come from external notebook hook)

Additionally the attribute bokeh.__base_version__ was removed. Computing it at all times made importing Bokeh take substantial fractions of a second longer than necessary. It is not expected this change should affect any users, but if you need this value, the bokeh.util.version.base_version function can be used.

Deprecated bokeh.charts support removed¶

The bokeh.charts module, which was simply a compatibility shim to load the separate bkcharts package, has been removed. Additionally, Bokeh itself no longer lists bkcharts as a dependency. In order to continue using bkcharts code, the bkcharts package must be installed separately.

Deprecated MPL compatibility removed¶

The bokeh.mpl module and all supporting code in bokeh.core.compat has been removed. Bokeh no longer offers or attempts any automatic MPL conversion.

Table Date Formatter Changes¶

A regression in 0.12.7 caused the DateFormatter to stop functioning. The problem has been fixed, however instead of the previously accepted JQuery style formats, the``format`` property now only accepts

• standard strftime format strings (making it consistent with DatetimeTickFormatter)

• any of the following additional predefined formats names:

  Format name(s)	Format string	Example Output
  ATOM / W3C / RFC-3339 / ISO-8601	"%Y-%m-%d"	2014-03-01
  COOKIE	"%a, %d %b %Y"	Sat, 01 Mar 2014
  RFC-850	"%A, %d-%b-%y"	Saturday, 01-Mar-14
  RFC-1123 / RFC-2822	"%a, %e %b %Y"	Sat, 1 Mar 2014
  RSS / RFC-822 / RFC-1036	"%a, %e %b %y"	Sat, 1 Mar 14
  TIMESTAMP	(ms since epoch)	1393632000000

  Note that the previously available format name TICKS is no longer supported.

Old Testing Functions Removed¶

The functions bokeh.test and bokeh.util.testing.runtests have been removed immediately. Tests should be run as described in the testing section of the Developer’s Guide.

The function bokeh.util.testing.print_versions has been removed immediately. The bokeh info command (or python -m bokeh info) should be used instead.

Refactor of bokeh.client and bokeh.document¶

The bokeh.client and bokeh.document packages were refactored, to make maintenance and testing simpler, and to improve overall code quality. No commonly used or demonstrated public APIs were affected, (no example code required any changes). The other files that were moved or changed are not expected to impact user code.

End of Official Support for Python 3.4¶

Starting with this release, Bokeh is no longer continuously tested against Python 3.4. Use of Bokeh with Python 3.4 will very likely still work, but there are no longer any guarantees backed by CI testing.

Breakage Related to Categoricals Overhaul¶

Bokeh support for Categorical data has needed attention for some time. The release brings improvements that dramatically improve the user experience when using categorical data with Bokeh. For details and examples, see the new User’s Guide chapter Handling Categorical Data.

At this point we endeavor to minimize breakage, and to provide managed deprecation cycles when things must change. However, in this instance, some minor immediate breaking changes were unavoidable:

• min_interval and max_interval on FactorRange are now given in synthetic coordinate units.
• bounds on FactorRange are now given in synthetic coordinate units.

New Embed Functions for Bokeh Applications¶

Two new embed functions similar to autoload_server are added, that have simpler APIs and are more focused:

• bokeh.embed.server_document() for embedding new sessions for entire Bokeh documents in HTML pages. (More common)
• bokeh.embed.server_session() for embedding existing sessions for specified Bokeh models in HTML pages (Less common)

Additionally, with these new methods one may choose to not load the JS/CSS resource files by passing resources="none" as a parameter.

Deprecations Removed¶

The following previously deprecated modules or features have been removed:

• bokeh.icons module
• Legacy anchor and legend locations left_center and right_center
• ImageRGBA.rows and ImageRGBA.cols properties
• HBox and VBox in bokeh.layouts
• validate keyword argument for bokeh.io.save

New Deprecations¶

bokeh.embed.autoload_server has been deprecated and replaced with the two simpler functions server_document() and server_session() described above.

bokeh.models.tools.tool_events has been deprecated. Users should instead use the SelectionGeometry event present on Plot or Figure.

DynamicImageRenderer and Plot.add_dyanamic_image have been deprecated. For GIS-related use-cases built on top of Bokeh, consider using GeoViews, or creating a Custom Extension.

ResizeTool is deprecated and also immediately is a NO-OP on the Python side. ResizeTool has been removed from BokehJS entirely.

BokehJS Widgets Bundle Split¶

The bokeh-widgets bundle was split into bokeh-widgets and bokeh-tables. This is to reduce the weight of the main widgets’ bundle. Bokeh includes bokeh-tables automatically when necessary, so this change should be transparent for most users. However, users of custom templates or other advanced embedding scenarios (including the use of components) may be affected. In short, if your application is responsible for loading Bokeh resources, then it should take care of loading the bokeh-tables as well.

TapTool Callback Calling Convention¶

The TapTool strayed from usual callback calling convention by passing a glyph data source as cb_obj. This has been rectified, and now the tool follows the usual convetion: the tool itself is passed as cb_obj and the data source is passed as part of the optional cb_data. Existing usage of OpenURL is unaffected by this change, but any CustomJS callbacks used with the tap tool will need to be updated to reflect this change.

DataTable Selection Highlighting Signal¶

The DataTable now responds to the signal source.change.emit(), instead of source.properties.selected.change.emit(), to visually highlight the rows in the DataTable that are part of the selection. If you have used source.properties.selected.change.emit() in CustomJS code, you will need to change it to source.change.emit().

The DataTable responds automatically to changes in its data source’s selected property. However, because of Bokeh’s change detection machinery, only a replacement of the selected property causes a change signal to be emitted, and not a partial update (e.g. source.selected['1d']['indices'] = [1, 2]). If you use a partial update in CustomJS code, you will need to emit the change signal yourself:

customjs = CustomJS(args=dict(source=source), code="""
    source['selected']['1d'].indices = [1, 2]
    source.change.emit();
""")

Refactoring of bokeh.server contents¶

The bokeh.server module was refactored in order to be easier to document and maintain, as well as simpler for user’s to use in more sophisticated use cases. These changes are not expected to impact standard usage of Bokeh in any way:

• All protocol-related code was moved to a new module bokeh.protocol
• The Server class was split into Server (no API changes) and a new BaseServer that can be used when explicit coordination of low level Tornado components is required.
• Missing sections added to reference guide, and docsctring coverage greatly expanded.
• Old cruft code to handle Tornado < 4.3 (which is no longer supported) was removed.

New deprecations¶

The Plot.webgl property has been deprecated in place of a new property Plot.output_backend in order to avoid conflicts between WebGL and a new SVG backend. If you are using plot.webgl = True, you should switch to setting plot.output_backend = "webgl" for the future.

Old deprecations removed¶

All previous deprecations up to 0.12.3 have be removed. Below is the complete list of removals.

• Deprecated Button.type property has been removed.
• Deprecated Legend properties: legends, legend_margin, legend_padding, legend_spacing have been removed.
• Deprecated DatetimeTickFormatter.formats property has been removed.
• Tool dimensions may not only be specified with enum values.

New models for Scales¶

The following BokehJS classes have been moved and renamed:

Previously, these Mapper classes were internal implementation details. The new Scale classes are first-class Bokeh models and are accessible from Python. This was done to facilitate future work supporting custom, user-defined scales.

There is a new Plot validation check to ensure that Scales and Ranges on a dimension are compatible. By default, Plot models are configured with LinearScale models which (along with LogScale models) are compatible with Range1d and DataRange1d range models.

One inevitable breaking change is that users employing a FactorRange in the bokeh.model API will have to specify a CategoricalScale on the same dimension. For example:

plot = Plot()
plot.x_range = DataRange1d()
plot.y_range = FactorRange(["Mon", "Tues", "Wed", "Thurs", "Fri"])
plot.y_scale = CategoricalScale()

The bokeh.plotting.figure function should this range and scale compatibility handling automagically in most cases.

As part of this work, some BokehJS attributes were renamed to be consistent with the new terminology:

Since these attributes may be present in user code (e.g CustomJS callbacks or extensions), the old names will continue to work for some time, with a deprecation warning in the JS console.

New signaling API¶

Previously BokehJS used Backbone events for communication between models. As part of an ongoing migration to TypeScript, the Backbone dependency was removed, and the relevant portion replaces with a minimal, type-safe API for signaling.

This change primarily affects contributors working on BokehJS and writers of extensions.

Python Datetime handling¶

Bokeh has not handled Python datetime values consistently with NumPy datetime64. Bokeh aims to treat all datetime values “as-is”, but in some cases a local timezone conversion could affect Python datetime values. This has been corrected. In case there is code that depends on the erroneous behavior, please note that the new behavior is effective immediately and is now maintained under test to be consistent with NumPy values. See the issue #5499 for more details.

Layout API and behaviour changes¶

Layout was previously handled on document level and there was one solver per document. This was changed to one solver per root, so document isn’t anymore responsible for any layout related stuff. All logic and APIs were moved to views, specifically to LayoutDOM. For example, if your code relied on document.resize(width, height), then you should use view.resize(width, height), where view is an associated view of any of document’s root models. Views can be obtained through Bokeh.index. To resize all roots use

for (var key in Bokeh.index) {
    Bokeh.index[key].resize(width, height);
}

New Deprecations¶

MPL COMPATIBLITY IS DEPRECATED

Bokeh’s MPL compatibility was implemented using a third-party library that only exposes a small fraction of all Matplotlib functionality, and is now no longer being actively maintained. The Bokeh team unfortunately does not have the resources to continue supporting this functionality, which was never more than extremely limited in capability, and often produced substandard results. Accordingly, in order to support the long term health of the project, it has been decided to remove all MPL compatibility support on the occasion of a 1.0 release. Any code that currently uses to_bokeh will continue to work with a deprecation warning until that time.

The bokeh.embed.standalone_html_page_for_models method has been deprecated in place of bokeh.embed.file_html. For details see pull request 5978.

The validate keyword argument to bokeh.io.save has been deprecated. Future usage of bokeh.io.save will always validate the document before outputting a file.

Deprecations removed¶

All previous deprecations up to 0.12.0 have be removed. Below is the complete list of removals.

Modules and functions and classes that have been removed:

The methods bokeh.document.add and push_notebook of ColumnDataSource have been removed.

The bokeh.io.output_server function has been also been removed. Additionally, bokeh.io.push and other supporting functions or properties that are useless without output_server have been removed. This includes any transitive imports of these functions from other modules.

Additionally, the property bokeh.charts.builder.Builder.sort_legend was removed, as well as the following properties of Plot

• border_fill
• background_fill
• logo
• responsive
• title_text_align
• title_text_alpha
• title_text_baseline
• title_text_color
• title_text_font
• title_text_font_size

Host Parameter Obsoleted¶

The --host parameter is now unnecessary. For compatibility, supplying it will currently cause a warning to be displayed, but it will otherwise be ignored, and apps will run as normal. In a future release, supplying it will result in an error.

The --host parameter for the Bokeh server was confusing and difficult to explain. As long as the Bokeh server relied on the HTTP “host” header to provide URLs to resources, the --host parameter was a necessary precaution against certain kinds of HTTP spoofing attacks. However, the Bokeh server has been updated to no longer require the use of the “host” header (and this is maintained under test). Accordingly, there is no need to have any check on the value of the “host” header, and so --host is no longer needed.

Document and Model Refactoring¶

In order that document.py and models.py only contain things that might be of usual interest to users, some changes and rearrangements were made.

The abstract class decorator was moved from models.py to has_props.py. The class decorator now also adds an admonition to the docstring of any class marked abstract that it is not useful to instantiate directly.

The metaclass Viewable has been renamed to MetaModel.

The document.py module has been split up, and parts that would not be of normal interest to most users have been moved to better locations.

These changes are not expected to impact user code in any way. For complete details see pull request 5786.

JQuery and underscore.js removed from BokehJS¶

JQuery has been removed as a build dependency of BokehJS. The variable Bokeh.$ is no longer available. If you require JQuery (i.e. for a custom extension or when using the JavaScript API) you will need to provide it explicitly.

underscore.js has been removed as a build dependency of BokehJS. The variable Bokeh._ is no longer available. If you require underscore.js (i.e. for a custom extension or when using the JavaScript API) you will need to provide it explicitly.

Both of these removals together result in a ~10% reduction in the size of the minified BokehJS library.

Default tooltip position for lines changed to nearest point¶

When showing tooltips for lines, the new default is to label the nearest point, instead of the previous point, which used to be the default.

HTTP Request information for apps limited to query arguments¶

The request previously attribute was added to session contexts as a way to expose HTTP query parameters. It was discovered that providing the entire request is not compatible with the usage of --num-procs. A method was found to satisfy the original feature request for query arguments, together with --num-procs (but only for query arguments). Accordingly the only attribute that can now be accessed on request is .arguments, e.g.:

curdoc().session_context.request.arguments

Attempting to access any other attribute on request will result in an error.

Default save file¶

If user-specified or default destination cannot be written to, a temporary file is generated instead. This mostly affects using output_file in an interactive session which formerly could result in a PermissionError. For details see pull request 5942.

The bokeh.io.save method will now only accept a LayoutDOM object and no longer a Document object for its obj argument. This aligns the bokeh.io.save argument types with bokeh.io.show.

Reorganization of bokeh’s examples¶

Low-level examples, located under examples/models, were split into file and server examples and are available under examples/models/file and examples/models/server respectively (similarly to plotting examples).

Enabling WebGL via URL parameters disallowed¶

Previously it was possible to enable WebGL with ?webgl=1 URL parameter. With addition of a separate bokeh-gl bundle, this usage is no longer supportable. WebGL rendering is still configurable using the Plot.webgl property.

Broken Dialog Removed¶

The Dialog widget has been broken for some time. Due to lack of user reports about it, and because custom extensions now provide a path for users to integrate third party JS dialog libaries, this widget has been removed immediately.

Custom Extension Import/Export¶

BokehJS is making a slow migration to TypeScript to support long-term stability and maintainability. This necessitates some short term changes for writing custom extensions.

JavaScript extension code with requires and module.exports, such as:

Model = require "model"

class DateGapTickFormatter extends TickFormatter
    # implementation here

module.exports =
    Model: DateGapTickFormatter

should be re-written as:

import {Model} from "model"

export class DateGapTickFormatter extends TickFormatter
    # implementation here

Legend Locations¶

To improve consistency, the following locations names have changed:

The old location names will continue to work for some time with a deprecation warning.

App Current Directory¶

Directory style apps no longer chdir into the app directory. The module attribute __file__ should be used to construct any file paths relative to main.py for use with open, etc.

Window Titles¶

Bokeh apps embedded with autoload_server will no longer set the browser window title.

Positional Argument Order For hbar¶

In order to provide much improved interactive help (true function signatures and rich auto-generated docstrings) the order of the left and right parameters to hbar had to be swapped (cannot have non-default args after a default arg). The new function signature is:

p.hbar(y, height, right, left=0, **kwargs)

Old bokeh-server Command Removed¶

Since 0.11, the old bokeh-server command remained and only printed a message directing to information about using bokeh serve. It has been removed completely.

Cruft auto Functions removed¶

The following functions in bokeh.io were long unused and have been removed: autoadd, autopush, and autosave.

Eco Templates No Longer Supported¶

BokehJS has migrated to using .tsx templates. Provisional support for including .eco templates has been removed from both BokehJS and the Bokeh Python library.

Base64 serialisation and Python 3.3¶

The addition a binary protocol that uses a base 64 encoding for NumPy arrays means that Bokeh will not function with NumPy arrays on Python 3.3, due to a bug in Python. A possible workaround is to convert all arrays to plain python lists. As a reminder, Bokeh official support includes Python 2.7 and 3.4+ only.

BokehJS BackboneView $ Removed¶

In part of a longer effort to remove the JQuery dependency from BokehJS entirely, the $ attribute that BokehJS added to BackboneView has been removed. Use e.g., @$el.find instead.

Additionally, use of Bokeh.$ and Bokeh._

Refactor of bokeh.core¶

It is expected that all of these these changes should be below the level that standard users will ever be exposed to. These changes are listed here for completeness.

The overly large bokeh.core.properties module has been split up. This improves maintainability and allows the contents of bokeh.core.properties to limited to things of that might be useful to users writing custom models. The new file structure:

• bokeh.core.has_props
• bokeh.core.properties
• bokeh.core.property.bases
• bokeh.core.property.containers
• bokeh.core.property.descriptors
• bokeh.core.property.descriptor_factory
• bokeh.core.property.override

The following class names have been changed to improve intent and clarity (i.e. only things that are actually Python descriptors are named “Descriptor”):

The following unused and non-useful properties were removed in this effort: Align, Event, Function, and This.

The default value for the owner parameter of the __get__ method on property descriptors was an unnecessary change to the standard Python descriptor protocol, and has been removed.

Additionally, the HasProps.set method has been removed. The name caused problems with the Sphinx docs build, and it was an unnecessary duplicate of HasProps.update (which should be used instead).

Specifying Font Sizes¶

Setting text font size properties directly as strings (e.g. font_size="10pt") has been UN-DEPRECATED. This usage will continue to work, without any further deprecation warning. (https://github.com/bokeh/bokeh/pull/5274)

output_server¶

The output_server function is deprecated and will be removed in the near future. Use bokeh.client functions such as push_session instead. (https://github.com/bokeh/bokeh/pull/5225)

Glyph Methods and Data Sources¶

It is now deprecated to supply both sequence literals and an explicit source to glyph methods. For example:

p.circle([1,2,3], y='foo', source=source)  # BAD

Either provide only sequence literals, e.g:

p.circle([1,2,3], y=[4,5,6])

or put all data into the explicitly provided source, e.g:

p.circle(x='foo, y='foo', source=source)

The older usage will continue to function for some time with a deprecation warning, and will result in an error in a future release. (https://github.com/bokeh/bokeh/pull/5187)

FuncTickFormatter¶

FuncTickFormatter instances using JavaScript or CoffeeScript now require code snippets (i.e., function bodies) instead of full function definitions. Additionally, these formatters now accept Bokeh models as arguments so that the models can be readily available to the formatter function code. (https://github.com/bokeh/bokeh/pull/4659/files)

Legend¶

Several legend properties had duplicative legend_ prefixes. The following property names have been changed:

The old property names will continue to work for some time with a deprecation warning.

Additionally, the legends property of Legend has been renamed to items, and given a new type. The new type now accepts a list of LegendItem models, instead of a list of tuples. The previous format is still accepted for convenience and compatibility and values are converted automatically. The legends property will also continue to work for some time with a deprecation warning.(https://github.com/bokeh/bokeh/pull/5229)

Dimensions¶

Specifying dimensions for tools has changed. The 'x' and 'y' aliases for 'width' and 'height' have been immediately removed. Additionally, instead of List(Enum(Dimension), dimensions are now specified more simply as Enum(Dimension) with valid values "width", "height", and "both". The previous format will continue to work for some time and be converted automatically with a deprecation warning. (https://github.com/bokeh/bokeh/pull/5225)

BokehJS Notes¶

• The BokehJS codebase organization has been cleaned up. The file common/hittest.coffee has been moved to core/hittest.coffee. Other files that are unlikely to be used directly by users have also been moved. (https://github.com/bokeh/bokeh/pull/5266)
• The BokehJS class GlyphView no longer inherits from Renderer.View, it now subclasses BokehView. (https://github.com/bokeh/bokeh/pull/5189)
• The BokehJS palettes are now only available in the bokeh-api.js bundle, and not in bokeh.[min].js (https://github.com/bokeh/bokeh/pull/5183)
• The BokehJS bundle bokeh-compiler.js has been removed completely. All Coffeescript code (for extension modules, etc.) is now pre-compiled by the Bokeh Python library. (https://github.com/bokeh/bokeh/pull/4946)

Jupyter Notebook output changes¶

As part of the changes to ensure that the BokehJS client library has loaded before attempting to render plots in the notebook, a new notebook_handle argument was added to the bokeh.io.show method. When set to True (with output_notebook enabled), the show method will return a handle that can be used with push_notebook.

For users who rely on the notebook handles to update plots out of their render order, you’ll have to add notebook_handle=True to your show invocations like below:

from bokeh.plotting import figure
from bokeh.io import output_notebook, push_notebook, show
output_notebook()
plot = figure()
plot.circle([1,2,3], [4,6,5])
handle = show(plot, notebook_handle=True)
# Update the plot title in the earlier cell
plot.title = "New Title"
push_notebook(handle=handle)

BokehJS API Changes¶

In order to shrink the size of the main BokehJS library and reduce pageload times, the Bokeh JS API has been separated into it’s own bokeh-api(.min).js bundle. For users requiring the JS API, it will be necessary to add the new resource to their HTML templates.

Google Maps¶

Google has made a change to their terms of use for google maps, and “effective immediately”, ALL google maps API calls MUST have an API key, or they will not function:

http://googlegeodevelopers.blogspot.mx/2016/06/building-for-scale-updates-to-google.html

All Bokeh GMapPlot models must have their api_key property set, or they will not function properly. PLEASE NOTE: all previously created GMap plots from any previous version of Bokeh are affect by this TOS change.

Examples¶

All WebGL examples have been moved under examples/webgl. The timeout.py and random_tiles app examples have been removed in favor of new, better examples. Several examples of new layout capability are under examples/howto/layout.

BokehJS¶

The mechanism for declaring properties on BokehJS has changed, with the addition of the @define, @override and @internal methods. This may affect existing custom extesnions. Until now, BokehJS details were considered an internal implementation detail. In the future, more attention will be given to BokehJS stability.

Deprecations and Compatibility¶

The new layout work was a large undertaking. As a result, there are many deprecations, including hplot, vplot, etc. Almost all old functions will continue to function, while issuing deprecation warnings. However, there are newer functions that should be preferred. The most up-to-date guidance for layout going forward is at:

https://bokeh.pydata.org/en/latest/docs/user_guide/layout.html

In most cases it was possible to move forward with a deprecation, for the time being, but there are two small hard compatibility breaks that could not be avoided: