Pandas 2.2 中文文档（八十）

原文：pandas.pydata.org/docs/

pandas.errors.SettingWithCopyWarning

原文：pandas.pydata.org/docs/reference/api/pandas.errors.SettingWithCopyWarning.html

异常pandas.errors.SettingWithCopyWarning

如果您尝试将其设置在从DataFrame 复制的切片上，您将收到警告。

mode.chained_assignment 必须设置为“警告”。警告是默认选项。链接索引时可能会无意中发生这种情况。

有关评估顺序的更多信息，请参阅用户指南。

有关视图和副本的更多信息，请参阅用户指南。

例子

df=pd.DataFrame({\’A\’: [1, 1, 1, 2, 2]}, columns=[\’A\’])

df.loc[0:3][\’A\’]=\’a\’

. #SettingWithCopyWarning: 正在尝试设置要复制的值.

pandas.errors.SpecificationError

原文：pandas.pydata.org/docs/reference/api/pandas.errors.SpecificError.html

异常pandas.errors.规范错误

如果没有正确指定agg 函数，agg 函数将抛出异常。

在两种情况下会抛出异常。

第一种方法是使用嵌套重命名函数(dict-dict) 在DataFrame 或Series 上调用agg。

第二种方法是在DataFrame 上调用agg，而不分配重复的函数和列名称。

例子

df=pd.DataFrame({\’A\’: [1, 1, 1, 2, 2],

.\’B\’: 范围(5),

.\’C\’: 范围(5)})

df.groupby(\’A\’).B.agg({\’foo\’: \’count\’})

. #SpecificationError: 不支持嵌套重命名功能

df.groupby(\’A\’).agg({\’B\’: {\’foo\’: [\’sum\’, \’max\’]}})

. #SpecificationError: 不支持嵌套重命名功能

df.groupby(\’A\’).agg([\’min\’, \’min\’])

. #SpecificationError: 不支持嵌套重命名功能

pandas.errors.UndefinedVariableError

原文：pandas.pydata.org/docs/reference/api/pandas.errors.UnknownVariableError.html

异常pandas.errors.UnknownVariableError(name, is_local=None)

如果使用未定义的变量名称，查询或计算将引发异常。

它还指示未定义的变量是否是局部的。

例子

df=pd.DataFrame({\’A\’: [1, 1, 1]})

df.query(\’A x\’)

. # UnknownVariableError: 名称“x”未定义

df.query(\’A @y\’)

. # UnknownVariableError: 局部变量\’y\’ 未定义

pd.eval(\’x + 1\’)

. # UnknownVariableError: 名称“x”未定义

pandas.errors.UnsortedIndexError

原文：pandas.pydata.org/docs/reference/api/pandas.errors.UnsortedIndexError.html

异常pandas.errors.UnsortedIndexError

对未按词法排序的MultiIndex 进行切片时引发错误。

KeyError 的子类。

例子

