Provide a collection of general utilities usefil for implementing Bokeh functionality.
view(location, browser=None, new='same', autoraise=True)¶
Opens a browser to view the specified location.
- location (str) – Location to open If location does not begin with “http:” it is assumed to be a file path on the local filesystem.
- browser (str) – what browser to use
- new (str) –
How to open the location. Valid values are:
"same"- open in the current tab
"tab"- open a new tab in the current window
"window"- open in a new window
- autoraise (bool) – Whether to raise the new location
CallbackManager mixin class for adding an
callback interface to classes.
A mixin class to provide an interface for registering and triggering callbacks.
Add a callback on this object to trigger when
Remove a callback from this object
Utilities for checking dependencies
Attempt to import an optional dependency.
Silently returns None if the requested module is not available.
Parameters: mod_name (str) – name of the optional module to try to import Returns: imported module or None, if import fails
Attempt to import a required dependency.
Raises a RuntimeError if the requested module is not available.
Deprecation framework for Bokeh.
To mark a method or function as being deprecated do this:
from bokeh.util.deprecate import deprecated @deprecated(("Bokeh 0.11.0", "other_thing") def bad_thing(self, first, second): ''' Docstring for bad_thing. ''' pass
bad_thing will issue a warning when called. It will
also have a deprecation notice appended to its docstring.
To mark an entire module as deprecated do this:
from bokeh.util.deprecate import deprecated_module deprecated_module('foo.bar', '0.11', 'use baz.quux instead')
foo.bar will issue a warning whenever it is imported.
DeprecationWarningsubclass for Bokeh deprecations. Used to selectively filter Bokeh deprecations for unconditional display.
utilities for working with functions
A property that is only computed once per instance and then replaces itself with an ordinary attribute. Deleting the attribute resets the property.
Utilities for Py2/Py3 interop.
Add metaclasses in both Python 2 and Python 3.
Function from jinja2/_compat.py. License: BSD.
Use it like this:
class BaseForm(object): pass class FormType(type): pass class Form(with_metaclass(FormType, BaseForm)): pass
This requires a bit of explanation: the basic idea is to make a dummy metaclass for one level of class instantiation that replaces itself with the actual metaclass. Because of internal type checks we also need to make sure that we downgrade the custom metaclass for one level to something closer to type (that’s why __call__ and __init__ comes back from type etc.).
This has the advantage over six.with_metaclass of not introducing dummy classes into the final MRO.
Configure the logging system for Bokeh.
By default, logging is not configured, to allow users of Bokeh to have full
control over logging policy. However, it is useful to be able to enable
logging arbitrarily during when developing Bokeh. This can be accomplished
by setting the environment variable
BOKEH_PY_LOG_LEVEL. Valid values are,
in order of increasing severity:
The default logging level is
Functions useful for loading Bokeh code and data in IPython notebooks.
Create a Jupyter comms object for a specific target, that can be used to update Bokeh documents in the notebook.
Parameters: target_name (str) – the target name the Comms object should connect to
- Jupyter Comms
load_notebook(resources=None, verbose=False, hide_banner=False)¶
Prepare the IPython notebook for displaying Bokeh plots.
- resources (Resource, optional) – how and where to load BokehJS from (default: CDN)
- verbose (bool, optional) – whether to report detailed settings (default: False)
- hide_banner (bool, optional) – whether to hide the Bokeh banner (default: False)
Clearing the output cell containing the published BokehJS resources HTML code may cause Bokeh CSS styling to be removed.
Compatibility wrapper for IPython
Later versions of IPython remove the
source(first) argument. This function insulates Bokeh library code from this change.
- source (str, optional) – the source arg for IPython (default: “bokeh”)
- data (dict) – the data dict to pass to
publish_display_dataTypically has the form
Get the location of the bokehjs source files. If dev is True, the files in bokehjs/build are preferred. Otherwise uses the files in bokeh/server/static.
Get the location of the server subpackage
Functions for testing what kind of Python or Python environment is in use.
Test whether we are inside an IPython notebook.
- True if we are inside a notebook, otherwise False
Test whether we are running Python 3.
- True if we are running Python 3, otherwise False
Test whether we are running PyPy.
- True if we are inside PyPy, otherwise False
Functions for helping with serialization and deserialization of Bokeh objects.
Return a new unique ID for a Bokeh object.
Normally this function will return UUIDs to use for identifying Bokeh objects. This is especally important for Bokeh objects stored on a Bokeh server. However, it is convenient to have more human-readable IDs during development, so this behavior can be overridden by setting the environment variable
Transform arrays into lists of json safe types also handles pandas series, and replacing nans and infs with strings
iterate through the data of a ColumnSourceData object replacing non-JSON-compliant objects with compliant ones
handles nans/inf conversion
transforms pandas series into array of values
traverse_data(datum, is_numpy=True, use_numpy=True)¶
recursively dig until a flat list is found if numpy is available convert the flat list to a numpy array and send off to transform_array() to handle nan, inf, -inf otherwise iterate through items in array converting non-json items
- datum (list) – a list of values or lists
- is_numpy – True if numpy is present (see imports)
- use_numpy – toggle numpy as a dependency for testing purposes
Utilities for generating and manipulating session IDs.
A session ID would typically be associated with each browser tab viewing an application or plot. Each session has its own state separate from any other sessions hosted by the server.
check_session_id_signature(session_id, secret_key=None, signed=False)¶
Check the signature of a session ID, returning True if it’s valid.
The server uses this function to check whether a session ID was generated with the correct secret key. If signed sessions are disabled, this function always returns True.
- session_id (str) – The session ID to check
- secret_key (str, optional) – Secret key (default: value of ‘BOKEH_SECRET_KEY’ env var)
- signed (bool, optional) – Whether to check anything (default: value of ‘BOKEH_SIGN_SESSIONS’ env var)
Generate a new securely-generated secret key appropriate for SHA-256 HMAC signatures. This key could be used to sign Bokeh server session IDs for example.
Generate a random session ID.
Typically, each browser tab connected to a Bokeh application has its own session ID. In production deployments of a Bokeh app, session IDs should be random and unguessable - otherwise users of the app could interfere with one another.
If session IDs are signed with a secret key, the server can verify that the generator of the session ID was “authorized” (the generator had to know the secret key). This can be used to have a separate process, such as another web application, which generates new sessions on a Bokeh server. This other process may require users to log in before redirecting them to the Bokeh server with a valid session ID, for example.
- secret_key (str, optional) – Secret key (default: value of ‘BOKEH_SECRET_KEY’ env var)
- signed (bool, optional) – Whether to sign the session ID (default: value of ‘BOKEH_SIGN_SESSIONS’ env var)
Functions useful for string manipulations or encoding.
Decode a sequence of bytes to a UTF-8 string
Parameters: u (str) – the bytes to decode Returns: UTF-8 string
Encode a UTF-8 string to a sequence of bytes.
Parameters: u (str) – the string to encode Returns: bytes
nice_join(seq, sep=', ')¶
Join together sequences of strings into English-friendly phrases using the conjunction
- seq (seq[str]) – a sequence of strings to nicely join
- sep (str, optional) – a sequence delimiter to use (default: ”, ”)
a joined string
>>> nice_join(["a", "b", "c"]) 'a, b or c'
Convert CamelCase to snake_case.
Functions to help with testing Bokeh and reporting issues.
create_chart(klass, values, compute_values=True, **kws)¶
Create a new chart class instance with values and the extra kws keyword parameters.
- klass (class) – chart class to be created
- values (iterable) – chart data series
- compute_values (bool) – if == True underlying chart attributes (e.g., data, ranges, source, etc.) are computed by calling _setup_show, _prepare_show and _show_teardown methods.
- **kws (refer to klass arguments specification details) –
klass chart instance
Print the versions for Bokeh and the current Python and OS.
Run the Bokeh tests under the bokeh python directory using pytest.
Does not run tests from bokehjs or examples.
Parameters: args (list, optional) –
command line arguments accepted by py.test
e.g. args=[‘-s’, ‘-k charts’] prevents capture of standard out and only runs tests that match charts. For more py.test options see http://pytest.org/latest/usage.html#usage.
Returns: pytest exitcode Return type: int
unittest decorator to skip a test for Python 3
unittest decorator to skip a test for PyPy
Internal utils related to Tornado
Converts result into a Future by collapsing any futures inside result.
If result is a Future we yield until it’s done, then if the value inside the Future is another Future we yield until it’s done as well, and so on.
Provide a version for the Bokeh library.
This module uses versioneer to manage version strings. During development, versioneer will compute a version string from the current git revision. For packaged releases based off tags, the version string is hard coded in the files packaged for distribution.
the version string for this installed Bokeh library
It is also possible to override the normal version computation by creating
__conda_version__.py file at the top level of the library,
that defines a
conda_version attribute. This facility is not normally
of interest to anyone except package maintainers.