bokeh.util#

提供一个通用实用工具集合，用于实现 Bokeh 功能。

`bokeh.util.browser`#

用于帮助浏览器操作的实用函数。

class DummyWebBrowser[source]#

一个 “no-op” 网络浏览器控制器。

open(url: str, new: Literal[0, 1, 2] = 0, autoraise: bool = True) → bool[source]#: 接收标准参数，但不执行任何操作。

get_browser_controller(browser: str | None = None) → BrowserLike[source]#

返回浏览器控制器。

参数:

browser (str or None) –

浏览器名称，或 None (默认值：None) 如果传递字符串 'none'，则返回虚拟 Web 浏览器控制器。

否则，使用该值通过 webbrowser 标准库模块选择合适的控制器。如果该值为 None，则使用系统默认值。

返回:

一个 Web 浏览器控制器

返回类型:

控制器

view(location: str, browser: str | None = None, new: Literal['same', 'window', 'tab'] = 'same', autoraise: bool = True) → None[source]#

打开浏览器以查看指定位置。

参数:

location (str) – 要打开的位置。如果位置不是以 “http:” 开头，则假定为本地文件系统上的文件路径。
browser (str or None) – 要使用的浏览器（默认值：None）。如果为 None，则使用系统默认浏览器。
new (str) –
如何打开位置。有效值包括：

'same' - 在当前选项卡中打开

'tab' - 在当前窗口中打开新选项卡

'window' - 在新窗口中打开
autoraise (bool) – 是否在新浏览器窗口中自动提升位置（默认值：True）

返回:

None

`bokeh.util.callback_manager`#

为类添加 on_change 和 on_event 回调接口，提供 PropertyCallbackManager 和 EventCallbackManager mixin 类。

class EventCallbackManager(*args: Any, **kw: Any)[source]#

一个 mixin 类，用于提供在 Python 端注册和触发事件回调的接口。

on_event(event: str | type[Event], *callbacks: Callable[[Event], None] | Callable[[], None]) → None[source]#

当指定事件在此模型上发生时，运行回调。

并非所有模型都支持所有事件。有关哪些模型能够触发特定事件的更多信息，请参阅 bokeh.events 中的特定事件。

class PropertyCallbackManager(*args: Any, **kw: Any)[source]#

一个 mixin 类，用于提供注册和触发回调的接口。

on_change(attr: str, *callbacks: Callable[[str, Any, Any], None]) → None[source]#

在此对象上添加一个回调，以便在 attr 更改时触发。

参数:

attr (str) – 此对象上的属性名称
callback (callable) – 要注册的回调函数

返回:

None

remove_on_change(attr: str, *callbacks: Callable[[str, Any, Any], None]) → None[source]#: 从此对象中删除回调

trigger(attr: str, old: Any, new: Any, hint: DocumentPatchedEvent | None = None, setter: Setter | None = None) → None[source]#: 在此对象上触发 attr 的回调。

`bokeh.util.compiler`#

提供函数和类以帮助进行各种 JS 和 CSS 编译。

exception CompilationError(error: dict[str, str] | str)[source]#: 用于报告 JS 编译错误的 RuntimeError 子类。

class AttrDict[source]#: 提供一个支持通过命名属性访问的 dict 子类。

class CustomModel(cls: type[HasProps])[source]#: 表示自定义（用户定义）Bokeh 模型。

class FromFile(path: str)[source]#

从单独的源文件读取的自定义模型实现。

参数:: path (str) – 包含扩展源代码的文件的路径

class Implementation[source]#: 用于表示 Bokeh 自定义模型实现的基础类。

class Inline(code: str, file: str | None = None)[source]#

用于表示 Bokeh 自定义模型实现的基础类，这些实现可以以某种语言的内联代码形式给出。

参数:

code (str) – 实现的源代码
file (str, optional) – 包含源代码文本的文件的文件路径（默认值：None）

class JavaScript(code: str, file: str | None = None)[source]#

JavaScript 中 Bokeh 自定义模型的实现

示例

