创建开发环境#

要测试代码更改，您需要从源代码构建 pandas，这需要 C/C++ 编译器和 Python 环境。如果您正在进行文档更改，则可以跳到 贡献给文档，但如果您跳过创建开发环境，则无法在推送更改之前在本地构建文档。建议同时安装 pre-commit 钩子。

步骤 1：安装 C 编译器#

如何操作将取决于您的平台。如果您在下一步选择使用 Docker 或 GitPod，则可以跳过此步骤。

Windows

您将需要 Visual Studio 2022 的生成工具。

注意

您不需要安装 Visual Studio 2022。您只需要“Visual Studio 2022 的生成工具”，该工具可以通过向下滚动到“所有下载”->“Visual Studio 工具”找到。在安装程序中，选择“使用 C++ 的桌面开发”工作负载。

或者，您可以使用 vs_BuildTools.exe 在命令行安装所需组件。

或者，您可以使用 WSL 并查阅下方的 Linux 说明。

macOS

要使用基于 mamba 的编译器，您需要使用 xcode-select --install 安装开发者工具。

如果您倾向于使用不同的编译器，可以在此处找到一般信息：https://devguide.pythonlang.cn/setup/#macos

Linux

对于基于 Linux 的 mamba 安装，您无需在 mamba 环境之外安装任何额外组件。以下说明仅在您的设置不基于 mamba 环境时才需要。

一些 Linux 发行版会预装 C 编译器。要查明您的系统上安装了哪些编译器（和版本）

# for Debian/Ubuntu:
dpkg --list | grep compiler
# for Red Hat/RHEL/CentOS/Fedora:
yum list installed | grep -i --color compiler

GCC (GNU Compiler Collection) 是一种广泛使用的编译器，支持 C 语言和许多其他语言。如果 GCC 已列为已安装的编译器，则无需其他操作。

如果没有安装 C 编译器，或者您希望升级，或者您正在使用不同的 Linux 发行版，请查阅您常用的搜索引擎以获取编译器安装/更新说明。

如果您遇到任何困难，请通过提出问题或在我们的贡献者社区 Slack 上联系我们。

步骤 2：创建隔离环境#

在开始之前，请

  • 确保您已克隆仓库

  • cd 到您刚刚通过克隆命令创建的 pandas 源代码目录

选项 2：使用 pip#

您需要至少具备 pandas 支持的最低 Python 版本。您还需要安装 setuptools 51.0.0 或更高版本才能构建 pandas。

