创建开发环境#

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

步骤 1：安装 C 编译器#

具体操作将取决于您的平台。

Windows

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

注意

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

如果您在尝试使用 Meson 构建时遇到指示 cl.exe 未找到的错误，请重新打开安装程序，并在右侧窗格中选择可选组件 **MSVC v142 - VS 2019 C++ x64/x86 生成工具** 进行安装。

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

或者，您可以使用 WSL 并参考下面的 Linux 说明。

macOS

要使用 conda 作为基础的编译器，您需要使用 xcode-select --install 安装开发人员工具。

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

Linux

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

一些 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：创建隔离环境#

在我们开始之前，请

  • 确保您已经 克隆了仓库

  • 使用 clone 命令 cd 到您刚刚创建的 pandas 源代码目录

选项 2：使用 pip#

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

Unix/macOS with 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 with pyenv

请在此处查阅 pyenv 设置的文档： https://github.com/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.11 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：构建和安装 pandas#

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

较新的构建系统通过 pip（通过 PEP 517 构建）调用 meson 后端。它会自动利用您 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 -Ceditable-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 命令后追加 -Cbuilddir="your builddir here" 来将构建目录传递给 pandas。此选项允许您配置 meson 存储已构建 C 扩展的位置，并支持快速重新构建。

有时，在调试 C 扩展时，将 pandas 与调试符号一起编译会很有用。追加 -Csetup-args="-Ddebug=true" 即可完成。

使用 pip，可以链式调用多个配置设置。例如，同时指定构建目录和使用调试符号构建将如下所示：-Cbuilddir="your builddir here" -Csetup-args="-Dbuildtype=debug"。

使用 setup.py 编译 pandas

注意

这种编译 pandas 的方法很快就会被弃用和移除，因为 meson 后端正在成熟。

要使用 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 时，导入 pandas 会自动触发重新构建，即使 C/Cython 文件被修改。默认情况下，此重新构建不会产生任何输出（导入只是需要更长时间）。如果您希望在导入 pandas 时看到 meson 的输出，可以设置环境变量 MESONPY_EDITABLE_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 . -Ceditable-verbose=true

提示

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