class MyExt(Model):
    __implementation__ = JavaScript(""" <JavaScript code> """)

class Less(code: str, file: str | None = None)[source]#: Less CSS 样式表的实现。

class TypeScript(code: str, file: str | None = None)[source]#

TypeScript 中 Bokeh 自定义模型的实现

示例

class MyExt(Model):
    __implementation__ = TypeScript(""" <TypeScript code> """)

bundle_all_models() → str | None[source]#: 创建所有模型的捆绑包。

bundle_models(models: Sequence[type[HasProps]] | None) → str | None[source]#: 创建选定 models 的捆绑包。

calc_cache_key(custom_models: dict[str, CustomModel]) → str[source]#

生成用于缓存自定义扩展实现的键。

除了 Model 类之外没有其他元数据，因此这是生成缓存键的唯一基础。

我们从 model.full_name 列表构建模型键。这并非理想方案，但稍后可能会找到更好的解决方案。

get_cache_hook() → Callable[[CustomModel, Implementation], AttrDict | None][source]#: 返回当前用于查找给定 CustomModel 和 Implementation 的已编译代码的缓存钩子。

set_cache_hook(hook: Callable[[CustomModel, Implementation], AttrDict | None]) → None[source]#: 设置用于查找给定 CustomModel 和 Implementation 的已编译模型缓存钩子。

`bokeh.util.dependencies`#

用于检查依赖项的实用工具。

import_optional(mod_name: str) → ModuleType | None[source]#

尝试导入一个可选的依赖项。

如果请求的模块不可用，则静默返回 None。

参数:: mod_name (str) – 尝试导入的可选模块的名称
返回:: 导入的模块，如果导入失败，则返回 None

import_required(mod_name: str, error_msg: str) → ModuleType[source]#

尝试导入一个必需的依赖项。

如果请求的模块不可用，则引发 RuntimeError。

参数:

mod_name (str) – 尝试导入的必需模块的名称
error_msg (str) – 当模块缺失时要引发的错误消息

返回:

导入的模块

Raises:

RuntimeError –

uses_pandas(obj: Any) → bool[source]#

检查对象是否为 pandas 对象。

在条件 import pandas as pd 之前使用此函数。

`bokeh.util.deprecation`#

`bokeh.util.functions`#

用于函数内省的实用工具。

get_param_info(sig: Signature) → tuple[list[str], list[Any]][source]#

查找具有默认值的参数并返回它们。

参数:: sig (Signature) – 函数签名
返回:: 具有默认值的参数
返回类型:: tuple(list, list)

`bokeh.util.hex`#

用于处理六边形平铺的实用函数。

有关此处使用的概念的更多信息，请参阅此信息丰富的页面

https://www.redblobgames.com/grids/hexagons/

axial_to_cartesian(q: Any, r: Any, size: float, orientation: str, aspect_scale: float = 1) → tuple[Any, Any][source]#

将轴向 (q,r) 坐标映射到瓦片中心的笛卡尔 (x,y) 坐标。

此函数可用于在六边形平铺中相对于笛卡尔坐标定位其他 Bokeh 字形。

此函数改编自

https://www.redblobgames.com/grids/hexagons/#hex-to-pixel

参数:

q (array[float]) – 用于分箱的 q 坐标的 NumPy 数组
r (array[float]) – 用于分箱的 r 坐标的 NumPy 数组
size (float) –
六边形平铺的大小。

大小定义为对于 “pointytop” 方向，从六边形中心到顶部角的距离；或者对于 “flattop” 方向，从中心到侧面角的距离。
orientation (str) – 六边形瓦片方向应为 “pointytop” 还是 “flattop”。
aspect_scale (float, optional) –
在 “cross” 维度中缩放六边形。

对于 “pointytop” 方向，六边形在水平方向上缩放。对于 “flattop”，它们在垂直方向上缩放。

当使用 aspect_scale != 1 的绘图时，将此值设置为与绘图匹配可能很有用。

返回:

(array[int], array[int])

cartesian_to_axial(x: Any, y: Any, size: float, orientation: str, aspect_scale: float = 1) → tuple[Any, Any][source]#

