创建开发环境#

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

步骤 1：安装 C 编译器#

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

Windows

您将需要 Visual Studio 2022 的构建工具.

注意

您**不需要**安装 Visual Studio 2022。您只需要“Visual Studio 的构建工具”，可以在“所有下载” -> “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 编译器集合） 是一种广泛使用的编译器，它支持 C 和许多其他语言。如果 GCC 被列为已安装的编译器，则无需其他操作。

如果未安装 C 编译器，或者您希望升级，或者您使用的是不同的 Linux 发行版，请咨询您喜欢的搜索引擎以获取编译器安装/更新指令。

如果您遇到任何困难，请通过打开问题或联系我们的贡献者社区 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

你可以使用 DockerFile 启动一个与 Visual Studio Code（一个流行的免费 IDE）的远程会话，使用 .devcontainer.json 文件。有关详细信息，请参阅 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 构建 pandas。但是，这种方法需要在 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 后端。有时，您需要使用它来调整构建目录，以及切换调试/优化级别。

您可以通过将 --config-settings builddir="your builddir here" 附加到您的 pip 命令来将构建目录传递给 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

注意

这种编译 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 中进行了提取和合并。

检查构建

此时，您应该能够从本地构建的版本导入 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_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

提示

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