bokeh.core.validation#

验证模块提供了对整个 Bokeh 模型集合执行完整性检查的功能。

要创建 Bokeh 可视化，中心任务是从 bokeh.models 中组装模型对象集合，形成一个表示应在客户端中创建的场景的图。可以“手动”执行此操作，直接使用模型对象。但是，为了简化此过程，Bokeh 提供了更高级别的接口，例如供用户使用的 bokeh.plotting。

这些接口自动化了常见的“组装”步骤，以确保以一致且可预测的方式创建 Bokeh 对象图。但是，无论使用何种接口，都可能以不完整或在某种程度上没有意义的方式将 Bokeh 模型组合在一起。

为了帮助诊断潜在问题，Bokeh 在输出可视化以进行显示时执行验证步骤。此模块包含错误和警告代码以及用于定义验证检查的辅助函数。

警告的一个用例是大声地向用户指出正确的方向，当他们意外地做了他们可能不是想要做的事情时 - 例如 EMPTY_LAYOUT 就是这种情况。由于警告不一定表示误用，因此它们是可配置的。要静默警告，请使用提供的 silence 函数。

>>> from bokeh.core.validation import silence
>>> from bokeh.core.validation.warnings import EMPTY_LAYOUT
>>> silence(EMPTY_LAYOUT, True)

错误代码#

这些定义了 Bokeh 验证检查的标准错误代码和消息。

1001 (BAD_COLUMN_NAME): 字形 (glyph) 的属性设置为字段名称，该名称与 GlyphRenderer 的数据源中的任何列都不对应。
1002 (MISSING_GLYPH): GlyphRenderer 没有配置字形 (glyph)。
1003 (NO_SOURCE_FOR_GLYPH): GlyphRenderer 没有配置数据源。
1004 (REQUIRED_RANGE): Plot 缺少一个或多个必需的默认范围（将导致空白绘图）。
1005 (MISSING_GOOGLE_API_KEY): Google Maps API 现在要求所有使用都需要 API 密钥。有关如何获取自己的 API 密钥以用于 Google Map 绘图的 api_key 属性的更多信息，请参阅 https://developers.google.com/maps/documentation/javascript/get-api-key。
1006 (NON_MATCHING_DATA_SOURCES_ON_LEGEND_ITEM_RENDERERS): 当 LegendItem.label 类型为字段时，LegendItem.renderers 上的所有 data_sources 必须匹配。
1007 (MISSING_MERCATOR_DIMENSION): MercatorTicker 和 MercatorTickFormatter``models must have their ``dimension 模型必须将其 dimension 属性设置为 'lat' 或 'lon'。
1008 (REQUIRED_SCALE): Scale 上缺少一个或多个必需的默认比例（将导致空白绘图）。
1009 (INCOMPATIBLE_SCALE_AND_RANGE): Scale 类型与同一绘图维度上的一个或多个范围不兼容（将导致空白绘图）。
1011 (MALFORMED_GRAPH_SOURCE): GraphSource 配置不正确。
1012 (INCOMPATIBLE_MAP_RANGE_TYPE): 地图绘图只能支持 Range1d 类型，不支持数据范围。
1013 (INCOMPATIBLE_POINT_DRAW_RENDERER): PointDrawTool 渲染器只能引用 XYGlyph 模型。
1014 (INCOMPATIBLE_BOX_EDIT_RENDERER): BoxEditTool 渲染器只能引用 Rect 字形模型。
1015 (INCOMPATIBLE_POLY_DRAW_RENDERER): PolyDrawTool 渲染器只能引用 MultiLine 和 Patches 字形模型。
1016 (INCOMPATIBLE_POLY_EDIT_RENDERER): PolyEditTool 渲染器只能引用 MultiLine 和 Patches 字形模型。
1017 (INCOMPATIBLE_POLY_EDIT_VERTEX_RENDERER): PolyEditTool vertex_renderer 只能引用 XYGlyph 模型。
1018 (NO_RANGE_TOOL_RANGES): RangeTool 必须配置至少一个 x_range 或 y_range
1019 (DUPLICATE_FACTORS): FactorRange 必须为轴指定唯一的分类因子列表。
1020 (BAD_EXTRA_RANGE_NAME): 配置的额外范围名称与任何范围都不对应。
1021 (EQUAL_SLIDER_START_END): noUiSlider 必须具有不相等的起点和终点。
1022 (MIN_PREFERRED_MAX_WIDTH): 预期 min_width <= width <= max_width
1023 (MIN_PREFERRED_MAX_HEIGHT): 预期 min_height <= height <= max_height
1024 (CDSVIEW_FILTERS_WITH_CONNECTED): CDSView 过滤器与具有连接拓扑的字形（例如 Line 或 Patch）不兼容。
1025 (INCOMPATIBLE_LINE_EDIT_RENDERER): LineEditTool 渲染器只能引用 MultiLine 和 Line 字形模型。
1026 (INCOMPATIBLE_LINE_EDIT_INTERSECTION_RENDERER): LineEditTool intersection_enderer 只能引用 LineGlyph 模型。
1027 (REPEATED_LAYOUT_CHILD): 同一模型不能在布局中多次使用。
9999 (EXT): 表示自定义错误检查失败。

