设置开发环境#

Bokeh 项目由两个主要组件构成：Bokeh 包源代码（使用 Python 编写）和 BokehJS 客户端库（使用 TypeScript 编写）。

因此，您需要设置两个环境才能为 Bokeh 做出贡献：Python 环境和 TypeScript 环境。本章将引导您完成设置完整开发环境的所有必要步骤。

1. 检查基本要求#

安装或更新 Git#

Bokeh 源代码存储在 Git 源代码控制仓库中。使用 Bokeh 的第一步是在您的系统上安装或更新 Git。

根据您使用的是 Windows、OSX 还是 Linux，有不同的方法可以执行此操作。要在任何平台上安装 Git，请参阅安装 Git 部分，该部分位于 Pro Git Book 中。

如果您以前从未使用过 Git，可以在 Git 文档中找到一些初学者教程和资源的链接。

安装或更新 conda#

处理 Bokeh 代码库需要安装几个非 Python 包的软件包。例如，用于 TypeScript 开发的 Node.js 或用于测试和导出的 Selenium。

为了能够在一个地方管理 Python 和非 Python 依赖项，Bokeh 使用 conda 包管理器。conda 是免费 Anaconda Python 发行版的一部分，适用于 Windows、macOS 和 Linux。Conda 为您创建和管理虚拟环境。因此，您不需要像 venv、virtualenv 或 pipenv 这样的工具。虽然从技术上讲，可以在没有 conda 的情况下手动安装所有依赖项，但本指南将假定您已安装 conda。

要在您的系统上安装或更新 Conda，请参阅安装，该部分位于 Conda 文档中。

注意

如果您的系统上已安装 conda，请通过运行以下命令确保它是最新的

conda update -n base -c defaults conda

2. Fork 和克隆仓库#

Bokeh 项目的源代码托管在 GitHub 上，地址为 bokeh/bokeh。

除非您是 @bokeh/dev 开发团队成员，否则您首先需要创建 Bokeh 主仓库的一个 fork。在 fork 时，请确保取消选中将复制限制为特定分支的复选框（例如“仅复制 branch-3.2 分支”）。有关创建 fork 的更多信息，请参阅 Fork 一个仓库，该部分位于 GitHub 帮助中。

接下来，将您要处理的 Bokeh 仓库版本克隆到您硬盘驱动器上的本地文件夹。使用 git clone 或按照克隆 fork 仓库中的说明进行操作，该部分位于 GitHub 帮助中。

克隆仓库会在您的文件系统位置创建一个 bokeh 目录。此本地 bokeh 目录在本文档的其余部分中称为源代码检出。

在继续之前，有必要使用以下命令将 Bokeh 仓库添加为额外的上游仓库

SSH

git remote add upstream git@github.com:bokeh/bokeh.git
git fetch upstream

HTTPS

git remote add upstream https://github.com/bokeh/bokeh.git
git fetch upstream

3. 创建 conda 环境#

您刚刚克隆到本地硬盘驱动器的 Bokeh 仓库在 conda 文件夹中包含测试环境文件。这些文件中包含自动创建基本开发环境所需的所有信息。

在您的源代码检出目录的根级别使用 conda env create 来设置环境并安装所有必要的软件包。“测试”环境文件按 Python 版本进行版本控制。

例如，要为 Python 3.10 安装环境，请调用

conda env create -n bkdev -f conda/environment-test-3.10.yml

注意

使用 conda -n bkdev 选项将 bkdev 设置为您的环境名称。本章的其余部分和本指南中的所有其他章节都假定这是您的环境名称。

然后，激活环境

conda activate bkdev

注意

要更新您的本地环境，请使用 conda env update --name bkdev -f conda/<environment file>。每当测试环境中的依赖项发生更改时，都需要更新您的本地环境。例如，当主 Bokeh 仓库中的环境文件更新时，或者当您切换分支以处理不同的 issue 时，可能会发生这种情况。

要了解有关创建和管理 conda 环境的更多信息，请参阅管理环境，该部分位于 Conda 文档中。

4. 安装 Node 包#

构建 BokehJS 还需要使用 Node 包管理器 (npm) 安装 JavaScript 依赖项。如果您已按照上面的说明进行操作，则 conda 已经将必要的 npm 和 node.js 包安装到您的系统中。

Bokeh 通常需要最新主要版本的 npm。要全局安装最新版本，请从源代码检出目录的顶层开始，然后运行以下命令

cd bokehjs
npm install --location=global npm

如果您不想全局安装 npm，请省略 --location=global 标志。在这种情况下，您需要调整所有后续的 npm 命令，以使用在 bokehjs/node_modules 下安装的本地版本。

接下来，仍然在 bokehjs 子目录中，运行以下命令来安装 BokehJS 的所有 JavaScript 依赖项

npm ci

此命令将必要的包安装到 node_modules 子目录中。

注意

通常，您只需在首次设置本地环境时执行此操作一次。但是，如果添加或更改了依赖项，则需要重复这些步骤来安装和更新相应的包。

5. 设置 pre-commit#

Bokeh 使用 pre-commit 来帮助您防止提交中出现一些常见错误。

要在本地设置 pre-commit，请从您的源代码检出目录的顶层运行以下命令

python scripts/hooks/install.py

这将 pre-commit 配置为使用两个 Git 钩子，每当您将提交推送到 Bokeh 的 GitHub 仓库时，它们都会检查您的代码

代码库测试: git-commit 将运行 Bokeh 的代码库测试，以检查代码库质量问题，例如空格和导入。这包括使用 Ruff、ESLint 和 isort 进行测试。
受保护分支: git-commit 将确保您不会意外地将提交推送到 Bokeh 的受保护分支 main 和 branch-x.y 上。

