创建一个开发环境#

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

步骤 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.python.org/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 with 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.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 文件启动一个与 Visual Studio Code 的远程会话，这是一个流行的免费 IDE。详情请参见 https://code.visualstudio.com/docs/remote/containers。

PyCharm (专业版)

启用 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 来构建 pandas。然而，这种方法在 setup.py 中需要大量复杂的代码，并且在并行编译 pandas 时由于 setuptools 的限制存在许多问题。

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

基于这些原因，你应该使用 meson 编译 pandas。因为 meson 构建系统较新，在其成熟过程中你可能会发现一些错误/小问题。你可以在这里报告这些错误 here。

要使用 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 后端。偶尔，你会想使用这个来调整构建目录，和/或切换调试/优化级别。

You can pass a build directory to pandas by appending -Cbuilddir="your builddir here" to your pip command. This option allows you to configure where meson stores your built C extensions, and allows for fast rebuilds.

Sometimes, it might be useful to compile pandas with debugging symbols, when debugging C extensions. Appending -Csetup-args="-Ddebug=true" will do the trick.

With pip, it is possible to chain together multiple config settings (for example specifying both a build directory and building with debug symbols would look like -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 进行了获取和合并。

检查构建

在这一点上，你应该能够从你本地构建的版本中导入 pandas:

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

在这一点上，您可能想要尝试 运行测试套件。

保持与最新构建同步

When building pandas with meson, importing pandas will automatically trigger a rebuild, even when C/Cython files are modified. By default, no output will be produced by this rebuild (the import will just take longer). If you would like to see meson’s output when importing pandas, you can set the environment variable MESONPY_EDITABLE_VERBOSE. For example, this would be:

# 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，该值将为真。