Source code for bokeh.model.util

#-----------------------------------------------------------------------------
# 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.
#-----------------------------------------------------------------------------
''' Provide a base class for all objects (called Bokeh Models) that can go in
a Bokeh |Document|.

'''
#-----------------------------------------------------------------------------
# Boilerplate
#-----------------------------------------------------------------------------
from __future__ import annotations

import logging # isort:skip
log = logging.getLogger(__name__)

#-----------------------------------------------------------------------------
# Imports
#-----------------------------------------------------------------------------

# Standard library imports
from typing import TYPE_CHECKING, Any, Callable

# Bokeh imports
from ..core.has_props import HasProps, Qualified
from ..util.dataclasses import entries, is_dataclass

if TYPE_CHECKING:
    from ..core.types import ID
    from ..document import Document
    from .model import Model

#-----------------------------------------------------------------------------
# Globals and constants
#-----------------------------------------------------------------------------

__all__ = (
    'HasDocumentRef',
    'Qualified', # XXX: for backwards compatibility
    'collect_filtered_models',
    'collect_models',
    'get_class',
    'visit_immediate_value_references',
    'visit_value_and_its_immediate_references',
)

#-----------------------------------------------------------------------------
# General API
#-----------------------------------------------------------------------------

#-----------------------------------------------------------------------------
# Dev API
#-----------------------------------------------------------------------------

class HasDocumentRef:

    _document: Document | None
    _temp_document: Document | None

    def __init__(self, *args, **kw):
        super().__init__(*args, **kw)
        self._document = None
        self._temp_document = None

    @property
    def document(self) -> Document | None:
        ''' The |Document| this model is attached to (can be ``None``)

        '''
        if self._temp_document is not None:
            return self._temp_document
        return self._document

    @document.setter
    def document(self, doc: Document) -> None:
        self._document = doc

def collect_filtered_models(discard: Callable[[Model], bool] | None, *input_values: Any) -> list[Model]:
    ''' Collect a duplicate-free list of all other Bokeh models referred to by
    this model, or by any of its references, etc, unless filtered-out by the
    provided callable.

    Iterate over ``input_values`` and descend through their structure
    collecting all nested ``Models`` on the go.

    Args:
        *discard (Callable[[Model], bool])
            a callable which accepts a *Model* instance as its single argument
            and returns a boolean stating whether to discard the instance. The
            latter means that the instance will not be added to collected
            models nor will its references be explored.

        *input_values (Model)
            Bokeh models to collect other models from

    Returns:
        list(Model)

    '''

    ids: set[ID] = set()
    collected: list[Model] = []
    queued: list[Model] = []

    def queue_one(obj: Model) -> None:
        if obj.id not in ids and not (callable(discard) and discard(obj)):
            queued.append(obj)

    for value in input_values:
        visit_value_and_its_immediate_references(value, queue_one)

    while queued:
        obj = queued.pop(0)
        if obj.id not in ids:
            ids.add(obj.id)
            collected.append(obj)
            visit_immediate_value_references(obj, queue_one)

    return collected

[docs] def collect_models(*input_values: Any) -> list[Model]: ''' Collect a duplicate-free list of all other Bokeh models referred to by this model, or by any of its references, etc. Iterate over ``input_values`` and descend through their structure collecting all nested ``Models`` on the go. The resulting list is duplicate-free based on objects' identifiers. Args: *input_values (Model) Bokeh models to collect other models from Returns: list[Model] : all models reachable from this one. ''' return collect_filtered_models(None, *input_values)
[docs] def get_class(view_model_name: str) -> type[Model]: ''' Look up a Bokeh model class, given its view model name. Args: view_model_name (str) : A view model name for a Bokeh model to look up Returns: Model: the model class corresponding to ``view_model_name`` Raises: KeyError, if the model cannot be found Example: .. code-block:: python >>> from bokeh.model import get_class >>> get_class("Range1d") <class 'bokeh.models.ranges.Range1d'> ''' # In order to look up from the model catalog that Model maintains, it # has to be created first. These imports ensure that all built-in Bokeh # models are represented in the catalog. from .. import models # noqa: F401 from .. import plotting # noqa: F401 from .model import Model known_models = Model.model_class_reverse_map if view_model_name in known_models: return known_models[view_model_name] else: raise KeyError(f"View model name '{view_model_name}' not found")
def visit_immediate_value_references(value: Any, visitor: Callable[[Model], None]) -> None: ''' Visit all references to another Model without recursing into any of the child Model; may visit the same Model more than once if it's referenced more than once. Does not visit the passed-in value. ''' if isinstance(value, HasProps): for attr in value.properties_with_refs(): child = getattr(value, attr) visit_value_and_its_immediate_references(child, visitor) else: visit_value_and_its_immediate_references(value, visitor) def visit_value_and_its_immediate_references(obj: Any, visitor: Callable[[Model], None]) -> None: ''' Visit Models, HasProps, and Python containers. Recurses down HasProps references and Python containers (does not recurse down Model subclasses). The ordering in this function is to optimize performance. We check the most comomn types (int, float, str) first so that we can quickly return in the common case. We avoid isinstance and issubclass checks in a couple places with `type` checks because isinstance checks can be slow. ''' from .model import Model typ = type(obj) if typ in {int, float, str}: # short circuit on common scalar types return if typ is list or issubclass(typ, (list, tuple)): # check common containers for item in obj: visit_value_and_its_immediate_references(item, visitor) elif issubclass(typ, dict): for key, value in obj.items(): visit_value_and_its_immediate_references(key, visitor) visit_value_and_its_immediate_references(value, visitor) elif issubclass(typ, HasProps): if issubclass(typ, Model): visitor(obj) else: # this isn't a Model, so recurse into it visit_immediate_value_references(obj, visitor) elif is_dataclass(obj): for _, value in entries(obj): visit_value_and_its_immediate_references(value, visitor) #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Code #-----------------------------------------------------------------------------