.. _release-2-0-0:

2.0.0
=====

Bokeh Version ``2.0.0`` (March 2020) is a major milestone of the Bokeh project.
This release cycle closed more than 180 issues. Highlights include:

* New, modern  ``MultiChoice`` widget added :bokeh-issue:`9532`
* BokehJS CDN resources are loaded with `SRI hashes`_ enabled :bokeh-issue:`8937`
* New ``DatePicker`` implementation with more features :bokeh-issue:`9509`, :bokeh-issue:`9494`, :bokeh-issue:`6728`, :bokeh-issue:`8917`
* Package relative imports work in directory-style Bokeh apps :bokeh-issue:`9545`
* App sessions now use an expirable token that is not visible in query arguments :bokeh-issue:`3458`
* Full HTTP header and cookies can be accessed by Bokeh app code :bokeh-issue:`9505`
* Reference documentation show inherited properties on all Bokeh models :bokeh-issue:`4966`
* IPyWidgets can be used in Bokeh applications, and Bokeh content can be put in IPyWidgets :bokeh-issue:`9590`
* Added tile providers for ESRI and OSM :bokeh-issue:`9560`

And several other bug fixes and docs additions. For full details see the
:bokeh-tree:`CHANGELOG`.

.. _release-2-0-0-migration:

`Migration Guide <releases.html#release-2-0-0-migration>`__
-----------------------------------------------------------

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"``:

.. code-block:: python

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

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

.. code-block:: python

    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:

.. code-block:: python

    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.

.. _SRI hashes: https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity
