创建开发环境#

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

步骤 1：安装 C 编译器#

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

Windows

你需要Visual Studio 2022 的 Build Tools。

注意

你不需要安装 Visual Studio 2022。你只需要向下滚动到“所有下载” -> “Tools for Visual Studio”找到“Build Tools for Visual Studio 2022”。在安装程序中，选择“使用 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 发行版，请查阅你常用的搜索引擎以获取编译器安装/更新说明。

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

步骤 2：创建隔离环境#

在我们开始之前，请确保

  • 你已经克隆了仓库

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

选项 2：使用 pip#

你需要至少达到 pandas 支持的最低 Python 版本。你还需要setuptools 51.0.0 或更高版本才能构建 pandas。

Unix/macOS 使用 virtualenv

# 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/macOS 使用 pyenv

请参考这里的文档来设置 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

你可以使用.devcontainer.json文件将 DockerFile 用于使用 Visual Studio Code（一个流行的免费 IDE）启动远程会话。详细信息请参阅https://vscode.js.cn/docs/remote/containers。

PyCharm (Professional)

启用 Docker 支持并使用 Services 工具窗口构建和管理镜像，以及运行和与容器交互。详细信息请参阅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 调用 meson 后端（通过PEP 517构建）。它会自动使用 CPU 上的所有可用核心，并且通过在导入 pandas 时自动重新构建来避免手动重新构建（使用可编辑安装）。

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

要使用 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

注意

版本号从最新的仓库标签中提取。在构建之前，请确保从 upstream 获取最新的标签。

# 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进行了 fetch 和 merge，你都需要重复此步骤。

检查构建

此时你应该能够从本地构建的版本中导入 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。