bokeh.core.json_encoder#

Provide a functions and classes to implement a custom JSON encoder for serializing objects for BokehJS.

In general, functions in this module convert values in the following way:

  • Datetime values (Python, Pandas, NumPy) are converted to floating point milliseconds since epoch.

  • TimeDelta values are converted to absolute floating point milliseconds.

  • RelativeDelta values are converted to dictionaries.

  • Decimal values are converted to floating point.

  • Sequences (Pandas Series, NumPy arrays, python sequences) that are passed though this interface are converted to lists. Note, however, that arrays in data sources inside Bokeh Documents are converted elsewhere, and by default use a binary encoded format.

  • Bokeh Model instances are usually serialized elsewhere in the context of an entire Bokeh Document. Models passed trough this interface are converted to references.

  • HasProps (that are not Bokeh models) are converted to key/value dicts or all their properties and values.

  • Color instances are converted to CSS color values.

serialize_json(obj: Any | Serialized[Any], *, pretty: bool | None = None, indent: int | None = None) str[source]#

Convert an object or a serialized representation to a JSON string.

This function accepts Python-serializable objects and converts them to a JSON string. This function does not perform any advaced serialization, in particular it won’t serialize Bokeh models or numpy arrays. For that, use bokeh.core.serialization.Serializer class, which handles serialization of all types of objects that may be encountered in Bokeh.

Parameters:
  • obj (obj) – the object to serialize to JSON format

  • pretty (bool, optional) –

    Whether to generate prettified output. If True, spaces are added after added after separators, and indentation and newlines are applied. (default: False)

    Pretty output can also be enabled with the environment variable BOKEH_PRETTY, which overrides this argument, if set.

  • indent (int or None, optional) – Amount of indentation to use in generated JSON output. If None then no indentation is used, unless pretty output is enabled, in which case two spaces are used. (default: None)

Returns:

RFC-8259 JSON string

Return type:

str

Examples

>>> import numpy as np

>>> from bokeh.core.serialization import Serializer
>>> from bokeh.core.json_encoder import serialize_json

>>> s = Serializer()

>>> obj = dict(b=np.datetime64("2023-02-25"), a=np.arange(3))
>>> rep = s.encode(obj)
>>> rep
{
    'type': 'map',
    'entries': [
        ('b', 1677283200000.0),
        ('a', {
            'type': 'ndarray',
            'array': {'type': 'bytes', 'data': Buffer(id='p1000', data=<memory at 0x7fe5300e2d40>)},
            'shape': [3],
            'dtype': 'int32',
            'order': 'little',
        }),
    ],
}

>>> serialize_json(rep)
'{"type":"map","entries":[["b",1677283200000.0],["a",{"type":"ndarray","array":'
"{"type":"bytes","data":"AAAAAAEAAAACAAAA"},"shape":[3],"dtype":"int32","order":"little"}]]}'

Note

Using this function isn’t strictly necessary. The serializer can be configured to produce output that’s fully compatible with dumps() from the standard library module json. The main difference between this function and dumps() is handling of memory buffers. Use the following setup:

>>> s = Serializer(deferred=False)

>>> import json
>>> json.dumps(s.encode(obj))