将笛卡尔 (x,y) 点映射到封闭瓦片的轴向 (q,r) 坐标。

此函数改编自

https://www.redblobgames.com/grids/hexagons/#pixel-to-hex

参数:

x (array[float]) – 要转换的 x 坐标的 NumPy 数组
y (array[float]) – 要转换的 y 坐标的 NumPy 数组
size (float) –
六边形平铺的大小。

大小定义为对于 “pointytop” 方向，从六边形中心到顶部角的距离；或者对于 “flattop” 方向，从中心到侧面角的距离。
orientation (str) – 六边形瓦片方向应为 “pointytop” 还是 “flattop”。
aspect_scale (float, optional) –
在 “cross” 维度中缩放六边形。

对于 “pointytop” 方向，六边形在水平方向上缩放。对于 “flattop”，它们在垂直方向上缩放。

当使用 aspect_scale != 1 的绘图时，将此值设置为与绘图匹配可能很有用。

返回:

(array[int], array[int])

hexbin(x: npt.NDArray[np.floating], y: npt.NDArray[np.floating], size: float, orientation: HexTileOrientationType = 'pointytop', aspect_scale: float = 1) → pd.DataFrame[source]#

对数据点执行等权重分箱到六边形瓦片中。

对于更复杂的使用案例，例如加权分箱或将各个瓦片按比例缩放到其他量，请考虑使用 HoloViews。

参数:

x (array[float]) – 用于分箱的 x 坐标的 NumPy 数组
y (array[float]) – 用于分箱的 y 坐标的 NumPy 数组
size (float) –
六边形平铺的大小。

大小定义为对于 “pointytop” 方向，从六边形中心到顶部角的距离；或者对于 “flattop” 方向，从中心到侧面角的距离。
orientation (str, optional) – 六边形瓦片方向应为 “pointytop” 还是 “flattop”。（默认值：“pointytop”）
aspect_scale (float, optional) –
匹配绘图的纵横比缩放。

当使用 aspect_scale != 1 的绘图时，可以设置此参数以匹配绘图，以便绘制规则的六边形（而不是“拉伸”的六边形）。

这大致等效于在“屏幕空间”中进行分箱，并且当绘图纵横比不为 1 时，最好使用轴对齐的矩形箱。

返回:

DataFrame

生成的 DataFrame 将具有列 q 和 r，它们以轴向坐标指定六边形瓦片位置，以及列 counts，它提供每个瓦片的计数。

Warning

六边形分箱仅在线性刻度上起作用，即不在对数图中。

`bokeh.util.info`#

print_info() → None[source]#: 打印有关 Bokeh、Python、操作系统和选定的一组依赖项的版本信息。

`bokeh.util.logconfig`#

为 Bokeh 配置日志系统。

默认情况下，日志记录未配置，以允许 Bokeh 用户完全控制日志记录策略。但是，在开发 Bokeh 时，能够任意启用日志记录非常有用。这可以通过设置环境变量 BOKEH_PY_LOG_LEVEL 来完成。有效值按严重程度递增顺序排列

debug
info
warn
error
fatal
none

默认日志级别为 none。

basicConfig(**kwargs: Any) → None[source]#: 一个 logging.basicConfig() 包装器，它也撤消了默认的 Bokeh 特定配置。

`bokeh.util.options`#

用于指定、验证和记录配置选项的实用工具。

class Options(kw: dict[str, Any])[source]#

利用 Bokeh 属性类型系统来指定和验证配置选项。

Options 的子类使用标准 Bokeh 属性指定一组配置选项

class ConnectOpts(Options):

    host = String(default="127.0.0.1", help="a host value")

    port = Int(default=5590, help="a port value")

然后，可以通过传递包含与配置选项对应的键和值以及任何其他键和值的字典来创建 ConnectOpts。ConnectOpts 上与属性对应的项将从字典中移除。这对于除了某些 Bokeh 模型属性之外还接受自己的一组配置关键字参数的函数非常有用。

`bokeh.util.paths`#