注意

根据您的系统，运行这些测试可能需要几十秒钟。如果任何测试失败，请检查控制台的输出。在大多数情况下，您可以在这里找到有关需要更改哪些内容才能通过测试的必要信息。

要卸载 Git 钩子，请从您的源代码检出目录的顶层运行以下命令

python scripts/hooks/uninstall.py

6. 本地构建和安装#

安装完所有必需的依赖项后，构建和安装 Bokeh 和 BokehJS 的最简单方法是使用 pip。pip 是 Python 的包安装程序，当您设置 conda 环境时会自动安装。在运行 pip 之前，请确保您已激活 bkdev 环境。

有两种使用 pip 安装 Bokeh 本地开发版本的方法

pip install -e .: Bokeh 将被安装为引用您的本地源目录。您对 Python 源代码所做的任何更改都将立即生效，而无需任何其他步骤。这是处理 Bokeh 代码库时推荐的模式。
pip install .: Bokeh 将安装在您的本地 Python site-packages 目录中。在这种模式下，对 Python 源代码的任何更改都不会生效，直到您再次运行 pip install .。

运行这两个命令中的任何一个也会构建和安装本地版本的 BokehJS。如果您想跳过构建新版本的 BokehJS 而改用不同的本地版本，请设置 BOKEHJS_ACTION 环境变量：BOKEHJS_ACTION="install" pip install -e .

注意

您需要每次 BokehJS 源代码更改时都重建 BokehJS。这可能是必要的，因为您自己进行了更改，或者因为您从 GitHub 拉取了更新的代码。重新运行 pip install -e . 以构建和安装 BokehJS。

有时，JavaScript 依赖项列表也会更改。如果发生这种情况，您需要在重建 BokehJS 之前重新运行4. 安装 Node 包部分中的说明。

8. 测试本地设置#

运行以下测试以检查所有内容是否已正确安装和设置

测试 Bokeh 核心#

首先，使用以下命令来测试 Bokeh 安装

python -m bokeh info

你应该看到类似于以下的输出

Python version        :  3.12.3 | packaged by conda-forge | (main, Apr 15 2024, 18:38:13) [GCC 12.3.0]
IPython version       :  8.19.0
Tornado version       :  6.3.3
NumPy version         :  2.0.0
Bokeh version         :  3.5.1
BokehJS static path   :  /opt/anaconda/envs/test/lib/python3.12/site-packages/bokeh/server/static
node.js version       :  v20.12.2
npm version           :  10.8.2
jupyter_bokeh version :  (not installed)
Operating system      :  Linux-5.15.0-86-generic-x86_64-with-glibc2.35

运行示例#

接下来，运行一些 Bokeh 自带的独立示例。

确保环境变量 BOKEH_RESOURCES 设置为 absolute-dev 或 inline，以便使用本地版本的 BokehJS。在 *source checkout* 目录中，运行以下命令

Linux/macOS

BOKEH_RESOURCES=inline python examples/basic/data/transform_markers.py

Windows (PS)

$Env:BOKEH_RESOURCES = "inline"
python.exe .\examples\basic\data\transform_markers.py

Windows (CMD)

set BOKEH_RESOURCES=inline
python examples\basic\data\transform_markers.py

这会在本地创建一个文件 transform_markers.html。当你在 Web 浏览器中打开此文件时，它应该显示此可视化效果

../../_images/bokeh_transform_markers_html.png

运行 Bokeh 服务器#

使用 Bokeh 的另一种方式是作为服务器。将环境变量 BOKEH_DEV=false 设置为 false，并在 *source checkout* 目录中运行 bokeh serve 命令

Linux/macOS

BOKEH_DEV=false python -m bokeh serve --show examples/server/app/sliders.py

Windows (PS)

$Env:BOKEH_DEV = "False"
python.exe -m bokeh serve --show .\examples\server\app\sliders.py

Windows (CMD)

set BOKEH_DEV=false
python -m bokeh serve --show examples\server\app\sliders.py

这应该会打开一个浏览器，其中包含一个交互式图形

所有滑块都允许对正弦波进行交互式控制，每次更新都会使用新参数重新绘制线条。--show 选项会打开一个 Web 浏览器。Bokeh 服务器的默认 URL 是 localhost:5006。

故障排除#

更新现有的开发环境并不总是按预期工作。作为一般规则，请确保你的 conda 环境、Node 包和本地构建始终是最新的。

以下列表包含你在设置开发环境时可能遇到的一些常见问题的解决方案

有关运行和安装 Bokeh 的更多信息，请查看贡献者可用的其他资源。请随时在 Bokeh Discourse 或 Bokeh 的贡献者 Slack 上提问。

设置开发环境#

1. 检查基本要求#

安装或更新 Git#

安装或更新 conda#

2. Fork 和克隆仓库#

3. 创建 conda 环境#

4. 安装 Node 包#

5. 设置 pre-commit#

6. 本地构建和安装#

7. 设置环境变量#

`BOKEH_RESOURCES`#

`BOKEH_DEV`#

8. 测试本地设置#

测试 Bokeh 核心#

运行示例#

运行 Bokeh 服务器#

故障排除#

设置开发环境#

1. 检查基本要求#

安装或更新 Git#

安装或更新 conda#

2. Fork 和克隆仓库#

3. 创建 conda 环境#

4. 安装 Node 包#

5. 设置 pre-commit#

6. 本地构建和安装#

7. 设置环境变量#

BOKEH_RESOURCES#

BOKEH_DEV#

8. 测试本地设置#

测试 Bokeh 核心#

运行示例#

运行 Bokeh 服务器#

故障排除#

`BOKEH_RESOURCES`#

`BOKEH_DEV`#