贡献Python代码#

Bokeh代码库结合了用Python和TypeScript编写的代码。本章概述了在处理Bokeh的Python代码时需要了解的最重要事项。

代码风格#

Bokeh 的 Python 代码通常遵循 PEP8 标准。一些显著的例外包括：

为了保持一致性，请对字符串使用双引号（"string"）
不要编写超过165个字符的行
编写 Google Python 风格指南文档字符串（更多信息请参见编写文档字符串）

Bokeh 为每个 Pull Request 使用了一系列代码质量测试。与 Python 代码相关的测试包括 Ruff 和 isort。使用以下命令在本地运行这些代码库测试：

pytest tests/codebase

要了解更多关于在您的系统上运行这些测试的信息，请参阅运行代码库测试。

测试#

所有Pull Requests，如果添加或更新代码，都应包括新的或更新的测试。有关测试的更多信息，包括特定于Python的测试，请参阅运行测试和编写测试。

源代码组织#

Bokeh 仓库包含 Bokeh 的 Python 代码以及 BokehJS 的 JavaScript 代码。以下是包含 Python 代码的最相关文件夹：

src/bokeh/

Bokeh库本身的Python代码位于 src/bokeh 文件夹中。

构成Bokeh可视化的所有内容（例如工具, 图形符号, 小部件, 或列数据源）都是基于Bokeh模型的。所有模型的Python代码位于 src/bokeh/models。有关模型的更多信息，请参见下面的模型和属性。

此文件夹中的其他子目录包括：

src/bokeh/plotting 包含 Bokeh 的绘图接口
src/bokeh/colors 包含处理颜色的代码
src/bokeh/embed 包含用于在网页中嵌入Bokeh内容的代码。
src/bokeh/io 包含 Bokeh 的 IO 功能代码，例如文件导出和笔记本输出
src/bokeh/palettes 包含 Bokeh 的调色板的代码
src/bokeh/sphinxext 包含用于自定义 Sphinx 扩展的代码，这些代码在 Bokeh 的文档中使用。

有关此目录及其子目录结构的更多信息，请参阅参考指南。

examples/

examples 文件夹包含了 Bokeh 大部分功能的示例。其中一些示例被用于 Bokeh 的 gallery。

tests/

tests 文件夹包含 Bokeh 的测试套件。有关测试的更多信息，请参见运行测试和编写测试。

typings/

src/typings 文件夹包含 Bokeh 类型提示的存根文件。

模型和属性#

所有Bokeh可视化的核心构建块都是基于Bokeh的模型的对象。这些模型是绘图元素的表示，例如坐标轴、图形符号或小部件。

在Python方面，Bokeh将每个绘图元素对象的属性序列化为JSON数据。在浏览器方面，BokehJS将这些JSON数据反序列化，并根据这些信息创建JavaScript对象。BokehJS然后使用这些JavaScript对象来渲染可视化。

流程图描述了数据从Python对象通过JSON流向浏览器端的过程。在那里，JSON数据被转换为JavaScript对象，然后被渲染为输出。输出可以是HTML Canvas、WebGL或SVG。

每当你在Python中更新或添加模型时，你还需要更新BokehJS对应的TypeScript代码。

Bokeh的所有Python模型都位于src/bokeh/models及其子文件夹中。它们都是Model的子类：

class SomeNewModel(Model):
    """ Some new model. """

模型包含属性，这些属性是在bokeh.core.properties中定义的类属性。例如：

class ModelWithIntProps(Model):
    prop1 = Int()
    prop2 = Int(10)

在这个例子中，ModelWithIntProps 模型代表具有两个整数值的对象，分别是 prop1 和 prop2。

Bokeh 使用了多种属性类型：

原始类型如 Byte, Int, Float, Complex, 或 String
类似容器的属性，这些属性将其他属性作为参数，例如 List (List(Int)) 或 Dict (Dict(String, Double))
特殊类型如 Instance (Instance(Plot)), Enum (Enum("foo", "bar", "baz")), 或 Either (Either(Int, String))

这些属性类型有几种用途：

类型检查不同的模型
确保模型在Python和JavaScript之间保持兼容
自动生成一些基本的文档用于参考指南

一个更现实的模型的例子可能看起来像这样：

class SomeModel(Model):
    prop1 = Int(127)
    prop2 = Either(Int, List(Int), Dict(String, List(Int)))
    prop3 = Enum("x", "y", "z")
    prop4 = Range(Float, 0.0, 1.0)
    prop5 = List(Instance(Range1d))

详情请参见 bokeh.core.properties。

警告

类 Any 是所有其他类型的超类型，并且会接受任何类型的值。由于这绕过了所有的类型验证，请确保谨慎使用它，如果有的话。

输入#

Bokeh 使用两个系统来检查 Python 代码的类型：

对于上述模型系统，Bokeh 使用其自己的属性系统。更多信息请参见模型和属性。
对于任何不使用模型的代码，Bokeh 使用 PEP 484 风格的提示。如有必要，请使用 Python 标准的 typing 和 typing_extensions 模块。

Bokeh的CI 使用 mypy 来检查类型。要在本地检查代码的类型，请运行 mypy bokeh。

注意

如果你想在除mypy之外的工具中使用类型信息（例如，使用typing.get_type_hints提取信息），你很可能需要使用Python 3.10或更高版本。这是因为Bokeh的一些类型提示使用了PEP 604中定义的X | Y语法来表示联合类型。