bokehjs_path(dev: bool = False) → Path[source]#

获取 bokehjs 源文件的位置。

默认情况下，使用 bokeh/server/static 中的文件。如果 dev 为 True，则首选 bokehjs/build 中的文件。但是，如果不可用，则会发出警告，并将前一个文件用作后备。

bokehjsdir(dev: bool = False) → str[source]#

获取 bokehjs 源文件的位置。

默认情况下，使用 bokeh/server/static 中的文件。如果 dev 为 True，则首选 bokehjs/build 中的文件。但是，如果不可用，则会发出警告，并将前一个文件用作后备。

Deprecated since version 3.4.0: 使用 bokehjs_path() 代替。

server_path() → Path[source]#: 获取服务器子包的位置。

serverdir() → str[source]#: 获取服务器子包的位置。

Deprecated since version 3.4.0: 使用 server_path() 代替。

static_path() → Path[source]#: 获取服务器静态目录的位置。

`bokeh.util.serialization`#

用于帮助 Bokeh 对象序列化和反序列化的函数。

某些 NumPy 数组 dtype 可以序列化为二进制格式，以提高性能和效率。支持的 dtype 列表为

np.int16
np.uint32
np.bool
np.int8
np.float32
np.uint8
np.int32
np.uint16
np.float64

array_encoding_disabled(array: npt.NDArray[Any]) → bool[source]#

确定数组是否可以进行二进制编码。

可以编码的 NumPy 数组 dtype 为

np.int16
np.uint32
np.bool
np.int8
np.float32
np.uint8
np.int32
np.uint16
np.float64

参数:: array (np.ndarray) – 要检查的数组
返回:: bool

convert_date_to_datetime(obj: date) → float[source]#

将日期对象转换为 datetime

参数:: obj (date) – 要转换的对象
返回:: datetime

convert_datetime_array(array: npt.NDArray[Any]) → npt.NDArray[np.floating[Any]][source]#

将 NumPy datetime 数组转换为自 epoch 以来毫秒数的数组。

参数:

array –

(obj) 要转换的 datetime 的 NumPy 数组

如果传入的值不是 NumPy 数组，它将按原样返回。

返回:

array

将任何可识别的日期、时间或日期时间值转换为自 epoch 以来的浮点毫秒数。

参数:: obj (object) – 要转换的对象
返回:: 毫秒
返回类型:: 浮点数

convert_timedelta_type(obj: timedelta | timedelta64) → float[source]#

将任何可识别的时间差值转换为浮点绝对毫秒数。

参数:: obj (object) – 要转换的对象
返回:: 毫秒
返回类型:: 浮点数

is_datetime_type(obj: Any) → TypeGuard[time | datetime | datetime64][source]#

判断对象是否为 Bokeh 可识别的任何日期、时间或日期时间类型。

参数:: obj (object) – 要测试的对象
返回:: 如果 obj 是日期时间类型，则为 True
返回类型:: bool

is_timedelta_type(obj: Any) → TypeGuard[timedelta | timedelta64][source]#

判断对象是否为 Bokeh 可识别的任何时间差类型。

参数:: obj (object) – 要测试的对象
返回:: 如果 obj 是时间差类型，则为 True
返回类型:: bool

make_globally_unique_css_safe_id() → ID[source]#

返回全局唯一的 CSS 安全 UUID。

在某些情况下，例如在 HTML 文档中标识动态创建的 Div，始终需要全局唯一的 ID。使用此函数生成的 ID 可用于诸如 document.querySelector("#id") 之类的 API 中。

返回:: 字符串

make_globally_unique_id() → ID[source]#

返回全局唯一的 UUID。

在某些情况下，例如在 HTML 文档中标识动态创建的 Div，始终需要全局唯一的 ID。

返回:: 字符串

make_id() → ID[source]#

为 Bokeh 对象返回一个新的唯一 ID。

通常，此函数将返回简单的单调递增的整数 ID（作为字符串），用于标识文档中的 Bokeh 对象。但是，如果希望每个对象都具有全局唯一性，则可以通过设置环境变量 BOKEH_SIMPLE_IDS=no 来覆盖此行为。