df=pd.DataFrame({\’cat\’: [0, 0, 1, 1],

. \’颜色\’: [\’白色\’, \’白色\’, \’棕色\’, \’黑色\’],

.\’生活\’: [4,4,3,7]},

df=df.set_index([\’猫\’, \’颜色\’])

D.F.

活

猫的颜色

0 白色4

白色4

1 棕色3

黑7

df.loc[(0, \’黑色\’):(1, \’白色\’)]

回溯（最后一次调用）:

UnsortedIndexError: \’密钥长度(2) 太长

MultiIndex lexsort深度(1)比\’

pandas.errors.UnsupportedFunctionCall

原文：pandas.pydata.org/docs/reference/api/pandas.errors.UnsupportedFunctionCall.html

异常pandas.errors.UnsupportedFunctionCall

尝试调用不受支持的numpy 函数时引发异常。

例如，np.cumsum(groupby_object)。

例子

df=pd.DataFrame({\’A\’: [0, 0, 1, 1],

. \’B\’: [\’x\’, \’x\’, \’z\’, \’y\’],

. \’C\’: [1, 2, 3, 4]}

np.cumsum(df.groupby([\’A\’]))

回溯（最后一次调用）:

UnsupportedFunctionCall: numpy 操作在groupby 中无效。

使用.groupby(.).cumsum() 代替

pandas.errors.ValueLabelTypeMismatch

原文：pandas.pydata.org/docs/reference/api/pandas.errors.ValueLabelTypeMismatch.html

异常pandas.errors.ValueLabelTypeMismatch

警告：to_stata 函数针对包含非字符串值的分类列引发警告。

例子

df=pd.DataFrame({\’categories\’: pd.Series([\’a\’, 2], dtype=\’category\’)})

df.to_stata(\’测试\’)

. # ValueLabelTypeMismatch: Stata 值标签（pandas 类别）必须是str.

pandas.show_versions

原文：pandas.pydata.org/docs/reference/api/pandas.show_versions.html

pandas.show_versions(as_json=False)

提供对错误报告很重要的有用信息。

这包括有关托管操作系统、pandas 版本以及已安装的其他相关软件包的版本的信息。

参数：

as_jsonstr 或bool，默认为False

如果为False，则以人类可读的格式将信息打印到控制台。

对于str，它被视为文件路径。该信息以JSON 格式写入文件。

如果为True，则以JSON 格式将信息输出到控制台。

例子

pd.show_versions()

输出将为：

安装版本

——————

提交： 37ea63d540fd27274cad6585082c91b1283f963d

Python : 3.10.6.final.0

Python 位： 64

操作系统： Linux

操作系统版本： 5.10.102.1-microsoft-standard-WSL2

版本： #1 SMP 3 月2 日星期三00:30:59 UTC 2022

机器： x86_64

处理器： x86_64

兼职订单：一点

LC_ALL : 无

LANG : en_GB.UTF-8

区域设置： en_GB.UTF-8

熊猫： 2.0.1

numpy : 1.24.3

缺失值

原文：pandas.pydata.org/docs/reference/missing_value.html

NA 是一种表示可空数据类型缺失值的方法（见下文）。

NANA（“不可用”）缺失值指示符。

NaT 是间隔和日期时间数据的缺失值（见下文）。

NaT(N)ot-(A)-(T)ime，时间相当于NaN。

pandas.NA

原文：pandas.pydata.org/docs/reference/api/pandas.NA.html

熊猫NA

别名

pandas.NaT

原文：pandas.pydata.org/docs/reference/api/pandas.NaT.html

熊猫.NaT

NaT 的另一个名称

开发

原文：pandas.pydata.org/docs/development/index.html

为熊猫做贡献

错误报告和改进建议

找到一个你可以解决的问题

提交拉取请求

成功提交拉取请求的提示

创建开发环境

第1步：安装C编译器

第二步：创建隔离环境

第3 步：构建并安装pandas

为文档做出贡献

关于pandas 文档

更新pandas 文档字符串

如何构建pandas 文档

预览更改

为代码库做出贡献

代码规范

预提交

可选依赖项

向后兼容性

输入提示

使用持续集成进行测试

测试驱动开发

运行测试套件

运行性能测试套件

记录代码

熊猫维护

角色

任务

问题类别

回复调查

关闭问题

审查拉取请求

回溯

清理旧问题

清理旧的拉取请求

成为熊猫维护者

合并拉取请求

基准机

发布流程

内部机制

指数

继承pandas数据结构

写时复制

参考跟踪调试C 扩展

本地调试

使用Docker

编辑支持

扩展熊猫

注册自定义访问器

扩展型

继承pandas数据结构

绘图后端

使用第三方类型的算术运算

开发商

以Apache Parquet 格式保存pandas DataFrame 对象的策略

版本策略

Python支持

安全策略

贡献者社区

社区会议

新贡献者会议

日历

GitHub 问题跟踪器

开发者邮件列表

社区闲置

贡献给 pandas

原文：pandas.pydata.org/docs/development/contributing.html

错误报告和增强请求

找到一个你可以解决的问题

提交拉取请求

版本控制、Git、GitHub

开始使用Git

创建一个pandas 分支

创建功能分支

更改代码

推送更改

创建拉取请求

更新拉取请求

更新您的开发环境

成功提交拉取请求的提示

我们欢迎所有贡献、错误报告、错误修复、文档改进、增强和想法。

错误报告和增强请求

错误报告和增强请求是使Pandas 更加稳定的重要组成部分，并通过Github issues 进行管理。报告问题或请求时，请选择适当的类别并完整填写问题表格，以便其他人和核心开发团队能够充分了解问题的范围。

问题将在Panda 社区中显示，并欢迎其他人提出意见和想法。

找到要贡献的问题

如果您不熟悉Pandas 或开源开发，我们建议您搜索GitHub 问题选项卡以查找您感兴趣的问题。未分配的问题被标记为文档，好的第一期通常对新贡献者有好处。

当您发现一个有趣的问题时，最好将其分配给自己，以避免向其他人重复。对于Github 问题，带有确切文本的评论将自动分配问题（这可能需要几秒钟，并且需要您刷新页面才能查看）。

如果由于某种原因您无法继续处理该问题，请取消分配该问题，以便其他人知道它可以再次使用。您可以查看分配的作业列表，因为可能没有人再处理它们。如果您想处理已分配给您的问题，请随时询问当前人员是否可以接管该问题（请在考虑暂停该问题之前至少等待一周）。

我们为贡献者社区提供多种沟通渠道。加入我们并在我们解决问题时提出问题。其中包括新贡献者定期会议、开发者会议、开发者邮件列表和Slack 贡献者社区。欢迎所有Panda 贡献者加入这些空间，我们可以在这里相互联系。即使是像您这样长期与我们合作的维护人员也不知道我们是如何工作的，也不知道您刚开始时事情在哪里。他们会很高兴地欢迎您，并帮助您了解我们的工作方式以及物品的位置。请参阅下一章了解更多信息。

提交拉取请求

版本控制、Git 和 GitHub

pandas 托管在GitHub 上，您必须注册免费的GitHub 帐户才能做出贡献。我们使用Git 进行版本控制，以便许多人可以一起处理项目。

如果您是Git 新手，可以通过以下资源了解Git：如果您需要帮助，您可以随时联系我们的贡献者社区。

Git 文档。

Numpy Git 资源教程。

此外，该项目遵循本页详细介绍的分叉工作流程。在此工作流程中，贡献者分叉存储库、进行更改并创建拉取请求。因此，请务必阅读并遵循本指南中的所有说明。

如果这是您第一次通过GitHub 上的分支为项目做出贡献，请查看GitHub 关于为项目做出贡献的文档。 GitHub 提供了有关使用测试存储库的快速教程，帮助您习惯分叉存储库、克隆分支、创建功能分支、推送更改和创建拉取请求。

以下是一些有助于理解GitHub 分叉和拉取请求的有用资源。

有关分叉存储库的GitHub 文档。

有关协作和拉取请求的GitHub 文档。

有关使用分支的GitHub 文档。

开始使用 Git

GitHub 提供了安装git、设置SSH 密钥和配置git 的说明。必须完成所有这些步骤才能在本地存储库和GitHub 之间无缝工作。

创建 pandas 的分支

您需要自己的Pandas 副本（例如叉子）才能使用该代码。转到pandas 项目页面并单击Fork 按钮。在选择创建分支之前，取消选中该框以仅复制主分支。您需要将fork 克隆到您的机器上

git clone https://github.com/your-user-name/pandas.git pandas-yourname

cd 熊猫-你的名字

git 远程添加上游https://github.com/pandas-dev/pandas.git

git 获取上游

这将创建目录pandas-yourname 并将存储库连接到上游（主项目）pandas 存储库。

消息

如果执行浅克隆（使用–Depth==N，其中N 大于或等于1），某些测试和函数（例如pd.show_versions()）可能会中断，因为无法计算版本号。

创建功能分支

您的本地主分支应始终反映pandas 存储库的当前状态。首先，确保您的pandas 主存储库是最新的。

git checkout 主要

git pull 上游main –ff-only

接下来，创建一个功能分支来进行更改。例如

git checkout -b 闪亮的新功能

这会将您的工作分支从主分支更改为最新的功能分支。该分支中的更改应该是特定于错误或功能的，以便清楚该分支为pandas 带来了什么。它有许多功能分支，您可以使用git checkout 命令在它们之间切换。

如果您想更新功能分支以反映主分支中的更改，请查看有关更新PR 的部分。

进行代码更改

在修改代码之前，请务必按照贡献环境指南设置适当的开发环境。

修改代码后，您可以运行它以查看到目前为止所做的所有更改。

git 状态

对于您想要修改或添加的任何文件，请运行：

git add 添加或修改的文件的路径/到/文件.py

再次运行git status 你应该看到

分支机构闪亮的新功能

Modified: /relative/path/to/文件添加或修改.py

最后，使用描述性提交消息将更改提交到本地存储库。

git commit -m \’你的提交消息放在这里\’

““### 推送更改

如果您想在GitHub 页面上发布更改，请在分叉的功能分支上推送提交。

“Pi

git Push Origin 闪亮新功能

其中origin 是GitHub 上远程存储库的默认名称。可以查看远程仓库

git 远程-v

如上所述添加上游存储库后，您将看到如下内容：

来源[[email protected]](/cdn-cgi/l/email-protection):yourname/pandas.git (获取)

来源[[email protected]](/cdn-cgi/l/email-protection):yourname/pandas.git (推送)

上游git: //github.com/pandas-dev/pandas.git （获取）

上游git://github.com/pandas-dev/pandas.git （推送）

代码位于GitHub 上，但尚未成为pandas 项目的一部分。为此，您需要在GitHub 上提交拉取请求。

提交拉取请求

完成代码更改后，您必须遵循Pandas 的发布指南才能成功接受您的代码更改。

如果一切看起来都很好，那么您就可以提交拉取请求了。 Pull 请求是GitHub 社区审查本地存储库中的代码并将其合并到您的项目中以便它出现在下一个版本中的一种方式。提交拉取请求：

转到GitHub 上的存储库

单击“比较拉取请求”按钮

然后单击“提交和更改的文件”并确保一切看起来都很好。

编写包含前缀的描述性标题。 pandas 使用标题前缀约定。以下是一些常见的前缀以及使用它们的一般准则。

ENH: 增强功能、新功能BUG: 错误修复DOC: 文档添加/更新TST: 测试添加/更新BLD: 构建流程/脚本更新PERF: 性能优化TYP: 类型注释CLN: 代码清理

在“讨论预览”选项卡中写下您的更改的描述。

单击以提交拉取请求。

该请求被发送给存储库维护者，由他审查代码。

更新您的 Pull Request

根据您收到的拉取请求评论，您可能需要对代码进行一些更改。您可以按照以下步骤重新提交代码以解决反馈并更新您的拉取请求。

pandasmain 分支的更新也很重要，应该反映在拉取请求中。要将功能分支与pandasmain 分支中的更改同步，请运行：

git checkout 闪亮的新功能

git 获取上游

git 合并上游/主干

如果没有冲突（或可以自动修复），文件将使用默认提交消息打开，您只需保存它即可。

并退出该文件。

如果有合并冲突，则需要解决这些冲突。例如，可以参考help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/来了解如何解决这些冲突。

一旦冲突解决完毕，运行：

运行git add -u来暂存您更新的任何文件；
运行git commit完成合并。

注意

如果您在想要将分支更新到main时有未提交的更改，则需要在更新之前stash它们（参见stash 文档）。这将有效地存储您的更改，可以在更新后重新应用它们。

特性分支在本地更新后，现在您可以通过将分支推送到 GitHub 上的分支来更新您的 Pull Request：

git push origin shiny-new-feature

任何git push都将自动使用您分支的更改更新您的 Pull Request 并重新启动持续集成检查。 ### 更新开发环境

定期将您的本地main分支与 pandasmain分支的更新同步，并更新您的开发环境以反映在开发过程中使用的各种包的任何更改都是很重要的。

如果使用 mamba，运行：

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml –prune

如果使用 pip，执行：

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install –upgrade -r requirements-dev.txt

成功发起 Pull Request 的技巧

如果您已经进入了发起 Pull Request 阶段，核心贡献者之一可能会查看。然而，请注意，少数人负责审查所有的贡献，这通常会导致瓶颈。

为了提高拉取请求被审查的机会，你应该：

引用一个开放问题以澄清 PR 的目的
确保你有适当的测试。这些应该是任何 PR 的第一部分
尽量保持你的拉取请求简单。较大的 PR 需要更长时间来审查
确保 CI 处于绿色状态。否则，审阅者可能根本不会看
保持更新你的拉取请求，不论是要求还是每隔几天

错误报告和改进请求

错误报告和改进请求是使 pandas 更加稳定的重要组成部分，并通过 Github 问题进行策划。在报告问题或请求时，请选择适当的类别并完整填写问题表单，以确保其他人和核心开发团队能够充分理解问题的范围。

该问题将会显示给 pandas 社区，并对其他人的评论/想法开放。

寻找要贡献的问题

如果你是 pandas 或开源开发的新手，我们建议在GitHub 的“issues”标签页上搜索你感兴趣的问题。未分配的标记为Docs和good first issue的问题通常适合新贡献者。

一旦你找到一个有趣的问题，最好把它分配给自己，这样其他人就不会重复进行工作。在 Github 问题中，发表一条包含确切文本take的评论，以自动将问题分配给你（这将花费几秒钟，并可能需要刷新页面才能看到它）。

如果由于任何原因你无法继续处理问题，请取消分配它，这样其他人就知道它又可用了。你可以检查已分配问题的列表，因为可能没有人在处理它们。如果你想处理一个已分配的问题，请友好地询问当前受让人是否可以接手它（请至少允许一周的不活动时间，然后再考虑中断问题的工作）。

我们有几个贡献者社区交流渠道，欢迎你加入，并在你摸清楚情况时提问。其中包括新贡献者的定期会议、开发会议、开发邮件列表和贡献者社区的 Slack。所有 pandas 贡献者都可以加入这些空间，在这里他们可以互相联系。即使是已经和我们在一起很长时间的维护者，在开始时也和你一样感到不知所措，他们很乐意欢迎你，并在你了解我们的工作方式和事物所在的过程中支持你。请看下一节了解更多信息。

提交拉取请求

版本控制、Git 和 GitHub

pandas 托管在GitHub，为了贡献，你需要注册一个免费的 GitHub 帐户。我们使用Git进行版本控制，以允许多人共同在项目上工作。

如果你对 Git 是新手，你可以参考这些资源学习 Git。如果需要帮助，可以随时联系贡献者社区：

Git 文档。
Numpy 的 Git 资源教程。

此外，该项目遵循本页面进一步描述的分叉工作流程，贡献者分叉仓库，进行更改，然后创建拉取请求。因此，请务必阅读并遵循本指南中的所有说明。

如果你是通过在 GitHub 上分叉项目来贡献的新手，请查看GitHub 贡献项目的文档。GitHub 提供了一个快速教程，使用一个测试仓库，可能会帮助你更熟悉如何分叉仓库、克隆分叉、创建功能分支、推送更改和发起拉取请求。

以下是一些关于在 GitHub 上了解分叉和拉取请求的有用资源：

GitHub 有关分叉仓库的文档。
GitHub 有关与拉取请求协作的文档。
GitHub 有关使用分叉的文档。

开始使用 Git

GitHub 有关安装 git、设置 SSH 密钥和配置 git 的说明。在你的本地仓库和 GitHub 之间无缝工作之前，所有这些步骤都需要完成。

创建 pandas 的分叉

你将需要你自己的 pandas 的副本（也称为分叉）来处理代码。转到pandas 项目页面并点击Fork按钮。在选择Create Fork之前，请取消选中仅复制主分支的框。你将想要克隆你的分叉到你的机器上

git clone https://github.com/your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream

这将创建目录pandas-yourname并将你的仓库连接到上游（主项目）pandas仓库。

注意

执行浅克隆（使用–depth==N，其中N大于或等于 1）可能会导致一些测试和功能（例如pd.show_versions()）失败，因为版本号无法再计算了。

创建功能分支

你的本地main分支应始终反映出 pandas 仓库的当前状态。首先确保它与主要 pandas 仓库保持最新。

git checkout main
git pull upstream main –ff-only

然后，为进行更改创建一个功能分支。例如

git checkout -b shiny-new-feature

这将把您的工作分支从main切换到shiny-new-feature分支。保持此分支中的任何更改专注于一个错误或功能，以便清楚地了解该分支为 pandas 带来了什么。您可以拥有许多功能分支，并使用git checkout命令在它们之间切换。

当您想要在创建分支后将主分支中的更改更新到功能分支时，请查看更新 PR 部分。

进行代码更改

在修改任何代码之前，请确保遵循贡献环境指南，设置适当的开发环境。

然后一旦您进行了代码更改，您可以通过运行查看您当前所做的所有更改。

git status

对于您打算修改或添加的文件，请运行。

git add path/to/file-to-be-added-or-changed.py

再次运行git status应该显示

On branch shiny-new-feature
modified: /relative/path/to/file-to-be-added-or-changed.py

最后，使用解释性的提交消息将更改提交到您的本地存储库

git commit -m \”your commit message goes here\”
“`### 推送您的更改
当您希望您的更改在您的 GitHub 页面上公开显示时，请推送您派生的功能分支的提交
“`py
git push origin shiny-new-feature

这里origin是 GitHub 上给定给您的远程存储库的默认名称。您可以查看远程存储库

git remote -v

如果按照上述描述添加了上游存储库，您将看到类似以下内容

origin [[email protected]](/cdn-cgi/l/email-protection):yourname/pandas.git (fetch)
origin [[email protected]](/cdn-cgi/l/email-protection):yourname/pandas.git (push)
upstream git://github.com/pandas-dev/pandas.git (fetch)
upstream git://github.com/pandas-dev/pandas.git (push)

现在您的代码已经在 GitHub 上，但尚未成为 pandas 项目的一部分。为了实现这一点，需要在 GitHub 上提交一个拉取请求。

创建拉取请求

一旦完成代码更改，您的代码更改将需要遵循 pandas 贡献指南才能成功被接受。

如果一切看起来正常，您就可以准备创建一个拉取请求。拉取请求是您的本地存储库中的代码如何变为 GitHub 社区可审查并合并到项目中以出现在下一个发布中的方式。要提交拉取请求：

转到您在 GitHub 上的存储库
单击比较和拉取请求按钮
您随后可以单击Commits和Files Changed，以确保最后一次一切看起来都正常
编写一个包含前缀的描述性标题。pandas 使用标题前缀的约定。以下是一些常见的前缀以及何时使用它们的一般准则：

ENH: 增强功能，新功能BUG: 修复错误DOC: 添加/更新文档TST: 添加/更新测试BLD: 更新构建过程/脚本PERF: 性能改进TYP: 类型注解CLN: 代码清理
在预览讨论选项卡中编写更改描述
单击发送拉取请求。

然后此请求将发送给存储库维护者，他们将审查代码。

更新您的拉取请求

根据拉取请求收到的审查，你可能需要对代码进行一些更改。你可以再次遵循代码提交步骤来解决任何反馈并更新你的拉取请求。

重要的是要确保 pandas main 分支的更新反映在你的拉取请求中。要将你的特性分支与 pandas main 分支中的更改同步，运行：

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

如果没有冲突（或者它们可以自动修复），将打开一个带有默认提交消息的文件，你只需保存并退出该文件即可。

如果存在合并冲突，你需要解决这些冲突。例如，可以查看help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/，了解如何操作。

一旦冲突解决完毕，运行：

git add -u 将更新过的文件加入到暂存区；
git commit 完成合并。

注意

如果在你想要用 main 更新分支时有未提交的更改，你需要在更新之前将它们 stash 起来（参见stash 文档）。这将有效地存储你的更改，并在更新后重新应用它们。

特性分支在本地更新后，现在可以通过将分支推送到 GitHub 上的分支来更新你的拉取请求：

git push origin shiny-new-feature

任何 git push 将自动更新你的拉取请求，以反映你的分支的更改，并重新启动持续集成检查。### 更新开发环境

定期更新你的本地 main 分支以反映 pandas main 分支的更新，并更新你的开发环境以反映在开发过程中使用的各种包的任何更改是重要的。

如果使用 mamba，运行：

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml –prune

如果使用 pip，执行：

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install –upgrade -r requirements-dev.txt
“`### 版本控制，Git 和 GitHub
pandas 托管在 [GitHub](https://www.github.com/pandas-dev/pandas)，要做出贡献，你需要注册一个[免费的 GitHub 账户](https://github.com/signup/free)。我们使用 [Git](https://git-scm.com/) 进行版本控制，以便许多人可以共同在项目上工作。
如果你是 Git 的新手，你可以参考一些资源来学习 Git。如有需要，可以随时向贡献者社区寻求帮助：
+ [Git 文档](https://git-scm.com/doc)。
+ [Numpy 的 Git 资源](https://numpy.org/doc/stable/dev/gitwash/git_resources.html) 教程。
此外，项目遵循进一步在本页描述的分支工作流程，其中贡献者分叉存储库，进行更改，然后创建拉取请求。因此，请确保阅读并遵循本指南中的所有说明。
如果您是通过在 GitHub 上进行分叉来为项目做贡献的新手，请查看[GitHub 为项目做贡献的文档](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)。GitHub 提供了一个快速教程，使用一个测试存储库可能会帮助您更熟悉分叉存储库、克隆分叉、创建功能分支、推送更改和发起拉取请求。
以下是一些关于在 GitHub 上了解更多关于分叉和拉取请求的有用资源：
+ [分叉存储库的 GitHub 文档](https://docs.github.com/en/get-started/quickstart/fork-a-repo)。
+ [与拉取请求协作的 GitHub 文档](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests)。
+ [与分支协作的 GitHub 文档](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks)。
### 开始使用 Git
[GitHub 有说明](https://docs.github.com/en/get-started/quickstart/set-up-git)用于安装 git、设置您的 SSH 密钥和配置 git。在您可以在本地存储库和 GitHub 之间无缝工作之前，所有这些步骤都需要完成。
### 创建 pandas 的分支
您需要您自己的 pandas 副本（也称为分支）来处理代码。转到[pandas 项目页面](https://github.com/pandas-dev/pandas)并点击`Fork`按钮。在选择`Create Fork`之前，请取消选中仅复制主分支的框。您将需要将您的分支克隆到您的计算机上
“`py
git clone https://github.com/your-user-name/pandas.git pandas-yourname
cd pandas-yourname
git remote add upstream https://github.com/pandas-dev/pandas.git
git fetch upstream

这将创建目录pandas-yourname并将您的存储库连接到上游（主项目）pandas存储库。

注意

执行浅克隆（使用–depth==N，其中N大于或等于 1）可能会破坏一些测试和功能，因为pd.show_versions()无法再计算版本号。

创建一个功能分支

您本地的main分支应始终反映 pandas 存储库的当前状态。首先确保它与主 pandas 存储库保持最新。

git checkout main
git pull upstream main –ff-only

然后，创建一个用于进行更改的功能分支。例如

git checkout -b shiny-new-feature

这将把你的工作分支从main切换到shiny-new-feature分支。保持此分支中的任何更改专注于一个 bug 或功能，以便清楚地了解该分支为 pandas 带来了什么。您可以拥有许多功能分支，并使用git checkout命令在它们之间切换。

当您想要在创建分支后使用主分支中的更改更新功能分支时，请查看更新 PR 部分。

进行代码更改

在修改任何代码之前，请确保遵循贡献环境指南来设置适当的开发环境。

然后，一旦您进行了代码更改，您可以通过运行查看您当前所做的所有更改。

git status

对于您打算修改或添加的文件，请运行。

git add path/to/file-to-be-added-or-changed.py

再次运行git status应显示

On branch shiny-new-feature
modified: /relative/path/to/file-to-be-added-or-changed.py

最后，使用解释性的提交消息将您的更改提交到本地存储库

git commit -m \”your commit message goes here\”

推送您的更改

当您希望您的更改公开显示在您的 GitHub 页面上时，请推送您的分支的提交

git push origin shiny-new-feature

这里 origin 是 GitHub 上给您的远程存储库的默认名称。您可以看到远程存储库

git remote -v

如果像上面描述的那样添加了上游存储库，您将看到类似以下的内容

现在您的代码已经在 GitHub 上了，但它还不是 pandas 项目的一部分。为了实现这一点，需要在 GitHub 上提交一个拉取请求。

创建拉取请求

一旦您完成了代码更改，您的代码更改将需要遵循 pandas 贡献指南才能成功被接受。

如果一切看起来都很好，您就可以准备发起拉取请求。拉取请求是您的本地存储库中的代码如何变为 GitHub 社区可审查并合并到项目中以出现在下一个版本中的方式。提交拉取请求：

转到您在 GitHub 上的存储库
单击 Compare & pull request 按钮
然后，单击 Commits 和 Files Changed，确保最后一次一切正常。
写一个包含前缀的描述性标题。pandas 使用标题前缀约定。以下是一些常见的前缀以及何时使用它们的一般指南：

ENH: 增强，新功能BUG: 修复 bugDOC: 文档添加/更新TST: 测试添加/更新BLD: 构建过程/脚本的更新PERF: 性能改进TYP: 类型注释CLN: 代码清理
在 Preview Discussion 标签中写下您的更改描述
点击 Send Pull Request。

然后，此请求将发送给存储库维护者，他们将审查代码。

更新您的拉取请求

根据您在拉取请求上收到的审查，您可能需要对代码进行一些更改。您可以再次遵循提交代码的步骤来处理任何反馈并更新您的拉取请求。

pandas 的 main 分支中的更新也很重要，它们应该反映在您的拉取请求中。要使用 pandas 的 main 分支中的更改更新您的特性分支，请运行：

git checkout shiny-new-feature
git fetch upstream
git merge upstream/main

如果没有冲突（或者它们可以自动修复），将打开一个带有默认提交消息的文件，您只需保存并退出此文件即可。

如果存在合并冲突，您需要解决这些冲突。请参阅例如 help.github.com/articles/resolving-a-merge-conflict-using-the-command-line/ 了解如何做到这一点的解释。

一旦冲突解决完成，运行：

git add -u 将更新的任何文件加入到暂存区；
git commit 完成合并。

注意

如果您在想要将分支更新到main时有未提交的更改，您需要先stash这些更改（参见stash 文档）。这将有效地存储您的更改，并且它们可以在更新后重新应用。

在本地更新特性分支后，现在可以通过在 GitHub 上推送到分支来更新您的拉取请求：

git push origin shiny-new-feature

任何git push都会自动使用您的分支更改更新您的拉取请求，并重新启动持续集成检查。

更新开发环境

定期将本地main分支与 pandas 的main分支的更新同步，并更新开发环境以反映在开发过程中使用的各种包的任何更改，这一点非常重要。

如果使用 mamba，请运行：

git checkout main
git fetch upstream
git merge upstream/main
mamba activate pandas-dev
mamba env update -f environment.yml –prune

如果使用 pip，请执行：

git checkout main
git fetch upstream
git merge upstream/main
# activate the virtual environment based on your platform
python -m pip install –upgrade -r requirements-dev.txt

成功拉取请求的提示

如果您已经到达发起拉取请求阶段，其中一个核心贡献者可能会查看。但请注意，负责审查所有贡献的人可能只有少数几个，这往往会导致瓶颈。

提高您的拉取请求被审查的机会，您应该：

引用一个开放的问题来澄清 PR 的目的，以进行重要的更改
确保您有适当的测试。这些应该是任何 PR 的第一部分
尽可能简化您的拉取请求。较大的 PR 需要更长时间进行审查
确保 CI 处于绿色状态。否则，审阅者可能根本不会查看
保持更新您的拉取请求，无论是按照要求还是每隔几天

创建开发环境

原文：pandas.pydata.org/docs/development/contributing_environment.html

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

步骤 1：安装 C 编译器

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

Windows

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

注意

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

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

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

macOS

要使用基于 mamba 的编译器，您需要使用xcode-select –install安装开发人员工具。

如果您想使用其他编译器，可以在此处找到一般信息：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 Compiler Collection) 是一个广泛使用的编译器，支持 C 语言和许多其他语言。如果 GCC 列为已安装的编译器，则无需进行其他操作。

如果未安装 C 编译器，或者您希望升级，或者您使用的是其他 Linux 发行版，请参考您喜欢的搜索引擎以获取编译器安装/更新说明。

如果您遇到任何困难，请通过打开问题或在我们的贡献者社区 Slack 上联系我们。

步骤 2：创建隔离环境

在我们开始之前，请：

确保您已经克隆了存储库
cd到刚刚用克隆命令创建的 pandas 源目录

选项 1：使用 mamba（推荐）

安装 miniforge 以获取mamba
确保您的 mamba 是最新的（mamba update mamba）
使用以下命令创建并激活pandas-dev的 mamba 环境：

mamba env create –file environment.yml
mamba activate pandas-dev
“`### 选项 2：使用 pip
您需要至少具有 pandas 支持的最低 Python 版本。您还需要具有`setuptools` 51.0.0 或更高版本才能构建 pandas。
**Unix**/**macOS 使用 virtualenv**
“`py
# 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 使用.devcontainer.json文件启动与 Visual Studio Code 的远程会话，这是一个流行的免费 IDE。有关详细信息，请参阅code.visualstudio.com/docs/remote/containers。

PyCharm（专业版）

启用 Docker 支持并使用 Services 工具窗口构建和管理镜像，以及运行和与容器交互。有关详细信息，请参阅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 后端。偶尔，你会想要使用这个来调整构建目录和/或切换调试/优化级别。

你可以通过在 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进行了获取和合并，你都需要重复这一步骤。

检查构建

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

步骤 1：安装 C 编译器

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

Windows

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

注意

您无需安装 Visual Studio 2022。您只需要下载“Visual Studio 的生成工具 2022”，并在安装程序中选择“使用 C++ 进行桌面开发”工作负载。

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

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

macOS

要使用基于 mamba 的编译器，您需要使用 xcode-select –install 安装开发人员工具。

如果您希望使用其他编译器，可以在此处找到一般信息：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 源代码目录

选项 1：使用 mamba（推荐）

安装 miniforge 以获取mamba
确保您的 mamba 是最新的（mamba update mamba）
使用以下命令创建并激活 pandas-dev mamba 环境：

mamba env create –file environment.yml
mamba activate pandas-dev
“`### 选项 2：使用 pip
您至少需要安装 pandas 支持的最低 Python 版本。您还需要安装 `setuptools` 51.0.0 或更高版本来构建 pandas。
**Unix**/**macOS 使用 virtualenv**
“`py
# 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 的文档此处。

Windows

以下是在 Windows 下使用 Powershell 设置虚拟环境的简要概述。有关详细信息，请参阅官方 virtualenv 用户指南。

使用您选择的 ENV_DIR。我们将使用 ~\\\\virtualenvs\\\\pandas-dev，其中 ~ 是由 $env:USERPROFILE（Powershell）或 %USERPROFILE%（cmd.exe）环境变量指向的文件夹。任何父目录应该已经存在。

选项 3：使用 Docker

pandas 在根目录中提供了一个 DockerFile，用于构建带有完整 pandas 开发环境的 Docker 镜像。

Docker 命令

构建 Docker 镜像：

# Build the image
docker build -t pandas-dev .

运行容器：

更简单的是，您可以集成 Docker 与以下 IDE：

Visual Studio Code

您可以使用 DockerFile 使用 .devcontainer.json 文件在 Visual Studio Code 中启动远程会话，Visual Studio Code 是一款流行的免费 IDE。有关详细信息，请参阅code.visualstudio.com/docs/remote/containers。

PyCharm（专业版）

启用 Docker 支持，并使用 Services 工具窗口构建和管理镜像，以及运行和与容器交互。有关详细信息，请参阅www.jetbrains.com/help/pycharm/docker.html。

选项 4：使用 Gitpod

Gitpod 是一个开源平台，可在您的浏览器中自动创建正确的开发环境，减少安装本地开发环境和处理不兼容依赖项的需要。

如果您是 Windows 用户，不熟悉使用命令行或首次构建 pandas，则通常使用 Gitpod 更快。以下是使用 GitPod 构建 pandas 的详细说明。

选项 1：使用 mamba（推荐）

安装 miniforge 以获取mamba
确保您的 mamba 是最新的（mamba update mamba）
使用以下命令创建并激活 pandas-dev mamba 环境：

mamba env create –file environment.yml
mamba activate pandas-dev

选项 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 的文档此处。

Windows

以下是在 Windows 下使用 Powershell 设置虚拟环境的简要概述。详情请参阅官方虚拟环境用户指南。

使用你选择的 ENV_DIR。我们将使用~\\\\virtualenvs\\\\pandas-dev，其中~是由$env:USERPROFILE（Powershell）或%USERPROFILE%（cmd.exe）环境变量指向的文件夹。任何父目录都应该已经存在。

选项 3：使用 Docker

pandas 在根目录提供了一个DockerFile，用于构建具有完整 pandas 开发环境的 Docker 镜像。

Docker 命令

构建 Docker 镜像：

# Build the image
docker build -t pandas-dev .

运行容器：

更简单的是，你可以将 Docker 集成到以下 IDE 中：

Visual Studio Code

你可以使用 DockerFile 使用 .devcontainer.json 文件启动与 Visual Studio Code 的远程会话，这是一个流行的免费 IDE。详情请参阅 code.visualstudio.com/docs/remote/containers。

PyCharm（专业版）

启用 Docker 支持，并使用服务工具窗口构建和管理镜像，以及运行和与容器交互。详情请参阅 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，请运行：

注意

版本号从最新的存储库标签中提取。在构建之前，请确保从上游获取最新标签:

# 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 进行了抓取和合并，都需要重复此步骤。

检查构建

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

使用 Gitpod 进行 pandas 开发

原文：pandas.pydata.org/docs/development/contributing_gitpod.html

本文档的这一部分将指导你完成：

使用 Gitpod 进行你的 pandas 开发环境
在 GitHub 上创建一个个人分叉的 pandas 存储库
pandas 和 VSCode 的快速浏览
在 Gitpod 中工作 pandas 文档

Gitpod

Gitpod 是一个开源平台，用于自动化和准备就绪的开发环境。它使开发人员能够将他们的开发环境描述为代码，并直接从浏览器开始每个新任务的即时和新鲜的开发环境。这减少了安装本地开发环境和处理不兼容依赖关系的需要。

Gitpod GitHub 集成

要能够使用 Gitpod，你需要在你的 GitHub 帐户上安装 Gitpod 应用程序，所以如果你还没有帐户，你需要首先创建一个。

要开始使用，请在 Gitpod 登录，并授予 GitHub 适当的权限。

我们构建了一个 python 3.10 环境，并且所有开发依赖项都将在环境启动时安装。

分叉 pandas 存储库

作为贡献者在 pandas 上工作的最佳方式是首先制作存储库的分叉。

浏览到 GitHub 上的 pandas 存储库并创建你自己的分叉。
浏览到你的分叉。你的分叉将有一个类似于 noatamir/pandas-dev 的 URL，只是用你的 GitHub 用户名代替 noatamir。

启动 Gitpod

一旦你通过 GitHub 对 Gitpod 进行了身份验证，你就可以安装 Gitpod Chromium 或 Firefox 浏览器扩展程序，它将在存储库的 Code 按钮旁边添加一个 Gitpod 按钮：

如果你安装了扩展程序 – 你可以点击 Gitpod 按钮启动新的工作区。
或者，如果你不想安装浏览器扩展程序，你可以访问gitpod.io/#https://github.com/USERNAME/pandas，将USERNAME替换为你的 GitHub 用户名。
在这两种情况下，这将在你的网络浏览器中打开一个新的标签，并开始构建你的开发环境。请注意，这可能需要几分钟的时间。
构建完成后，你将被引导到你的工作区，包括 VSCode 编辑器和你在 pandas 上工作所需的所有依赖项。当你第一次启动你的工作区时，你会注意到可能有一些操作正在运行。这将确保你安装了 pandas 的开发版本。
当你的工作区准备好时，你可以通过输入来测试构建：
$ python -m pytest pandas
请注意，此命令运行时间较长，因此一旦确认正在运行，您可能希望使用 ctrl-c 取消它。

快速的工作空间导览

Gitpod 使用 VSCode 作为编辑器。如果您以前没有使用过此编辑器，则可以查看入门 VSCode 文档以熟悉它。

您的工作空间将类似于下图所示：

我们在编辑器中标记了一些重要的部分：

您当前的 Python 解释器 – 默认情况下，这是 pandas-dev，应显示在状态栏和终端上。您不需要激活 conda 环境，因为这将始终为您激活。
您当前的分支始终显示在状态栏中。您还可以使用此按钮来更改或创建分支。
GitHub 拉取请求扩展 – 您可以使用此扩展从工作空间处理拉取请求。
市场扩展 – 我们已向 pandas Gitpod 添加了一些基本扩展。但是，您还可以为自己安装其他扩展或语法突出显示主题，这些扩展将为您保留。
您的工作空间目录 – 默认情况下，它是 /workspace/pandas-dev。不要更改此目录，因为这是 Gitpod 中保留的唯一目录。

我们还预先安装了一些工具和 VSCode 扩展，以帮助开发体验：

VSCode rst 扩展
Markdown All in One
VSCode Gitlens 扩展
VSCode Git 图形扩展

通过 Gitpod 进行开发的工作流程

本文档的为 pandas 做贡献部分包含有关 pandas 开发工作流程的信息。在开始工作之前，请确保查看此内容。

使用 Gitpod 时，git 已为您预先配置：

您不需要配置 git 用户名和电子邮件，因为在通过 GitHub 进行身份验证时应已完成此操作。除非您正在使用 GitHub 功能保持电子邮件地址私密。您可以在终端中使用命令 git config –list 检查 git 配置。使用 git config –global user.email “your-secret-email@users.noreply.github.com” 将您的电子邮件地址设置为您在 github 个人资料中使用的电子邮件地址进行提交。
由于你是从自己的 pandas 分支开始工作的，默认情况下会将 upstream 和 origin 添加为远程。您可以在终端上键入 git remote 来验证此操作，或者单击状态栏上的分支名称（参见下图）。

渲染 pandas 文档

你可以在如何构建 pandas 文档部分找到有关如何使用 Sphinx 渲染文档的详细文档。要构建完整的文档，你需要在/doc目录中运行以下命令：

$ cd doc
$ python make.py html

或者你可以构建一个单页，使用：

python make.py –single development/contributing_gitpod.rst

在 Gitpod 中，你有两个主要选项来渲染文档。

选项 1：使用 Liveserve

在pandas/doc/build/html中查看文档。
要查看页面的渲染版本，你可以右键点击.html文件，然后点击使用 Live Serve 打开。另外，你也可以在编辑器中打开文件，然后点击状态栏上的Go live按钮。

一个简单的浏览器将会在编辑器的右侧打开。我们建议关闭它，然后点击弹出窗口中的在浏览器中打开按钮。
要停止服务器，请点击状态栏上的端口：5500按钮。

选项 2：使用 rst 扩展

一个快速简便的方法来在你编辑.rst文件时查看实时更改，就是使用 docutils 的 rst 扩展。

注意

这将生成一个简单的文档实时预览，没有html主题，有些反向链接可能不会被正确添加。但这是一个轻松和简便的方式来即时获取你的工作反馈，而不需要构建 html 文件。

在编辑器中打开位于doc/source中的任何源文档文件。
在 Mac 上使用Cmd`-`Shift`-`P或在 Linux 和 Windows 上使用Ctrl`-`Shift`-`P打开 VSCode 命令面板。开始输入“restructured”，然后选择“打开预览”或“打开侧边预览”。

当你编辑文档时，你会在编辑器上看到实时渲染。

如果你想要看到带有html主题的最终输出，你需��使用make html重新构建文档，并按照选项 1 中描述的使用 Live Serve。

常见问题和故障排除

我的 Gitpod 工作区会被保留多久？

如果你不使用，你停止的工作区将会保留 14 天，之后将会被删除。

我可以回到之前的工作区吗？

是的，假设你离开一段时间，想继续在你的 pandas 贡献上工作。你需要访问gitpod.io/workspaces，然后点击你想要重新启动的工作区。你的所有更改将会保留，就像你上次离开的那样。

我可以安装额外的 VSCode 扩展吗？

当然！你安装的任何扩展都将被安装在你自己的工作区中并得到保留。

我在 Gitpod 上注册了，但我仍然看不到我的存储库中的Gitpod按钮。

前往 gitpod.io/integrations 并确保您已登录。将鼠标悬停在 GitHub 上，然后单击右侧出现的三个按钮。单击编辑权限，确保您已选中 user:email、read:user 和 public_repo。单击更新权限并在 GitHub 应用页面上确认更改。

如果我不使用工作区，它会保持活动多长时间？

如果您在浏览器选项卡中保持工作区处于打开状态但不与其交互，它将在 30 分钟后关闭。如果关闭浏览器选项卡，它将在 3 分钟后关闭。

我的终端是空白的 – 没有光标，完全没有响应

不幸的是，这是 Gitpod 方面已知的问题。您可以通过两种方式解决此问题：

新建一个全新的 Gitpod 工作区。
前往您的 Gitpod 仪表板并找到正在运行的工作区。将鼠标悬停在其上，然后单击三个点菜单，然后单击停止。当工作区完全停止时，您可以单击其名称重新启动它。

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到仓库。

前往 gitpod.io/integrations 并确保您已登录。将鼠标悬停在 GitHub 上，然后单击右侧出现的三个按钮。单击编辑权限，确保您已选中 public_repo。单击更新权限并在 GitHub 应用页面上确认更改。

致谢

此页面是从 NumPy 项目轻微调整的。

Gitpod

Gitpod 是一个用于自动化和即用即开发的开源平台，它使开发人员能够将他们的开发环境描述为代码，并直接从浏览器为每个新任务启动即时而新鲜的开发环境。这减少了安装本地开发环境和处理不兼容依赖项的需求。

Gitpod GitHub 集成

要使用 Gitpod，您需要在 GitHub 帐户上安装 Gitpod 应用程序，因此，如果您尚未拥有帐户，则需要首先创建一个。

要开始工作，只需在 Gitpod 登录，并为 GitHub 授予适当的权限。

我们已构建了一个 Python 3.10 环境，并且所有开发依赖项都将在环境启动时安装。

创建 pandas 仓库的分支

作为贡献者工作 pandas 的最佳方式是首先创建该仓库的分支。

浏览到GitHub 上的 pandas 存储库并创建你自己的分支。
浏览到你的分支。你的分支将有一个类似于noatamir/pandas-dev的 URL，只是将noatamir替换为你的 GitHub 用户名。

启动 Gitpod

一旦通过 GitHub 在 Gitpod 上进行了身份验证，你可以安装Gitpod Chromium 或 Firefox 浏览器扩展，它将在存储库中的Code按钮旁边添加一个Gitpod按钮：

如果你安装了扩展 – 你可以点击Gitpod按钮启动一个新的工作空间。
或者，如果你不想安装浏览器扩展，你可以访问gitpod.io/#https://github.com/USERNAME/pandas，将USERNAME替换为你的 GitHub 用户名。
在这两种情况下，这将在你的网络浏览器上打开一个新标签页并开始构建你的开发环境。请注意，这可能需要几分钟。
一旦构建完成，你将被引导到你的工作空间，包括 VSCode 编辑器和你在 pandas 上工作所需的所有依赖项。第一次启动工作空间时，你��注意到可能有一些操作正在运行。这将确保你安装了 pandas 的开发版本。
当你的工作空间准备好后，你可以通过输入以下内容来测试构建：
$ python -m pytest pandas
请注意，这个命令运行起来需要一段时间，所以一旦确认它正在运行，你可能想要使用 ctrl-c 取消它。

快速工作空间导览

Gitpod 使用 VSCode 作为编辑器。如果你以前没有使用过这个编辑器，你可以查看VSCode 文档来熟悉它。

你的工作空间将类似于下面的图片：

我们在编辑器中标记了一些重要部分：

你当前的 Python 解释器 – 默认情况下是pandas-dev，应该显示在状态栏和终端上。你不需要激活 conda 环境，因为这将始终为你激活。
你当前的分支始终显示在状态栏中。你也可以使用这个按钮来更改或创建分支。
GitHub 拉取请求扩展 – 你可以使用这个扩展来处理来自工作空间的拉取请求。
Marketplace 扩展 – 我们已经为 pandas Gitpod 添加了一些必要的扩展。但是，你也可以安装其他扩展或语法高亮主题供你使用，并且这些将为你保留。
你的工作空间目录 – 默认情况下是/workspace/pandas-dev。请不要更改，因为这是 Gitpod 中唯一保留的目录。

我们还预先安装了一些工具和 VSCode 扩展以帮助开发体验：

VSCode rst 扩展
Markdown All in One
VSCode Gitlens 扩展
VSCode Git 图表扩展

使用 Gitpod 的开发工作流程

本文档的贡献给 pandas 部分包含有关 pandas 开发工作流程的信息。在开始贡献之前，请务必查阅此内容。

在使用 Gitpod 时，git 已经为您预先配置好：

您不需要配置 git 用户名和电子邮件，因为在您通过 GitHub 进行身份验证时应该已经为您完成了此操作。除非您使用 GitHub 功能保持电子邮件地址私密。您可以在终端中使用命令 git config –list 检查 git 配置。使用 git config –global user.email “your-secret-email@users.noreply.github.com” 命令将您的电子邮件地址设置为您在 github 个人资料中用于提交的地址。
由于您从自己的 pandas 分支启动了工作空间，默认情况下会将upstream和origin添加为远程。您可以在终端上键入 git remote 或点击状态栏上的branch name（见下图）来验证这一点。

渲染 pandas 文档

您可以在如何构建 pandas 文档部分找到有关使用 Sphinx 渲染文档的详细文档。要构建完整的文档，您需要在 /doc 目录中运行以下命令：

$ cd doc
$ python make.py html

或者，您可以构建单个页面：

python make.py –single development/contributing_gitpod.rst

在 Gitpod 中呈现文档有两种主要选项。

选项 1：使用 Live Serve

查看位于 pandas/doc/build/html 中的文档。
要查看页面的渲染版本，您可以右键单击 .html 文件，然后单击Open with Live Serve。或者，您可以在编辑器中打开文件，然后单击状态栏上的Go live按钮。

简单的浏览器将会在编辑器的右侧打开。我们建议将其关闭，并单击弹出窗口中的Open in browser按钮。
要停止服务器，请点击状态栏上的Port: 5500按钮。

选项 2：使用 rst 扩展

在您编辑 .rst 文件时，快速且方便地查看实时更改的方法是使用带有 docutils 的 rst 扩展。

注意

这将生成一个简单的文档实时预览，不使用html主题，有些反向链接可能添加不正确。但这是一个轻松和轻量级的方式，可以即时获得对你的工作的反馈，而无需构建 html 文件。

在编辑器中打开位于doc/source中的任何源文档文件。
在 Mac 上使用Cmd`-`Shift`-`P或在 Linux 和 Windows 上使用Ctrl`-`Shift`-`P打开 VSCode 命令面板。开始输入“restructured”，然后选择“打开预览”或“打开侧边栏预览”。

当你在文档上工作时，你会在编辑器上看到实时渲染。

如果你想看到带有html主题的最终输出，你需要使用make html重新构建文档，并按照选项 1 中描述的使用 Live Serve。

选项 1：使用 Live Serve

在pandas/doc/build/html中查看文档。
要查看页面的渲染版本，你可以右键点击.html文件，然后点击使用 Live Serve 打开。或者，你可以在编辑器中打开文件，然后点击状态栏上的Go live按钮。

一个简单的浏览器将在编辑器的右侧打开。我们建议关闭它，然后点击弹出窗口中的在浏览器中打开按钮。
要停止服务器，请点击状态栏上的端口：5500按钮。

选项 2：使用 rst 扩展

一个快速简单的方法，可以在你编辑.rst文件时看到实时更改，使用带有 docutils 的 rst 扩展。

注意

当你在文档上工作时，你会在编辑器上看到实时渲染。

如果你想看到带有html主题的最终输出，你需要使用make html重新构建文档，并按照选项 1 中描述的使用 Live Serve。

常见问题和故障排除

我的 Gitpod 工作区会保留多久��

你停止的工作区将保留 14 天，如果你不使用它们，之后将被删除。

我可以回到以前的工作区吗？

是的，比如你离开一段时间，想要继续在你的 pandas 贡献上工作。你需要访问gitpod.io/workspaces，然后点击你想要重新启动的工作空间。你的所有更改将和你上次离开的状态一样。

我可以安装额外的 VSCode 扩展吗？

当然可以！你安装的任何扩展都将安装在你自己的工作空间中并得以保留。

我在 Gitpod 上注册了，但仍然看不到我的存储库中的Gitpod按钮。

前往gitpod.io/integrations，确保你已经登录。悬停在 GitHub 上，点击右侧出现的三个按钮。点击编辑权限，确保你勾选了user:email，read:user和public_repo。点击更新权限，并在 GitHub 应用页面确认更改。

如果我不使用工作空间，它会保持活动多长时间？

如果你在浏览器标签页中保持工作空间打开但没有与其交互，它将在 30 分钟后关闭。如果你关闭了浏览器标签页，它将在 3 分钟后关闭。

我的终端是空白的 – 没有光标，完全没有反应。

不幸的是，这是 Gitpod 方面已知的问题。你可以通过两种方式解决这个问题：

创建一个全新的 Gitpod 工作空间。
前往你的Gitpod 仪表板，找到正在运行的工作空间。悬停在其上，然后点击三个点的菜单，然后点击停止。当工作空间完全停止后，你可以点击其名称重新启动它。

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到存储库。

前往gitpod.io/integrations，确保你已经登录。悬停在 GitHub 上，点击右侧出现的三个按钮。点击编辑权限，确保你勾选了public_repo。点击更新权限，并在 GitHub 应用页面确认更改。

我的 Gitpod 工作空间保留多久？

你停止的工作空间将保留 14 天，如果你不使用它们，将在此之后删除。

我可以返回之前的工作空间吗？

我可以安装额外的 VSCode 扩展吗？

当然可以！你安装的任何扩展都将安装在你自己的工作空间中并得以保留。

我在 Gitpod 上注册了，但仍然看不到我的存储库中的Gitpod按钮。

前往gitpod.io/integrations，确保已登录。将鼠标悬停在 GitHub 上，然后单击右侧出现的三个按钮。单击编辑权限，并确保已选中user:email、read:user和public_repo。单击更新权限，并在 GitHub 应用页面上确认更改。

如果我不使用工作区，它会保持活动多长时间？

如果你将工作区保持在浏览器选项卡中打开但不与其交互，它将在 30 分钟后关闭。如果关闭浏览器选项卡，则在 3 分钟后关闭。

我的终端是空白的 – 没有光标，完全没有响应

不幸的是，这是 Gitpod 方面已知的问题。你可以通过两种方式解决此问题：

创建一个全新的 Gitpod 工作区。
前往你的Gitpod 仪表板，找到正在运行的工作区。将鼠标悬停在其上，然后点击三个点菜单，然后点击停止。当工作区完全停止后，你可以点击其名称重新启动它。

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到存储库。

前往gitpod.io/integrations，确保已登录。将鼠标悬停在 GitHub 上，然后单击右侧出现的三个按钮。单击编辑权限，并确保已选中public_repo。单击更新权限，并在 GitHub 应用页面上确认更改。

致谢

本页面轻微改编自NumPy项目。
我可以安装额外的 VSCode 扩展吗？

当然可以！你安装的任何扩展都将安装在你自己的工作空间中并得以保留。

我在 Gitpod 上注册了，但仍然看不到我的存储库中的Gitpod按钮。

[外链图片转存中…(img-RfkbipU2-1719541743765)]

如果我不使用工作空间，它会保持活动多长时间？

如果你在浏览器标签页中保持工作空间打开但没有与其交互，它将在 30 分钟后关闭。如果你关闭了浏览器标签页，它将在 3 分钟后关闭。

我的终端是空白的 – 没有光标，完全没有反应。

不幸的是，这是 Gitpod 方面已知的问题。你可以通过两种方式解决这个问题：

[外链图片转存中…(img-PVrqRTjB-1719541743765)]

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到存储库。

[外链图片转存中…(img-QNlF0EM2-1719541743766)]

我的 Gitpod 工作空间保留多久？

你停止的工作空间将保留 14 天，如果你不使用它们，将在此之后删除。

我可以返回之前的工作空间吗？

我可以安装额外的 VSCode 扩展吗？

当然可以！你安装的任何扩展都将安装在你自己的工作空间中并得以保留。

我在 Gitpod 上注册了，但仍然看不到我的存储库中的Gitpod按钮。

[外链图片转存中…(img-qlx9XIZc-1719541743766)]

如果我不使用工作区，它会保持活动多长时间？

如果你将工作区保持在浏览器选项卡中打开但不与其交互，它将在 30 分钟后关闭。如果关闭浏览器选项卡，则在 3 分钟后关闭。

我的终端是空白的 – 没有光标，完全没有响应

不幸的是，这是 Gitpod 方面已知的问题。你可以通过两种方式解决此问题：

[外链图片转存中…(img-kciUheTU-1719541743766)]

我通过 GitHub 进行了身份验证，但仍然无法通过 Gitpod 提交到存储库。

[外链图片转存中…(img-DV0ojfIc-1719541743766)]

致谢

本页面轻微改编自NumPy项目。

#以上关于Pandas 2.2 中文文档（八十）的相关内容来源网络仅供参考，相关信息请以官方公告为准！

原创文章，作者：CSDN，如若转载，请注明出处：https://www.sudun.com/ask/92705.html