#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2024, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
'''
'''
#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations
import logging # isort:skip
log = logging.getLogger(__name__)
#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------
# Standard library imports
import re
from contextlib import contextmanager
from typing import (
TYPE_CHECKING,
Any,
Iterator,
Sequence,
)
from weakref import WeakKeyDictionary
# Bokeh imports
from ..core.types import ID
from ..document.document import Document
from ..model import Model, collect_models
from ..settings import settings
from ..themes.theme import Theme
from ..util.dataclasses import dataclass, field
from ..util.serialization import (
make_globally_unique_css_safe_id,
make_globally_unique_id,
)
if TYPE_CHECKING:
from ..document.document import DocJson
#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------
__all__ = (
'contains_tex_string',
'FromCurdoc',
'is_tex_string',
'OutputDocumentFor',
'RenderItem',
'RenderRoot',
'RenderRoots',
'standalone_docs_json',
'standalone_docs_json_and_render_items',
'submodel_has_python_callbacks',
)
#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# Dev API
#-----------------------------------------------------------------------------
class FromCurdoc:
''' This class merely provides a non-None default value for ``theme``
arguments, since ``None`` itself is a meaningful value for users to pass.
'''
pass
@contextmanager
def OutputDocumentFor(objs: Sequence[Model], apply_theme: Theme | type[FromCurdoc] | None = None,
always_new: bool = False) -> Iterator[Document]:
''' Find or create a (possibly temporary) Document to use for serializing
Bokeh content.
Typical usage is similar to:
.. code-block:: python
with OutputDocumentFor(models):
(docs_json, [render_item]) = standalone_docs_json_and_render_items(models)
Inside the context manager, the models will be considered to be part of a single
Document, with any theme specified, which can thus be serialized as a unit. Where
possible, OutputDocumentFor attempts to use an existing Document. However, this is
not possible in three cases:
* If passed a series of models that have no Document at all, a new Document will
be created, and all the models will be added as roots. After the context manager
exits, the new Document will continue to be the models' document.
* If passed a subset of Document.roots, then OutputDocumentFor temporarily "re-homes"
the models in a new bare Document that is only available inside the context manager.
* If passed a list of models that have different documents, then OutputDocumentFor
temporarily "re-homes" the models in a new bare Document that is only available
inside the context manager.
OutputDocumentFor will also perfom document validation before yielding, if
``settings.perform_document_validation()`` is True.
objs (seq[Model]) :
a sequence of Models that will be serialized, and need a common document
apply_theme (Theme or FromCurdoc or None, optional):
Sets the theme for the doc while inside this context manager. (default: None)
If None, use whatever theme is on the document that is found or created
If FromCurdoc, use curdoc().theme, restoring any previous theme afterwards
If a Theme instance, use that theme, restoring any previous theme afterwards
always_new (bool, optional) :
Always return a new document, even in cases where it is otherwise possible
to use an existing document on models.
Yields:
Document
'''
# Note: Comms handling relies on the fact that the new_doc returned
# has models with the same IDs as they were started with
if not isinstance(objs, Sequence) or len(objs) == 0 or not all(isinstance(x, Model) for x in objs):
raise ValueError("OutputDocumentFor expects a non-empty sequence of Models")
def finish() -> None:
pass
docs = {obj.document for obj in objs if obj.document is not None}
if always_new:
def finish() -> None: # noqa
_dispose_temp_doc(objs)
doc = _create_temp_doc(objs)
else:
if len(docs) == 0:
doc = _new_doc()
for model in objs:
doc.add_root(model)
# handle a single shared document
elif len(docs) == 1:
doc = docs.pop()
# we are not using all the roots, make a quick clone for outputting purposes
if set(objs) != set(doc.roots):
def finish() -> None:
_dispose_temp_doc(objs)
doc = _create_temp_doc(objs)
# we are using all the roots of a single doc, just use doc as-is
pass # lgtm [py/unnecessary-pass]
# models have mixed docs, just make a quick clone
else:
def finish():
_dispose_temp_doc(objs)
doc = _create_temp_doc(objs)
if settings.perform_document_validation():
doc.validate()
_set_temp_theme(doc, apply_theme)
yield doc
_unset_temp_theme(doc)
finish()
class RenderItem:
def __init__(self, docid: ID | None = None, token: str | None = None, elementid: ID | None = None,
roots: list[Model] | dict[Model, ID] | None = None, use_for_title: bool | None = None):
if (docid is None and token is None) or (docid is not None and token is not None):
raise ValueError("either docid or sessionid must be provided")
if roots is None:
roots = dict()
elif isinstance(roots, list):
roots = {root: make_globally_unique_id() for root in roots}
self.docid = docid
self.token = token
self.elementid = elementid
self.roots = RenderRoots(roots)
self.use_for_title = use_for_title
def to_json(self) -> dict[str, Any]:
json: dict[str, Any] = {}
if self.docid is not None:
json["docid"] = self.docid
else:
json["token"] = self.token
if self.elementid is not None:
json["elementid"] = self.elementid
if self.roots:
json["roots"] = self.roots.to_json()
json["root_ids"] = [root.id for root in self.roots]
if self.use_for_title is not None:
json["use_for_title"] = self.use_for_title
return json
def __eq__(self, other: Any) -> bool:
if not isinstance(other, self.__class__):
return False
else:
return self.to_json() == other.to_json()
[docs]
@dataclass
class RenderRoot:
""" Encapsulate data needed for embedding a Bokeh document root.
Values for ``name`` or ``tags`` are optional. They may be useful for
querying a collection of roots to find a specific one to embed.
"""
#: A unique ID to use for the DOM element
elementid: ID
#: The Bokeh model ID for this root
id: ID = field(compare=False)
#: An optional user-supplied name for this root
name: str | None = field(default="", compare=False)
#: A list of any user-supplied tag values for this root
tags: list[Any] = field(default_factory=list, compare=False)
def __post_init__(self):
# Model.name is nullable, and field() won't enforce the default when name=None
self.name = self.name or ""
class RenderRoots:
def __init__(self, roots: dict[Model, ID]) -> None:
self._roots = roots
def __iter__(self) -> Iterator[RenderRoot]:
for i in range(0, len(self)):
yield self[i]
def __len__(self):
return len(self._roots.items())
def __getitem__(self, key: int | str) -> RenderRoot:
if isinstance(key, int):
(root, elementid) = list(self._roots.items())[key]
else:
for root, elementid in self._roots.items():
if root.name == key:
break
else:
raise ValueError(f"root with {key!r} name not found")
return RenderRoot(elementid, root.id, root.name, root.tags)
def __getattr__(self, key: str) -> RenderRoot:
return self.__getitem__(key)
def to_json(self) -> dict[ID, ID]:
return {root.id: elementid for root, elementid in self._roots.items()}
def __repr__(self) -> str:
return repr(self._roots)
def standalone_docs_json(models: Sequence[Model | Document]) -> dict[ID, DocJson]:
'''
'''
docs_json, _ = standalone_docs_json_and_render_items(models)
return docs_json
def standalone_docs_json_and_render_items(models: Model | Document | Sequence[Model | Document], *,
suppress_callback_warning: bool = False) -> tuple[dict[ID, DocJson], list[RenderItem]]:
'''
'''
if isinstance(models, (Model, Document)):
models = [models]
if not (isinstance(models, Sequence) and all(isinstance(x, (Model, Document)) for x in models)):
raise ValueError("Expected a Model, Document, or Sequence of Models or Documents")
if submodel_has_python_callbacks(models) and not suppress_callback_warning:
log.warning(_CALLBACKS_WARNING)
docs: dict[Document, tuple[ID, dict[Model, ID]]] = {}
for model_or_doc in models:
if isinstance(model_or_doc, Document):
model = None
doc = model_or_doc
else:
model = model_or_doc
doc = model.document
if doc is None:
raise ValueError("A Bokeh Model must be part of a Document to render as standalone content")
if doc not in docs:
docs[doc] = (make_globally_unique_id(), dict())
(docid, roots) = docs[doc]
if model is not None:
roots[model] = make_globally_unique_css_safe_id()
else:
for model in doc.roots:
roots[model] = make_globally_unique_css_safe_id()
docs_json: dict[ID, DocJson] = {}
for doc, (docid, _) in docs.items():
docs_json[docid] = doc.to_json(deferred=False)
render_items: list[RenderItem] = []
for _, (docid, roots) in docs.items():
render_items.append(RenderItem(docid, roots=roots))
return (docs_json, render_items)
def submodel_has_python_callbacks(models: Sequence[Model | Document]) -> bool:
''' Traverses submodels to check for Python (event) callbacks
'''
has_python_callback = False
for model in collect_models(models):
if len(model._callbacks) > 0 or len(model._event_callbacks) > 0:
has_python_callback = True
break
return has_python_callback
def is_tex_string(text: str) -> bool:
''' Whether a string begins and ends with MathJax default delimiters
Args:
text (str): String to check
Returns:
bool: True if string begins and ends with delimiters, False if not
'''
dollars = r"^\$\$.*?\$\$$"
braces = r"^\\\[.*?\\\]$"
parens = r"^\\\(.*?\\\)$"
pat = re.compile(f"{dollars}|{braces}|{parens}", flags=re.S)
return pat.match(text) is not None
def contains_tex_string(text: str) -> bool:
''' Whether a string contains any pair of MathJax default delimiters
Args:
text (str): String to check
Returns:
bool: True if string contains delimiters, False if not
'''
# these are non-greedy
dollars = r"\$\$.*?\$\$"
braces = r"\\\[.*?\\\]"
parens = r"\\\(.*?\\\)"
pat = re.compile(f"{dollars}|{braces}|{parens}", flags=re.S)
return pat.search(text) is not None
#-----------------------------------------------------------------------------
# Private API
#-----------------------------------------------------------------------------
_CALLBACKS_WARNING = """
You are generating standalone HTML/JS output, but trying to use real Python
callbacks (i.e. with on_change or on_event). This combination cannot work.
Only JavaScript callbacks may be used with standalone output. For more
information on JavaScript callbacks with Bokeh, see:
https://docs.bokeh.org/en/latest/docs/user_guide/interaction/callbacks.html
Alternatively, to use real Python callbacks, a Bokeh server application may
be used. For more information on building and running Bokeh applications, see:
https://docs.bokeh.org/en/latest/docs/user_guide/server.html
"""
def _new_doc() -> Document:
# TODO: embed APIs need to actually respect the existing document's
# configuration, but for now this is better than nothing.
from ..io import curdoc
doc = Document()
callbacks = curdoc().callbacks._js_event_callbacks
doc.callbacks._js_event_callbacks.update(callbacks)
return doc
def _create_temp_doc(models: Sequence[Model]) -> Document:
doc = _new_doc()
for m in models:
doc.models[m.id] = m
m._temp_document = doc
for ref in m.references():
doc.models[ref.id] = ref
ref._temp_document = doc
doc._roots = list(models)
return doc
def _dispose_temp_doc(models: Sequence[Model]) -> None:
for m in models:
m._temp_document = None
for ref in m.references():
ref._temp_document = None
_themes: WeakKeyDictionary[Document, Theme] = WeakKeyDictionary()
def _set_temp_theme(doc: Document, apply_theme: Theme | type[FromCurdoc] | None) -> None:
_themes[doc] = doc.theme
if apply_theme is FromCurdoc:
from ..io import curdoc
doc.theme = curdoc().theme
elif isinstance(apply_theme, Theme):
doc.theme = apply_theme
def _unset_temp_theme(doc: Document) -> None:
if doc not in _themes:
return
doc.theme = _themes[doc]
del _themes[doc]
#-----------------------------------------------------------------------------
# Code
#-----------------------------------------------------------------------------
