bokeh.document.document — Anaconda Enterprise 4.4 documentation

Anaconda Enterprise: Documentation

# bokeh.document.document

Note

This section documents the physical filesystem module that implements `Document`. However the intended public interface is in bokeh.document.

Provide the `Document` class, which is a container for Bokeh Models to be reflected to the client side BokehJS library.

As a concrete example, consider a column layout with `Slider` and `Select` widgets, and a plot with some tools, an axis and grid, and a glyph renderer for circles. A simplified representation oh this document might look like the figure below:

A Bokeh Document is a collection of Bokeh Models (e.g. plots, tools, glyphs, etc.) that can be serialized as a single collection.

class `bokeh.document.document.` `Document`(**kwargs)

  The basic unit of serialization for Bokeh.

  Document instances collect Bokeh models (e.g. plots, layouts, widgets, etc.) so that they may be reflected into the BokehJS client runtime. Because models may refer to other models (e.g., a plot has a list of renderers), it is not generally useful or meaningful to convert individual models to JSON. Accordingly, the `Document` is thus the smallest unit of serialization for Bokeh.

  `add_next_tick_callback`(callback)

    Add callback to be invoked once on the next tick of the event loop.

    Parameters: | callback (callable) – A callback function to execute on the next tick.
    Returns: |
    Return type: | NextTickCallback

    Note

    Next tick callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

  `add_periodic_callback`(callback, period_milliseconds)

    Add a callback to be invoked on a session periodically.

    Parameters: | callback (callable) – A callback function to execute periodically period_milliseconds (int) – Number of milliseconds between each callback execution.
    Returns: |
    Return type: | PeriodicCallback

    Note

    Periodic callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

  `add_root`(model, setter=None)

    Add a model as a root of this Document.

    Any changes to this model (including to other models referred to by it) will trigger `on_change` callbacks registered on this document.

    Parameters: | model (Model) – The model to add as a root of this document. setter (ClientSession or ServerSession or None, optional) – This is used to prevent “boomerang” updates to Bokeh apps. (default: None) In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.

  `add_timeout_callback`(callback, timeout_milliseconds)

    Add callback to be invoked once, after a specified timeout passes.

    Parameters: | callback (callable) – A callback function to execute after timeout timeout_milliseconds (int) – Number of milliseconds before callback execution.
    Returns: |
    Return type: | TimeoutCallback

    Note

    Timeout callbacks only work within the context of a Bokeh server session. This function will no effect when Bokeh outputs to standalone HTML or Jupyter notebook cells.

  `apply_json_patch`(patch, setter=None)

    Apply a JSON patch object and process any resulting events.

    Parameters: | patch (JSON-data) – The JSON-object containing the patch to apply. setter (ClientSession or ServerSession or None, optional) – This is used to prevent “boomerang” updates to Bokeh apps. (default: None) In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.
    Returns: | None

  `apply_json_patch_string`(patch)

    Apply a JSON patch provided as a string.

    Parameters: | patch (str) –
    Returns: | None

  `clear`()

    Remove all content from the document but do not reset title.

    Returns: | None

  `delete_modules`()

    Clean up sys.modules after the session is destroyed.

  classmethod `from_json`(json)

    Load a document from JSON.

    json (JSON-data) :
      A JSON-encoded document to create a new Document from.

    Returns: |
    Return type: | Document

  classmethod `from_json_string`(json)

    Load a document from JSON.

    json (str) :
      A string with a JSON-encoded document to create a new Document from.

    Returns: |
    Return type: | Document

  `get_model_by_id`(model_id)

    Find the model for the given ID in this document, or `None` if it is not found.

    Parameters: | model_id (str) – The ID of the model to search for
    Returns: | Model or None

  `get_model_by_name`(name)

    Find the model for the given name in this document, or `None` if it is not found.

    Parameters: | name (str) – The name of the model to search for
    Returns: | Model or None

  `on_change`(*callbacks)

    Provide callbacks to invovke if the document or any Model reachable from its roots changes.

  `remove_next_tick_callback`(callback)

    Remove a callback added earlier with `add_next_tick_callback`.

    Returns: | None
    Raises: | KeyError, if the callback was never added

  `remove_on_change`(*callbacks)

    Remove a callback added earlier with `on_change`.

    Raises: | KeyError, if the callback was never added

  `remove_periodic_callback`(callback)

    Remove a callback added earlier with `add_periodic_callback`

    Returns: | None
    Raises: | KeyError, if the callback was never added

  `remove_root`(model, setter=None)

    Remove a model as root model from this Document.

    Changes to this model may still trigger `on_change` callbacks on this document, if the model is still referred to by other root models.

    Parameters: | model (Model) – The model to add as a root of this document. setter (ClientSession or ServerSession or None, optional) – This is used to prevent “boomerang” updates to Bokeh apps. (default: None) In the context of a Bokeh server application, incoming updates to properties will be annotated with the session that is doing the updating. This value is propagated through any subsequent change notifications that the update triggers. The session can compare the event setter to itself, and suppress any updates that originate from itself.

  `remove_timeout_callback`(callback)

    Remove a callback added earlier with `add_timeout_callback`.

    Returns: | None
    Raises: | KeyError, if the callback was never added

  `replace_with_json`(json)

    Overwrite everything in this document with the JSON-encoded document.

    json (JSON-data) :
      A JSON-encoded document to overwrite this one.

    Returns: | None

  `select`(selector)

    Query this document for objects that match the given selector.

    Parameters: | selector (JSON-like query dictionary) – you can query by type or by name, e.g. `{"type": HoverTool}`, `{"name": "mycircle"}`
    Returns: | seq[Model]

  `select_one`(selector)

    Query this document for objects that match the given selector. Raises an error if more than one object is found. Returns single matching object, or None if nothing is found

    Parameters: | selector (JSON-like query dictionary) – you can query by type or by name, e.g. `{"type": HoverTool}`, `{"name": "mycircle"}`
    Returns: | Model or None

  `set_select`(selector, updates)

    Update objects that match a given selector with the specified attribute/value updates.

    Parameters: | selector (JSON-like query dictionary) – you can query by type or by name,i e.g. `{"type": HoverTool}`, `{"name": "mycircle"}` updates (dict) :
    Returns: | None

  `to_json`()

    Convert this document to a JSON object.

    Returns: | JSON-data

  `to_json_string`(indent=None)

    Convert the document to a JSON string.

    Parameters: | indent (int or None, optional) – number of spaces to indent, or None to suppress all newlines and indentation (default: None)
    Returns: | str

  `validate`()

    Perform integrity checks on the modes in this document.

    Returns: | None

  `roots`

    A list of all the root models in this Document.

  `session_callbacks`

    A list of all the session callbacks on this document.

  `session_context`

    The `SessionContext` for this document.

  `template`

    A Jinja2 template to use for rendering this document.

  `template_variables`

    A dictionary of template variables to pass when rendering `self.template`.

  `theme`

    The current `Theme` instance affecting models in this Document.

    Setting this to `None` sets the default theme. (i.e this property never returns `None`.)

    Changing theme may trigger model change events on the models in the document if the theme modifies any model properties.

  `title`

    A title for this document.

    This title will be set on standalone HTML documents, but not e.g. when `autoload_server` is used.