返回:: 字符串

transform_array(array: npt.NDArray[Any]) → npt.NDArray[Any][source]#

将 ndarray 转换为可序列化的 ndarray。

转换不可序列化的 dtype 并返回 JSON 可序列化格式

参数:: array (np.ndarray) – 要转换的 NumPy 数组
返回:: ndarray

transform_series(series: pd.Series[Any] | pd.Index[Any] | pd.api.extensions.ExtensionArray) → npt.NDArray[Any][source]#

将 Pandas Series 转换为序列化形式

参数:: series (pd.Series) – 要转换的 Pandas Series
返回:: ndarray

`bokeh.util.token`#

用于生成和操作会话 ID 的实用工具。

会话 ID 通常与查看应用程序或绘图的每个浏览器选项卡关联。每个会话都有自己的状态，与其他服务器托管的会话分开。

check_session_id_signature(session_id: str, secret_key: bytes | None = None, signed: bool | None = False) → bool[source]#

检查会话 ID 的签名，如果有效则返回 True。

服务器使用此函数来检查会话 ID 是否是使用正确的密钥生成的。如果禁用了签名会话，则此函数始终返回 True。

check_token_signature(token: str, secret_key: bytes | None = None, signed: bool = False) → bool[source]#

检查令牌和包含的签名的签名。

服务器使用此函数来检查令牌和包含的会话 ID 是否是使用正确的密钥生成的。如果禁用了签名会话，则此函数始终返回 True。

参数:

token (str) – 要检查的令牌
secret_key (str, optional) – 密钥 (默认值：BOKEH_SECRET_KEY 环境变量的值)
signed (bool, optional) – 是否检查任何内容 (默认值：BOKEH_SIGN_SESSIONS 环境变量的值)

返回:

bool

generate_jwt_token(session_id: ID, secret_key: bytes | None = None, signed: bool = False, extra_payload: dict[str, Any] | None = None, expiration: int = 300) → str[source]#

根据 session_id 和附加的 payload 生成 JWT 令牌。

参数:

session_id (str) – 要添加到令牌的会话 ID
secret_key (str, optional) – 密钥 (默认值：BOKEH_SECRET_KEY 环境变量的值)
signed (bool, optional) – 是否对会话 ID 进行签名 (默认值：BOKEH_SIGN_SESSIONS 环境变量的值)
extra_payload (dict, optional) – 要包含在 Bokeh 会话令牌中的额外键/值对
expiration (int, optional) – 过期时间

返回:

字符串

generate_secret_key() → str[source]#

生成一个新的安全生成的密钥，适用于 SHA-256 HMAC 签名。

此密钥可用于对 Bokeh 服务器会话 ID 进行签名等。

generate_session_id(secret_key: bytes | None = None, signed: bool = False) → ID[source]#

生成随机会话 ID。

通常，连接到 Bokeh 应用程序的每个浏览器选项卡都有自己的会话 ID。在 Bokeh 应用程序的生产部署中，会话 ID 应该是随机且不可猜测的 - 否则应用程序的用户可能会互相干扰。

get_session_id(token: str) → ID[source]#

从 JWT 令牌中提取会话 ID。

参数:: token (str) – 包含 session_id 和其他数据的 JWT 令牌。
返回:: 字符串

get_token_payload(token: str) → dict[str, Any][source]#

从令牌中提取 payload。

参数:: token (str) – 包含 session_id 和其他数据的 JWT 令牌。
返回:: 字典

`bokeh.util.strings`#

用于字符串操作或编码的实用函数。

append_docstring(docstring: str | None, extra: str) → str | None[source]#

安全地附加到文档字符串。

当使用 -OO 选项执行 Python 时，文档字符串将被删除，并替换为值 None。此函数可防止在这种情况下附加额外的内容。

参数:

docstring (str 或 None) – 要格式化的文档字符串，或 None
extra (str) – 如果 docstring 不为 None，则要附加的内容

返回:

字符串或 None

