bokeh.core.property.descriptors#

为委托给Bokeh属性提供Python描述符。

Python 的描述符协议允许对实例上的所有属性访问进行细粒度控制（“你控制点”）。Bokeh 使用描述符协议来提供易于使用、声明式、基于类型的

可以自动验证和序列化其值的类属性，以及帮助提供复杂的文档。

Bokeh 属性实际上由两部分组成：一个熟悉的“属性”部分，例如 Int, String 等，以及一个关联的 Python 描述符，该描述符将属性访问委托给属性实例。

例如，一个非常简化的类似范围对象的定义可能是：

from bokeh.model import Model
from bokeh.core.properties import Float

class Range(Model):
    start = Float(help="start point")
    end   = Float(help="end point")

当这个类被创建时，MetaHasProps 元类将 start 和 end 属性连接到 Float 属性。然后，当用户访问这些属性时，描述符将所有获取和设置操作委托给 Float 属性。

rng = Range()

# The descriptor __set__ method delegates to Float, which can validate
# the value 10.3 as a valid floating point value
rng.start = 10.3

# But can raise a validation exception if an attempt to set to a list
# is made
rng.end = [1,2,3]   # ValueError !

更复杂的属性，如DataSpec及其子类，可以控制值的序列化方式。考虑这个使用Circle图形及其x属性的例子，该属性是一个NumberSpec：

from bokeh.models import Circle

c = Circle()

c.x = 10      # serializes to {'value': 10}

c.x = 'foo'   # serializes to {'field': 'foo'}

在Bokeh中还有许多其他类似的例子。通过这种方式，用户可以简单自然地操作，而无需担心验证、序列化和文档等低级细节。

该模块提供了类 PropertyDescriptor 和各种子类，可用于将 Bokeh 属性附加到 Bokeh 模型。

注意

这些类构成了实现Bokeh模型和属性系统的非常底层的机制的一部分。这些类或其方法不太可能适用于任何标准用途，也不适用于那些不直接在Bokeh自身基础设施上进行开发的人员。

class AliasPropertyDescriptor(name: str, alias: Alias[T])[源代码]#

__init__(name: str, alias: Alias[T]) → None[source]#

class ColumnDataPropertyDescriptor(name: str, property: Property[T])[source]#

一个专门用于处理ColumnData属性的PropertyDescriptor。

__set__(obj, value, *, setter=None)[source]#

实现Python 描述符协议的设置器。

此方法首先单独提取并移除JSON中的任何units字段，并直接设置相关的单位属性。然后将剩余的值传递给超类__set__进行处理。

注意

一个可选参数 setter 已被添加到标准的 setter 参数中。当需要时，应通过显式调用 __set__ 来提供此值。更多信息请参见下文。

Parameters:

obj (HasProps) – 要在其上设置新属性值的实例
value (obj) – 设置属性的新值
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

class DataSpecPropertyDescriptor(name: str, property: Property[T])[source]#

一个用于Bokeh DataSpec属性的PropertyDescriptor，这些属性序列化为字段/值字典。

get_value(obj: HasProps) → Any[source]#

set_from_json(obj: HasProps, value: Any, *, setter: Setter | None = None)[source]#

从JSON值设置此属性的值。

此方法首先

Parameters:

obj (HasProps)
值 (JSON字典)
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

class DeprecatedAliasPropertyDescriptor(name: str, alias: DeprecatedAlias[T])[source]#

__init__(name: str, alias: DeprecatedAlias[T]) → None[源代码]#

class PropertyDescriptor(name: str, property: Property[T])[源代码]#

一个用于Bokeh属性的基类，具有简单的获取/设置和序列化行为。

__init__(name: str, property: Property[T]) → None[source]#

为基本的Bokeh属性创建一个PropertyDescriptor。

Parameters:

name (str) – 此属性对应的属性名称
property (Property) – 用于创建描述符的基本属性

__str__() → str[source]#

PropertyDescriptor 的基本字符串表示。

委托给 self.property.__str__

__get__(obj: HasProps | None, owner: type[HasProps] | None) → T[source]#

实现Python 描述符协议的getter。

例如，对于实例属性访问，我们委托给Property。对于类属性访问，我们返回自身。

Parameters:

obj (HasProps 或 None) – 要在其上设置新属性值的实例（用于实例属性访问），或 None（用于类属性访问）
owner (obj) – 设置属性的新值

Returns:

无

示例

>>> from bokeh.models import Range1d