Unix/**带 virtualenv 的 macOS**

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/virtualenvs/pandas-dev
# Any parent directories should already exist
python3 -m venv ~/virtualenvs/pandas-dev

# Activate the virtualenv
. ~/virtualenvs/pandas-dev/bin/activate

# Install the build dependencies
python -m pip install -r requirements-dev.txt

Unix/**带 pyenv 的 macOS**

请查阅此处的文档以设置 pyenv。

# Create a virtual environment
# Use an ENV_DIR of your choice. We'll use ~/Users/<yourname>/.pyenv/versions/pandas-dev
pyenv virtualenv <version> <name-to-give-it>

# For instance:
pyenv virtualenv 3.9.10 pandas-dev

# Activate the virtualenv
pyenv activate pandas-dev

# Now install the build dependencies in the cloned pandas repo
python -m pip install -r requirements-dev.txt

Windows

以下是关于如何在 Windows 下使用 Powershell 设置虚拟环境的简要概述。有关详细信息，请参阅virtualenv 官方用户指南。

使用您选择的 ENV_DIR。我们将使用 ~\\virtualenvs\\pandas-dev，其中 ~ 是由 $env:USERPROFILE (Powershell) 或 %USERPROFILE% (cmd.exe) 环境变量指向的文件夹。任何父目录都应该已经存在。

# Create a virtual environment
python -m venv $env:USERPROFILE\virtualenvs\pandas-dev

# Activate the virtualenv. Use activate.bat for cmd.exe
~\virtualenvs\pandas-dev\Scripts\Activate.ps1

# Install the build dependencies
python -m pip install -r requirements-dev.txt

选项 3：使用 Docker#

pandas 在根目录中提供了一个 DockerFile，用于构建包含完整 pandas 开发环境的 Docker 镜像。

Docker 命令

构建 Docker 镜像

# Build the image
docker build -t pandas-dev .

运行容器

# Run a container and bind your local repo to the container
# This command assumes you are running from your local repo
# but if not alter ${PWD} to match your local repo path
docker run -it --rm -v ${PWD}:/home/pandas pandas-dev

更简单的是，您可以将 Docker 与以下 IDE 集成

Visual Studio Code

您可以使用 DockerFile 通过 .devcontainer.json 文件，与流行的免费 IDE Visual Studio Code 启动远程会话。详情请参阅 https://vscode.js.cn/docs/remote/containers。

PyCharm (专业版)

启用 Docker 支持，并使用服务工具窗口构建和管理镜像，以及运行和与容器交互。详情请参阅 https://www.jetbrains.com/help/pycharm/docker.html。

选项 4：使用 Gitpod#

Gitpod 是一个开源平台，它直接在您的浏览器中自动创建正确的开发环境，从而减少了安装本地开发环境和处理不兼容依赖的需求。

如果您是 Windows 用户，不熟悉命令行或首次构建 pandas，使用 Gitpod 通常会更快。以下是使用 GitPod 构建 pandas 的详细说明。

步骤 3：构建并安装 pandas#

目前有两种支持的构建 pandas 的方式：pip/meson 和 setuptools(setup.py)。历史上，pandas 仅支持使用 setuptools 构建。然而，这种方法需要在 setup.py 中编写大量复杂的代码，并且由于 setuptools 的限制，在并行编译 pandas 时也存在许多问题。

较新的构建系统通过 pip（通过 PEP 517 构建）调用 meson 后端。它会自动使用 CPU 上所有可用的核心，并通过在导入 pandas 时自动重建（通过可编辑安装）来避免手动重建的需要。

基于这些原因，您应该使用 meson 编译 pandas。由于 meson 构建系统较新，随着其成熟，您可能会发现一些错误/小问题。您可以在此处报告这些错误。

要使用 meson 编译 pandas，运行

# Build and install pandas
# By default, this will print verbose output
# showing the "rebuild" taking place on import (see section below for explanation)
# If you do not want to see this, omit everything after --no-build-isolation
python -m pip install -ve . --no-build-isolation --config-settings editable-verbose=true

注意

版本号是从最新的仓库标签中提取的。请务必在构建之前从上游获取最新的标签。

# set the upstream repository, if not done already, and fetch the latest tags
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream --tags

构建选项

如果您想配置您的安装，可以将选项从 pip 前端传递给 meson 后端。有时，您会希望使用此功能来调整构建目录和/或切换调试/优化级别。

您可以通过在 pip 命令后附加 --config-settings builddir="your builddir here" 来向 pandas 传递构建目录。此选项允许您配置 meson 存储构建的 C 扩展的位置，并允许快速重建。

有时，在调试 C 扩展时，使用调试符号编译 pandas 可能很有用。附加 --config-settings setup-args="-Ddebug=true" 即可实现。

使用 pip，可以链接多个配置设置（例如，同时指定构建目录和使用调试符号构建将看起来像 --config-settings builddir="your builddir here" --config-settings=setup-args="-Dbuildtype=debug"）。

使用 setup.py 编译 pandas

注意

随着 meson 后端的成熟，这种编译 pandas 的方法将很快被弃用并移除。

要使用 setuptools 编译 pandas，运行

python setup.py develop

注意

如果 pandas 已经安装（通过 meson），您必须首先卸载它

python -m pip uninstall pandas

这是因为 python setup.py develop 不会卸载 meson-python 用来从构建文件夹导入扩展的加载器脚本，这可能会导致诸如 FileNotFoundError 等错误。

注意

每次 C 扩展更改时，您都需要重复此步骤，例如，如果您修改了 pandas/_libs 中的任何文件，或者您从 upstream/main 进行了拉取和合并。

检查构建

此时，您应该能够从本地构建的版本中导入 pandas

$ python
>>> import pandas
>>> print(pandas.__version__)  # note: the exact output may differ
2.0.0.dev0+880.g2b9e661fbb.dirty

此时，您可能想尝试运行测试套件。

保持与最新构建同步

当使用 meson 构建 pandas 时，即使 C/Cython 文件被修改，导入 pandas 也会自动触发重建。默认情况下，此重建不会产生任何输出（导入只会花费更长时间）。如果您想在导入 pandas 时看到 meson 的输出，您可以设置环境变量 MESONPY_EDTIABLE_VERBOSE。例如，这将是

# On Linux/macOS
MESONPY_EDITABLE_VERBOSE=1 python

# Windows
set MESONPY_EDITABLE_VERBOSE=1 # Only need to set this once per session
python

如果您每次都想看到此详细输出，可以将 editable-verbose 配置设置设为 true，如下所示

python -m pip install -ve . --config-settings editable-verbose=true

提示

如果您想知道您的 pandas 是使用 setuptools 还是 meson 构建的，可以检查 pandas._built_with_meson 的值，如果使用 meson 编译，则该值为 true。