Source code for bokeh.core.property.instance

#-----------------------------------------------------------------------------
# Copyright (c) 2012 - 2023, Anaconda, Inc., and Bokeh Contributors.
# All rights reserved.
#
# The full license is in the file LICENSE.txt, distributed with this software.
#-----------------------------------------------------------------------------
""" Provide the Instance property.

The Instance property is used to construct object graphs of Bokeh models,
where one Bokeh model refers to another.

"""

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

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

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

# Standard library imports
import types
from importlib import import_module
from typing import (
    Any,
    Callable,
    Generic,
    TypeVar,
)

# Bokeh imports
from ..has_props import HasProps
from ..serialization import Serializable
from ._sphinx import model_link, property_link, register_type_link
from .bases import Init, Property
from .singletons import Undefined

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

__all__ = (
    'Instance',
    'InstanceDefault',
    'Object',
)

T = TypeVar("T", bound=object)
S = TypeVar("S", bound=Serializable)

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

[docs]class Object(Property[T]): """ Accept values that are instances of any class. .. note:: This is primarily useful for validation purpose. Non-serializable objects will fail regardless during the serialization process. """ _instance_type: type[T] | Callable[[], type[T]] | str def __init__(self, instance_type: type[T] | Callable[[], type[T]] | str, default: Init[T] = Undefined, help: str | None = None): if not (isinstance(instance_type, (type, str)) or callable(instance_type)): raise ValueError(f"expected a type, fn() -> type, or string, got {instance_type}") if isinstance(instance_type, type): self._assert_type(instance_type) self._instance_type = instance_type super().__init__(default=default, help=help) @staticmethod def _assert_type(instance_type: type[Any]) -> None: pass def __str__(self) -> str: class_name = self.__class__.__name__ instance_type = self.instance_type.__name__ return f"{class_name}({instance_type})" @property def has_ref(self) -> bool: return True @property def instance_type(self) -> type[T]: instance_type: type[Serializable] if isinstance(self._instance_type, type): instance_type = self._instance_type elif isinstance(self._instance_type, str): module, name = self._instance_type.rsplit(".", 1) instance_type = getattr(import_module(module, "bokeh"), name) self._assert_type(instance_type) self._instance_type = instance_type else: instance_type = self._instance_type() self._assert_type(instance_type) self._instance_type = instance_type return instance_type def validate(self, value: Any, detail: bool = True) -> None: super().validate(value, detail) if isinstance(value, self.instance_type): return instance_type = self.instance_type.__name__ value_type = type(value).__name__ msg = "" if not detail else f"expected an instance of type {instance_type}, got {value} of type {value_type}" raise ValueError(msg) def _may_have_unstable_default(self): # because the instance value is mutable return self._default is not Undefined
[docs]class Instance(Object[S]): """ Accept values that are instances of serializable types (e.g. |HasProps|). """ @staticmethod def _assert_type(instance_type: type[Any]) -> None: if not (isinstance(instance_type, type) and issubclass(instance_type, Serializable)): raise ValueError(f"expected a subclass of Serializable (e.g. HasProps), got {instance_type}")
I = TypeVar("I", bound=HasProps)
[docs]class InstanceDefault(Generic[I]): """ Provide a deferred initializer for Instance defaults. This is useful for Bokeh models with Instance properties that should have unique default values for every model instance. Using an InstanceDefault will afford better user-facing documentation than a lambda initializer. """ def __init__(self, model: type[I], **kwargs: Any) -> None: self._model = model self._kwargs = kwargs def __call__(self) -> I: return self._model(**self._kwargs) def __repr__(self) -> str: kwargs = ", ".join(f"{key}={val}" for key, val in self._kwargs.items()) return f"<Instance: {self._model.__qualified_model__}({kwargs})>"
#----------------------------------------------------------------------------- # Dev API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Private API #----------------------------------------------------------------------------- #----------------------------------------------------------------------------- # Code #----------------------------------------------------------------------------- @register_type_link(Instance) def _sphinx_type_link(obj: Instance[Any]) -> str: # Sphinx links may be generated during docstring processing which means # we can't necessarily evaluate pure function (e.g. lambda) Instance # initializers, since they may contain circular references to the (not # yet fully defined at this point) Model if isinstance(obj._instance_type, types.FunctionType): return f"{property_link(obj)}" if isinstance(obj._instance_type, str): return f"{property_link(obj)}({obj._instance_type!r})" model = obj.instance_type model_name = f"{model.__module__}.{model.__name__}" return f"{property_link(obj)}({model_link(model_name)})"