>>> r = Range1d(start=10, end=20)

# instance attribute access, returns the property value
>>> r.start
10

# class attribute access, returns the property descriptor
>>> Range1d.start
<bokeh.core.property.descriptors.PropertyDescriptor at 0x1148b3390>

__set__(obj: HasProps, value: T, *, setter: Setter | None = None) → None[source]#

实现Python 描述符协议的设置器。

注意

一个可选参数 setter 已被添加到标准的 setter 参数中。当需要时，应通过显式调用 __set__ 来提供此值。更多信息请参见下文。

Parameters:

obj (HasProps) – 要在其上设置新属性值的实例
value (obj) – 设置属性的新值
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

__delete__(obj: HasProps) → None[source]#

实现Python 描述符协议的删除器。

Parameters:: obj (HasProps) – 要从中删除此属性的实例

class_default(cls: type[HasProps], *, no_eval: bool = False)[source]#

获取HasProps特定子类型的默认值，该值可能不用于单个实例。

Parameters:

cls (class) – 获取默认值的类。
no_eval (bool, optional) – 是否评估默认值的可调用对象（默认值：False）

Returns:

对象

instance_default(obj: HasProps) → T[source]#

获取将用于特定实例的默认值。

Parameters:: obj (HasProps) – 获取默认值的实例。
Returns:: 对象

get_value(obj: HasProps) → Any[source]#

生成用于序列化的值。

有时，为了用户或开发者的方便，序列化的值可能与__get__不同，以便__get__值看起来更简单。

Parameters:: obj (HasProps) – 获取序列化属性的对象
Returns:: 任何

set_from_json(obj: HasProps, value: Any, *, setter: Setter | None = None)[source]#

从JSON值设置此属性的值。

Parameters:

obj – (HasProps) : 设置属性值的实例
value – (JSON-value) : 要设置给属性的值
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

trigger_if_changed(obj: HasProps, old: Any) → None[source]#

如果属性设置为一个不等于old的值，则发送一个更改事件通知。

Parameters:

obj (HasProps) – 正在设置属性的对象。
旧值 (obj) – 要比较的属性的先前值

Returns:

无

property has_ref: bool#

该属性是否可以引用另一个 HasProps 实例。

对于基本属性，委托给Property上的has_ref属性。

property readonly: bool#

此属性是否为只读。

只读属性只能由客户端（即在浏览器中的BokehJS）修改。

property serialized: bool#

在序列化对象时，是否应序列化该属性。

例如，对于一个“虚拟”或“方便”的属性，如果它复制了其他属性中已经可用的信息，那么这将为False。

class UnitsSpecPropertyDescriptor(name, property, units_property)[source]#

一个用于Bokeh UnitsSpec属性的PropertyDescriptor，它会自动作为副作用贡献相关的_units属性。

__init__(name, property, units_property) → None[source]#

Parameters:

name (str) – 此属性对应的属性名称
property (Property) – 用于创建描述符的基本属性
units_property (Property) – 一个用于保存单位信息的关联属性

__set__(obj, value, *, setter=None)[source]#

实现Python 描述符协议的设置器。

此方法首先单独提取并移除JSON中的任何units字段，并直接设置相关的单位属性。然后将剩余的值传递给超类__set__进行处理。

注意

一个可选参数 setter 已被添加到标准的 setter 参数中。当需要时，应通过显式调用 __set__ 来提供此值。更多信息请参见下文。

Parameters:

obj (HasProps) – 要在其上设置新属性值的实例
value (obj) – 设置属性的新值
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

set_from_json(obj, json, *, models=None, setter=None)[source]#

从JSON值设置此属性的值。

此方法首先单独提取并移除JSON中的任何units字段，并直接设置相关的单位属性。然后将剩余的JSON传递给父类set_from_json进行处理。

Parameters:

obj – (HasProps) : 设置属性值的实例
json – (JSON值) : 要设置给属性的值
models (dict 或 None, 可选) –
模型ID到模型的映射（默认：None）

在需要更新的属性也具有引用值的情况下，这是必需的。
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对Bokeh应用程序的“回旋镖”更新。 (默认值: None)

在Bokeh服务器应用程序的上下文中，对属性的传入更新将使用正在执行更新的会话进行注释。此值通过更新触发的任何后续更改通知传播。会话可以将事件设置器与自身进行比较，并抑制源自自身的任何更新。

Returns:

无

exception UnsetValueError[source]#: 表示访问了没有值的描述符的状态。