format_docstring(docstring: None, *args: Any, **kwargs: Any) → None[source]#

format_docstring(docstring: str, *args: Any, **kwargs: Any) → str

安全地格式化文档字符串。

当使用 -OO 选项执行 Python 时，文档字符串将被删除，并替换为值 None。此函数可防止在这种情况下应用字符串格式化选项。

参数:

docstring (str 或 None) – 要格式化的文档字符串，或 None
args (tuple) – 文档字符串的字符串格式化参数
kwargs (dict) – 文档字符串的字符串格式化参数

返回:

字符串或 None

indent(text: str, n: int = 2, ch: str = ' ') → str[source]#

将给定文本块中的所有行缩进指定的量。

参数:

text (str) – 要缩进的文本
n (int, optional) – 每行缩进的量 (默认值：2)
ch (char, optional) – 用于填充缩进的字符 (默认值：“ ”)

nice_join(seq: Iterable[str], *, sep: str = ', ', conjunction: str = 'or') → str[source]#

使用连词 or 将字符串序列连接成友好的英语短语（如果适用）。

参数:

seq (seq[str]) – 要友好连接的字符串序列
sep (str, optional) – 要使用的序列分隔符 (默认值：“, ”)
conjunction (str 或 None, optional) – 用于最后两项的连词，或 None 以重现基本连接行为 (默认值：“or”)

返回:

连接的字符串

示例

>>> nice_join(["a", "b", "c"])
'a, b or c'

snakify(name: str, sep: str = '_') → str[source]#: 将 CamelCase 转换为 snake_case。

`bokeh.util.tornado`#

与 Tornado 相关的内部实用工具

`bokeh.util.terminal`#

提供用于格式化终端输出的实用工具。

`bokeh.util.version`#

为 Bokeh 库提供版本信息。

此模块使用 versioneer 来管理版本字符串。在开发期间，versioneer 将从当前的 git 修订版计算版本字符串。对于基于标签的打包发布，版本字符串在为分发打包的文件中硬编码。

__version__#: 此已安装 Bokeh 库的完整版本字符串

函数

base_version: 返回基本版本字符串，不附加任何“dev”、“rc”或本地构建信息。
is_full_release: 返回当前安装的版本是否为完整版本。

`bokeh.util.warnings`#

提供 Bokeh 特定的警告子类。

这些子类的主要用途是强制它们默认情况下无条件地向用户显示。

exception BokehDeprecationWarning[source]#

一个 Bokeh 特定的 DeprecationWarning 子类。

用于选择性地过滤 Bokeh 弃用警告以进行无条件显示。

exception BokehUserWarning[source]#

一个 Bokeh 特定的 UserWarning 子类。

用于选择性地过滤 Bokeh 警告以进行无条件显示。

find_stack_level() → int[source]#

在堆栈中查找第一个不在 Bokeh 内部的位置。

灵感来自：pandas.util._exceptions.find_stack_level

bokeh.util#

bokeh.util.browser#

bokeh.util.callback_manager#

bokeh.util.compiler#

bokeh.util.dependencies#

bokeh.util.deprecation#

bokeh.util.functions#

bokeh.util.hex#

bokeh.util.info#

bokeh.util.logconfig#

bokeh.util.options#

bokeh.util.paths#

bokeh.util.serialization#

bokeh.util.token#

bokeh.util.strings#

bokeh.util.tornado#

bokeh.util.terminal#

bokeh.util.version#

bokeh.util.warnings#

`bokeh.util.browser`#

`bokeh.util.callback_manager`#

`bokeh.util.compiler`#

`bokeh.util.dependencies`#

`bokeh.util.deprecation`#

`bokeh.util.functions`#

`bokeh.util.hex`#

`bokeh.util.info`#

`bokeh.util.logconfig`#

`bokeh.util.options`#

`bokeh.util.paths`#

`bokeh.util.serialization`#

`bokeh.util.token`#

`bokeh.util.strings`#

`bokeh.util.tornado`#

`bokeh.util.terminal`#

`bokeh.util.version`#

`bokeh.util.warnings`#