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

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

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

__set__(obj, value, *, setter=None)

实现 Python 描述符协议 的 setter。

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

注意

已将可选参数 setter 添加到标准 setter 参数中。在需要时，应通过显式调用 __set__ 提供此值。有关更多信息，请参见下文。

参数:

• obj (HasProps) – 要在其上设置新属性值的实例

• value (obj) – 要设置的属性的新值

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

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

用于 Bokeh DataSpec 属性的 PropertyDescriptor，它序列化为字段/值字典。

get_value(obj: HasProps) → Any

set_from_json(obj: HasProps, value: Any, *, setter: Setter | None = None)

从 JSON 值设置此属性的值。

此方法首先

参数:

• obj (HasProps)

• value (JSON-dict)

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

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

__init__(name: str, alias: DeprecatedAlias[T]) → None

class PropertyDescriptor(name: str, property: Property[T])

具有简单 get/set 和序列化行为的 Bokeh 属性的基类。

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

为基本的 Bokeh 属性创建 PropertyDescriptor。

参数:

• name (str) – 此属性所属的属性名称

• property (Property) – 要为其创建描述符的基本属性

__str__() → str

PropertyDescriptor 的基本字符串表示。

委托给 self.property.__str__

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

实现 Python 描述符协议 的 getter。

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

参数:

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

• owner (obj) – 要设置为属性的新值

返回值:

无

示例

>>> 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

实现 Python 描述符协议 的 setter。

注意

已将可选参数 setter 添加到标准 setter 参数中。在需要时，应通过显式调用 __set__ 提供此值。有关更多信息，请参见下文。

参数:

• obj (HasProps) – 要在其上设置新属性值的实例

• value (obj) – 要设置的属性的新值

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

__delete__(obj: HasProps) → None

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

参数:

obj (HasProps) – 要从其删除此属性的实例

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

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

参数:

• cls (class) – 要获取其默认值的类。

• no_eval (bool, optional) – 是否评估默认值的调用函数（默认值：False）

返回值:

object

instance_default(obj: HasProps) → T

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

参数:

obj (HasProps) – 要获取其默认值的实例。

返回值:

object

get_value(obj: HasProps) → Any

生成用于序列化的值。

有时，希望序列化值不同于 __get__，以便 __get__ 值对于用户或开发人员的方便而言看起来更简单。

参数:

obj (HasProps) – 要获取其序列化属性的对象

返回值:

Any

set_from_json(obj: HasProps, value: Any, *, setter: Setter | None = None)

从 JSON 值设置此属性的值。

参数:

• obj – (HasProps) : 要在其上设置属性值的实例

• value – (JSON-value) : 要设置为属性的值

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

trigger_if_changed(obj: HasProps, old: Any) → None

如果将属性设置为与 old 不相等的值，则发送更改事件通知。

参数:

• obj (HasProps) – 属性正在设置到的对象。

• old (obj) – 要比较的属性的先前值

返回值:

无

property has_ref: bool

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

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

property readonly: bool

此属性是否为只读。

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

property serialized: bool

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

例如，对于“虚拟”或“便利”属性（复制其他属性中已有的信息），这将为 False。

class UnitsSpecPropertyDescriptor(name, property, units_property)

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

__init__(name, property, units_property) → None

参数:

• name (str) – 此属性所属的属性名称

• property (Property) – 要为其创建描述符的基本属性

• units_property (Property) – 用于保存单位信息的关联属性

__set__(obj, value, *, setter=None)

实现 Python 描述符协议 的 setter。

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

注意

已将可选参数 setter 添加到标准 setter 参数中。在需要时，应通过显式调用 __set__ 提供此值。有关更多信息，请参见下文。

参数:

• obj (HasProps) – 要在其上设置新属性值的实例

• value (obj) – 要设置的属性的新值

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

set_from_json(obj, json, *, models=None, setter=None)

从 JSON 值设置此属性的值。

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

参数:

• obj – (HasProps) : 要在其上设置属性值的实例

• json – (JSON-value) : 要设置为属性的值

• models (dict or None, optional) –

  模型 ID 到模型的映射（默认值：None）

  这在需要更新的属性也具有具有引用的值的情况下是必需的。

• setter (ClientSession 或 ServerSession 或 None, 可选) –

  用于防止 Bokeh 应用程序的“回弹”更新。（默认值：None）

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

返回值:

无

exception UnsetValueError

表示描述符没有值时访问的状态。