创建开发环境#

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

第1步：安装C编译器#

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

视窗

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

笔记

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

或者，您可以使用vs_BuildTools.exe在命令行上安装必要的组件

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

苹果系统

要使用基于mamba的编译器，您需要使用. 否则，有关编译器安装的信息可以在这里找到： https ://devguide.python.org/setup/#macosxcode-select --install

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 源目录

选项1：使用mamba（推荐）#

安装曼巴
确保您的 Mamba 是最新的 ( )mamba update mamba

 # Create and activate the build environment
mamba env create --file environment.yml
mamba activate pandas-dev

选项 2：使用 pip #

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

带有 virtualenv 的Unix / 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

使用 pyenv 的Unix / 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下使用Powershell搭建虚拟环境。详细信息请参考官方 virtualenv 用户指南。

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

 # 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 集成：

视觉工作室代码

您可以使用 DockerFile 使用该.devcontainer.json文件启动与 Visual Studio Code（一种流行的免费 IDE）的远程会话。有关详细信息，请参阅https://code.visualstudio.com/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构建）调用介子后端。它会自动使用 CPU 上的所有可用内核，并且每当导入 pandas（通过可编辑安装）时都会自动重建，从而避免了手动重建的需要。

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

要使用介子编译 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

构建选项

如果您想配置安装，可以将选项从 pip 前端传递到 meson 后端。有时，您需要使用它来调整构建目录，和/或切换调试/优化级别。

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

有时，在调试 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 的方法很快就会被弃用并删除。

要使用 setuptools 编译 pandas，请运行：

 python setup.py develop

笔记

如果pandas已经安装（通过介子），你必须先卸载它：

 python -m pip uninstall pandas

这是因为 python setup.pydevelop 不会卸载用于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

使用介子构建 pandas 时，即使 C/Cython 文件被修改，导入 pandas 也会自动触发重建。默认情况下，此重建不会产生任何输出（导入将花费更长的时间）。如果你想在导入 pandas 时看到介子的输出，你可以设置环境变量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，则该值是正确的。