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 属性。然后，当用户访问这些属性时，描述符会将所有 get 和 set 操作委托给 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 字形及其作为 NumberSpec 的 x 属性的示例：

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])[源代码]#

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

__set__(obj, value, *, setter=None)[源代码]#

实现 Python 描述符协议的 setter。

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

注意

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

参数:

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

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

返回:

None

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

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

get_value(obj: HasProps) → Any[源代码]#

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

从 JSON 值设置此属性的值。

此方法首先

参数:

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

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

返回:

None

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) – 要将属性设置为的新值

返回:

None

示例

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

返回:

None

__delete__(obj: HasProps) → None[源代码]#

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

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

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

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

参数:

cls (class) – 要获取默认值的类。
no_eval (bool, 可选) – 是否评估默认值的可调用对象（默认值：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 值) : 要设置为属性的值
setter (ClientSession 或 ServerSession 或 None, 可选) –
这用于防止对 Bokeh 应用程序的“回旋镖”更新。（默认值：None）

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

返回:

None

trigger_if_changed(obj: HasProps, old: Any) → None[源代码]#

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

参数:

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

返回:

None

property has_ref: bool#

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

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

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

参数:

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

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

实现 Python 描述符协议的 setter。

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

注意

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

参数:

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

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

返回:

None

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

从 JSON 值设置此属性的值。

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

参数:

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

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

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

返回:

None

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