bokeh.util

提供一系列用于实现 Bokeh 功能的通用实用程序。

bokeh.util.browser

用于帮助执行涉及浏览器的操作的实用程序函数。

class DummyWebBrowser

一个“无操作”的网络浏览器控制器。

open(url: str, new: Literal[0, 1, 2] = 0, autoraise: bool = True) → bool

接收标准参数，不执行任何操作。

get_browser_controller(browser: str | None = None) → BrowserLike

返回一个浏览器控制器。

参数：

browser (str 或 None) –

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

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

返回值：

一个网络浏览器控制器

返回类型：

控制器

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

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

参数：

• location (str) – 要打开的位置 如果 location 不以“http:”开头，则假定它是本地文件系统上的文件路径。

• browser (str 或 None) – 使用什么浏览器 (默认值：None) 如果为 None，则使用系统默认浏览器。

• new (str) –

  如何打开位置。有效值为

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

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

  'window' - 在新窗口中打开

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

返回值：

无

bokeh.util.callback_manager

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

class EventCallbackManager(*args: Any, **kw: Any)

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

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

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

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

class PropertyCallbackManager(*args: Any, **kw: Any)

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

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

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

参数：

• attr (str) – 此对象上的属性名称

• callback (callable) – 要注册的回调函数

返回值：

无

remove_on_change(attr: str, *callbacks: Callable[[str, Any, Any], None]) → None

从此对象中删除回调。

trigger(attr: str, old: Any, new: Any, hint: DocumentPatchedEvent | None = None, setter: Setter | None = None) → None

触发此对象上attr的回调函数。

bokeh.util.compiler

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

exception CompilationError(error: dict[str, str] | str)

用于报告JS编译错误的RuntimeError子类。

class AttrDict

提供一个支持通过命名属性访问的dict子类。

class CustomModel(cls: type[HasProps])

表示自定义（用户定义）的Bokeh模型。

class FromFile(path: str)

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

参数：

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

class Implementation

表示Bokeh自定义模型实现的基类。

class Inline(code: str, file: str | None = None)

表示可能以某种语言的内联代码给出的Bokeh自定义模型实现的基类。

参数：

• code (str) – 实现的源代码

• file (str, 可选) – 包含源文本的文件路径（默认值：None）

class JavaScript(code: str, file: str | None = None)

JavaScript中Bokeh自定义模型的实现

示例

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

class Less(code: str, file: str | None = None)

Less CSS样式表的实现。

class TypeScript(code: str, file: str | None = None)

TypeScript中Bokeh自定义模型的实现

示例

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

bundle_all_models() → str | None

创建所有模型的bundle。

bundle_models(models: Sequence[type[HasProps]] | None) → str | None

创建选定models的bundle。

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

生成一个键，用于缓存自定义扩展实现。

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

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

get_cache_hook() → Callable[[CustomModel, Implementation], AttrDict | None]

返回当前缓存钩子，用于根据CustomModel和Implementation查找编译后的代码。

set_cache_hook(hook: Callable[[CustomModel, Implementation], AttrDict | None]) → None

设置一个编译模型缓存钩子，用于根据CustomModel和Implementation查找编译后的代码。

bokeh.util.dependencies

用于检查依赖项的实用程序。

import_optional(mod_name: str) → ModuleType | None

尝试导入可选的依赖项。

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

参数：

mod_name (str) – 要尝试导入的可选模块的名称

返回值：

导入的模块或None，如果导入失败。

import_required(mod_name: str, error_msg: str) → ModuleType

尝试导入必需的依赖项。

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

参数：

• mod_name (str) – 要尝试导入的必需模块的名称

• error_msg (str) – 模块丢失时要引发的错误消息

返回值：

导入的模块

引发:

RuntimeError –

uses_pandas(obj: Any) → bool

检查对象是否为pandas对象。

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

bokeh.util.deprecation

bokeh.util.functions

函数内省的实用程序。

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

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

参数：

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]

将轴向(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) –

  沿“交叉”维度缩放六边形。

  对于“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]

将笛卡尔(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) –

  沿“交叉”维度缩放六边形。

  对于“pointytop”方向，六边形沿水平方向缩放；对于“flattop”，六边形沿垂直方向缩放。

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

返回值：

(array[int], array[int])

hexbin(x: Any, y: Any, size: float, orientation: str = 'pointytop', aspect_scale: float = 1) → Any

将数据点等权重分箱到六边形图块中。

对于更复杂的使用案例，例如加权分箱或按其他数量比例缩放单个图块，请考虑使用 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列。

警告

六边形分箱仅适用于线性刻度，即不适用于对数绘图。

bokeh.util.info

print_info() → None

打印有关 Bokeh、Python、操作系统和选定依赖项的版本信息。

bokeh.util.logconfig

配置 Bokeh 的日志系统。