警告代码#

这些定义了 Bokeh 验证检查的标准警告代码和消息。

1000 (MISSING_RENDERERS): Plot 对象没有配置渲染器（将导致空白绘图）。
1002 (EMPTY_LAYOUT): 布局模型没有子项（将导致空白布局）。
1004 (BOTH_CHILD_AND_ROOT): 每个组件只能在一个地方渲染，不能既是根又是布局中的子项。
9999 (EXT): 表示自定义警告检查失败。

辅助函数#

这些辅助函数可用于对 Bokeh 模型集合执行完整性检查，或将模型上的方法标记为警告或错误检查。

check_integrity(models: Iterable[Model]) → ValidationIssues[source]#

收集与 Bokeh 模型集合关联的所有警告。

参数:: models (seq[Model]) – 要测试的模型集合
返回:: 包含所有警告和错误消息的集合
返回类型:: ValidationIssues

此函数将返回一个对象，其中包含检测到的所有错误和/或警告条件。例如，没有任何子项的布局会将警告添加到集合中

>>> empty_row = Row()

>>> check_integrity([empty_row])
ValidationIssues(
    warning=[
        ValidationIssue(
            code=1002,
            name="EMPTY_LAYOUT",
            text="Layout has no children",
            extra="Row(id='1001', ...)",
        ),
    ],
)

silence(warning: Warning, silence: bool = True) → set[Warning][source]#

静默所有 Bokeh 模型上的特定警告。

参数:

warning (Warning) – 要静默的 Bokeh 警告
silence (bool) – 是否静默警告

返回:

包含所有已静默警告的集合

此函数将警告添加到静默器集合或从静默器集合中删除警告，该集合在运行 check_integrity 时引用。如果警告被添加到静默器中 - 那么它将永远不会被引发。

>>> from bokeh.core.validation.warnings import EMPTY_LAYOUT
>>> bokeh.core.validation.silence(EMPTY_LAYOUT, True)
{1002}

要重新打开警告，请使用相同的方法，但将 silence 参数设置为 false

>>> bokeh.core.validation.silence(EMPTY_LAYOUT, False)
set()

error(code_or_name: int | str | Issue) → Callable[[Callable[[...], str | None]], Validator][source]#

用于标记 Bokeh 错误条件的验证器方法的装饰器

参数:: code_or_name (int, str or Issue) – 来自 bokeh.validation.errors 的代码或自定义检查的字符串标签
返回:: Bokeh 模型方法的装饰器
返回类型:: 可调用对象

被装饰的函数必须具有以 _check 开头的名称，并在检测到错误条件时返回字符串消息，如果没有检测到错误条件，则返回 None。

示例

第一个示例使用数字代码表示 bokeh.validation.errors 中提供的标准错误。此用法主要供 Bokeh 核心开发人员使用。

from bokeh.validation.errors import REQUIRED_RANGES

@error(REQUIRED_RANGES)
def _check_no_glyph_renderers(self):
    if bad_condition: return "message"

第二个示例展示了如何通过将任意字符串标签传递给装饰器来实现自定义警告检查。此用法主要供任何使用自己的自定义模型扩展 Bokeh 的人员使用。

@error("MY_CUSTOM_WARNING")
def _check_my_custom_warning(self):
    if bad_condition: return "message"

warning(code_or_name: int | str | Issue) → Callable[[Callable[[...], str | None]], Validator][source]#

用于标记 Bokeh 错误条件的验证器方法的装饰器

参数:: code_or_name (int, str or Issue) – 来自 bokeh.validation.errors 的代码或自定义检查的字符串标签
返回:: Bokeh 模型方法的装饰器
返回类型:: 可调用对象

被装饰的函数应该具有以 _check 开头的名称，并在检测到错误条件时返回字符串消息，如果没有检测到错误条件，则返回 None。

示例

第一个示例使用数字代码表示 bokeh.validation.warnings 中提供的标准警告。此用法主要供 Bokeh 核心开发人员使用。

from bokeh.validation.warnings import MISSING_RENDERERS

@warning(MISSING_RENDERERS)
def _check_no_glyph_renderers(self):
    if bad_condition: return "message"

第二个示例展示了如何通过将任意字符串标签传递给装饰器来实现自定义警告检查。此用法主要供任何使用自己的自定义模型扩展 Bokeh 的人员使用。

@warning("MY_CUSTOM_WARNING")
def _check_my_custom_warning(self):
    if bad_condition: return "message"