默认情况下，不会配置日志记录，以允许 Bokeh 用户完全控制日志记录策略。但是，在开发 Bokeh 时能够任意启用日志记录很有用。这可以通过设置环境变量BOKEH_PY_LOG_LEVEL来实现。有效值为（按严重性递增顺序排列）

• debug

• 信息

• warn

• error

• fatal

• none

默认日志记录级别为none。

basicConfig(**kwargs: Any) → None

一个logging.basicConfig()包装器，它还会撤消默认的 Bokeh 特定配置。

bokeh.util.options

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

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

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

获取 bokehjs 源文件的位置。

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

bokehjsdir(dev: bool = False) → str

获取 bokehjs 源文件的位置。

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

自版本 3.4.0 起已弃用: 请改用 bokehjs_path()。

server_path() → Path

获取服务器子包的位置。

serverdir() → str

获取服务器子包的位置。

自版本 3.4.0 起已弃用: 请改用 server_path()。

static_path() → Path

获取服务器静态目录的位置。

bokeh.util.serialization

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

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

• np.float32

• np.uint32

• np.int32

• np.int8

• np.uint8

• np.uint16

• np.float64

• np.int16

• np.bool

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

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

可以编码的 NumPy 数组数据类型为

• np.float32

• np.uint32

• np.int32

• np.int8

• np.uint8

• np.uint16

• np.float64

• np.int16

• np.bool

参数：

array (np.ndarray) – 要检查的数组

返回值：

bool

convert_date_to_datetime(obj: date) → float

将日期对象转换为日期时间。

参数：

obj (date) – 要转换的对象

返回值：

datetime

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

将 NumPy 日期时间数组转换为自纪元以来的毫秒数组。

参数：

array –

(obj) 要转换的日期时间 NumPy 数组

如果传入的值不是 NumPy 数组，则会原样返回。

返回值：

array

convert_datetime_type(obj: Any | pd.Timestamp | pd.Timedelta | dt.datetime | dt.date | dt.time | np.datetime64) → float

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

参数：

obj (object) – 要转换的对象

返回值：

毫秒

返回类型：

float

convert_timedelta_type(obj: timedelta | timedelta64) → float

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

参数：

obj (object) – 要转换的对象

返回值：

毫秒

返回类型：

float

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

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

参数：

obj (object) – 要测试的对象

返回值：

如果obj是日期时间类型，则返回 True

返回类型：

bool

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

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

参数：

obj (object) – 要测试的对象

返回值：

如果obj是时间差类型，则返回 True

返回类型：

bool

make_globally_unique_css_safe_id() → ID

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

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

返回值：

字符串

make_globally_unique_id() → ID

返回一个全局唯一的 UUID。

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

返回值：

字符串

make_id() → ID

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

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

返回值：

字符串

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

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

将 Pandas 系列转换为序列化形式。

参数：

series (pd.Series) – 要转换的 Pandas 系列

返回值：

ndarray

bokeh.util.token

用于生成和操作会话 ID 的实用程序。

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

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

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

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

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

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

服务器使用此函数检查令牌和包含的会话 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

根据会话 ID 和其他有效负载生成 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

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

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

generate_session_id(secret_key: bytes | None = None, signed: bool = False) → ID

生成随机会话 ID。

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

get_session_id(token: str) → ID

从 JWT 令牌中提取会话 ID。

参数：

token (str) – 包含会话 ID 和其他数据的 JWT 令牌。

返回值：

字符串

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

提取令牌中的有效负载。

参数：

token (str) – 包含会话 ID 和其他数据的 JWT 令牌。

返回值：

字典

bokeh.util.strings

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

append_docstring(docstring: str | None, extra: str) → str | None

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

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

参数：

• docstring (str 或 None) – 要格式化的文档字符串，或 None

• extra (str) – 如果 docstring 不为 None，则要追加的内容

返回值：

str 或 None

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

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

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

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

参数：

• docstring (str 或 None) – 要格式化的文档字符串，或 None

• args (元组) – 文档字符串的字符串格式化参数

• kwargs (字典) – 文档字符串的字符串格式化参数

返回值：

str 或 None

indent(text: str, n: int = 2, ch: str = ' ') → str

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

参数：

• text (str) – 要缩进的文本

• n (int, 可选) – 缩进每一行的量（默认值：2）

• ch (char, 可选) – 用什么字符填充缩进（默认值：“ ”）

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

使用连接词or（在适当情况下）将字符串序列连接成对英语友好的短语。

参数：

• seq (seq[str]) – 要很好地连接的字符串序列

• sep (str, 可选) – 要使用的序列分隔符（默认值：“, “）

• conjunction (str 或 None, 可选) – 用于最后两个项目的连接词，或 None 以重现基本连接行为（默认值：“or”）

返回值：

连接后的字符串

示例

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

snakify(name: str, sep: str = '_') → str

将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特定的警告子类。

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

异常 BokehDeprecationWarning

Bokeh特定的DeprecationWarning子类。

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

异常 BokehUserWarning

Bokeh特定的UserWarning子类。

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

find_stack_level() → int

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

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