Contributing to pandas¶

Where to start?¶

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

如果您只是想开始使用pandas代码库，请导航到GitHub“问题”标签，开始查找有趣的问题。在您可以开始使用的文档和难度新手下列出了一些问题。

或者也许通过使用pandas你有自己的想法或正在寻找文档中的东西，并认为'这可以改进'...你可以做点什么！

随时可以在邮寄名单或Gitter上提问。

Bug reports and enhancement requests ¶

错误报告是使pandas更稳定的重要部分。有一个完整的错误报告将允许其他人再现错误，并提供洞察修复。由于支持许多版本的pandas，因此知道版本信息也将标识自以前版本以来的改进。尝试在主分支上生成错误代码通常是一个值得做的练习，以确认该错误仍然存在。它也值得搜索现有的错误报告和拉请求，以查看该问题是否已经报告和/或修复。

错误报告必须：

包含一个简短的自包含的Python代码段，用于重现问题。您可以使用GitHub Flavored Markdown来格式化代码：
```
```python
>>> from pandas import DataFrame
>>> df = DataFrame(...)
...
```
```
包括pandas的完整版本字符串及其依赖项。在pandas的版本0.12之后，您可以使用内置函数：
```
>>> from pandas.util.print_versions import show_versions
>>> show_versions()
```
和pandas中0.13.1及以上：
```
>>> pd.show_versions()
```
解释当前行为为什么是错误/不需要和你期望的结果是什么。

然后问题会显示给pandas社区，其他人可以看到并提供想法/评论。

Working with the code ¶

现在您有一个您想要修复的问题，要添加的增强功能或文档，您需要了解如何使用GitHub和pandas代码库。

Version control, Git, and GitHub ¶

对于新用户，使用Git是促成pandas的更强大的方面之一。它可以很快拥有压倒性优势，但坚持下面的指导方针将有助于保持过程简单，大多是无故障。一如既往，如果你有困难，请随时要求帮助。

代码托管在GitHub上。要提供资料，您需要注册一个免费的GitHub帐户。我们使用Git进行版本控制，允许许多人在项目上一起工作。

一些伟大的资源学习Git：

GitHub帮助页。
NumPy的文档。
Matthew Brett的Pydagogue。

Getting started with Git ¶

GitHub有指示用于安装git，设置SSH密钥和配置git。所有这些步骤需要完成，然后才能在本地存储库和GitHub之间无缝工作。

Forking ¶

你将需要你自己的fork来处理代码。转到pandas项目页，然后点击Fork按钮。你会想要克隆你的叉子到你的机器：

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

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

在提交拉取请求后，测试套件将在Travis-CI上自动运行。但是，如果您希望在提交pull请求之前在分支上运行测试套件，则需要将Travis-CI连接到您的GitHub存储库。这样做的说明是这里。

Creating a branch ¶

您希望您的主分支仅反映生产就绪代码，因此创建功能分支以进行更改。例如：

git branch shiny-new-feature
git checkout shiny-new-feature

以上可以简化为：

git checkout -b shiny-new-feature

这将您的工作目录更改为闪亮的新功能分支。Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to pandas. 你可以有许多闪亮的新功能，并使用git checkout命令在它们之间切换。

要更新此分支，您需要从主分支检索更改：

git fetch upstream
git rebase upstream/master

这将重播你的提交在最新的熊猫git master。如果这导致合并冲突，您必须在提交您的拉取请求之前解决这些冲突。如果您有未提交的更改，则需要在更新之前stash。这将有效地存储您的更改，他们可以在更新后重新应用。

Creating a development environment ¶

创建pandas开发环境的简单方法如下。

安装Anaconda或miniconda
请确保您已cloned the repository
cd到pandas源目录

通过运行以下命令，让conda创建一个名为pandas_dev的新环境或任何其他名称：

conda create -n pandas_dev --file ci/requirements_dev.txt

对于python 3环境：

conda create -n pandas_dev python=3 --file ci/requirements_dev.txt

警告

如果您使用Windows，请参阅here for a fully compliant Windows environment。

这将创建新的环境，而不是触摸任何现有的环境，也没有任何现有的python安装。它将安装pandas的所有基本依赖项，以及开发和测试工具。如果要安装其他依赖项，可以按如下所示安装它们：

conda install -n pandas_dev -c pandas pytables scipy

要安装所有 pandas依赖项，您可以执行以下操作：

conda install -n pandas_dev -c pandas --file ci/requirements_all.txt

要在此环境中工作，Windows用户应activate，如下所示：

activate pandas_dev

Mac OSX / Linux用户应该使用：

source activate pandas_dev

然后，您将看到一条确认消息，表明您处于新的开发环境中。

要查看您的环境：

conda info -e

要在Windows中返回到主页根环境：

deactivate

在OSX / Linux中返回到您的主根环境：

source deactivate

请参阅完整的条件文档此处。

此时，您可以轻松地执行就地安装，如下一节所述。

Creating a Windows development environment ¶

如果基于Windows系统，您需要安装编译器来构建安装环境。您将需要安装相应的Visual Studio编译器，VS 2008 for Python 2.7，VS 2010 for 3.4和VS 2015 for Python 3.5。

对于Python 2.7，您可以安装mingw编译器，它将等效于VS 2008：

conda install -n pandas_dev libpython

或使用Microsoft Visual Studio VC ++编译器Python。请注意，您必须检查x64框以安装x64扩展构建功能，因为默认情况下未安装。

对于Python 3.4，您可以下载并安装Windows 7.1 SDK。阅读下面的参考文件，因为在安装过程中可能会有各种各样的困难。

对于Python 3.5，您可以下载并安装Visual Studio 2015社区版。

这里有一些参考和博客：

Making changes ¶

在更改代码之前，通常需要构建刚刚签出的代码。有两种主要的方法。

开发pandas的最佳方式是通过运行以下命令来构建C扩展：
```
python setup.py build_ext --inplace
```
如果您在pandas源目录中启动Python解释器，您将调用构建的C扩展
另一个非常常见的选择是执行pandas的develop安装：
```
python setup.py develop
```
这使得一个符号链接告诉Python解释器从你的开发目录中导入pandas。因此，您可以始终在您的系统上使用开发版本，而不必在克隆目录中。

Contributing to the documentation ¶

如果你不是专门开发人员，贡献文档仍然是巨大的价值。你甚至不必成为pandas的专家！像参考文档一样，为了清晰起见，重写小段落是一种简单但有效的方法。下一个用户读这部分内容的人会在你的贡献的基础上！

事实上，文档的一些部分，在专家写的后更糟糕。如果文档中的某些东西对你说没有完全弄清楚，在你弄清楚之后再更新相关部分是一个必要的方法，以确保它将帮助下一个人。

文档：

关于pandas文档
如何构建pandas文档

About the pandas documentation ¶

该文档用reStructuredText编写，这几乎就像用纯英语书写，并使用Sphinx构建。Sphinx文档对reST有一个很好的介绍。查看Sphinx文档以对文档执行更复杂的更改。

关于文档的一些其他重要的事情：

pandas文档由两部分组成：代码本身中的docstrings和此文件夹中的文档pandas/doc/。

docstrings提供了对各个功能的使用的清楚解释，而此文件夹中的文档包括每个主题的教程式概述以及一些其他信息（新增内容，安装等）。
docstrings遵循Numpy Docstring Standard，在科学Python社区中广泛使用。这个标准规定了docstring的不同部分的格式。有关详细说明，请参阅本文档，或者查看一些现有函数以类似方式扩展它。
本教程大量使用ipython指令 sphinx扩展。此指令允许您将代码放在将在doc构建期间运行的文档中。例如：
```
.. ipython:: python

    x = 2
    x**3
```
将呈现为：
```
In [1]: x = 2

In [2]: x**3
Out[2]: 8
```
在doc构建过程中，几乎所有的代码示例都会运行（并保存输出）。这种方法意味着代码示例将始终是最新的，但它确实使doc构建更复杂。

注意

.rst文件用于自动生成文档的Markdown和HTML版本。因此，请不要直接编辑CONTRIBUTING.md，而应对doc/source/contributing.rst进行任何更改。然后，要生成CONTRIBUTING.md，请使用以下命令使用pandoc：

pandoc doc/source/contributing.rst -t markdown_github > CONTRIBUTING.md

实用程序脚本scripts/api_rst_coverage.py可用于比较doc/source/api.rst中记录的方法列表（用于生成API参考页面）和实际的公共方法。这将识别doc/source/api.rst中记录的方法，这些方法实际上不是类方法，以及在doc/source/api.rst中没有记录的现有方法。。

How to build the pandas documentation ¶

首先，您需要有一个开发环境，以便能够构建pandas（请参阅creating a development environment above）。此外，要构建文档，还有一些额外的要求：您需要安装sphinx和ipython。numpydoc用于解析Numpy Docstring Standard（见上文）后面的文档字符串，但不需要安装，因为numpydoc的本地副本包含在pandas 源代码。nbconvert和nbformat是构建文档中包含的Jupyter笔记本所必需的。

如果您有名为pandas_dev的conda环境，则可以使用以下命令安装额外的需求：

conda install -n pandas_dev sphinx ipython nbconvert nbformat

此外，建议所有optional dependencies。安装。这不是绝对必要的，但请注意，您在构建文档时会看到一些错误消息。这是因为文档中的所有代码都是在doc构建期间执行的，因此使用可选依赖关系的代码示例会生成错误。运行pd.show_versions()可获取所有依赖项的已安装版本的概述。

警告

您需要具有sphinx version> = 1.3.2。

Building the documentation ¶

那么如何构建文档呢？在控制台中导航到您当地的pandas/doc/目录，然后运行：

python make.py html

然后，您可以在文件夹pandas/doc/build/html/中找到HTML输出。

第一次构建文档时，将需要一段时间，因为它必须运行所有代码示例并构建所有生成的docstring页面。在后续的调用中，sphinx将尝试仅构建已修改的页面。

如果你想做一个完全干净的构建，做：

python make.py clean
python make.py build

从pandas 0.13.1开始，您可以告诉make.py只编译文档的一个部分，大大缩短了检查更改的周转时间。系统将提示您删除不需要的.rst文件。这是好的，因为这些文件的先前版本可以从git检出。但是，您必须确保不将文件删除提交到您的Git存储库！

#omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single
# section, that which is in indexing.rst
python make.py clean
python make.py --single indexing

为了比较，完整的文档构建可能需要10分钟，-no-api构建可能需要3分钟，单个节可能需要15秒。后续构建（仅处理已更改的部分）将更快。在Web浏览器中打开以下文件，以查看刚刚构建的完整文档：

pandas/docs/build/html/index.html

你会看到你的新的和改进的文档的满意！

Building master branch documentation ¶

当pull请求合并到pandas master分支中时，文档的主要部分也由Travis-CI构建。这些文档随后托管在此处。

Contributing to the code base ¶

代码库：

代码标准
测试驱动开发/代码编写
记录您的代码

Code standards ¶

pandas使用PEP8标准。有几个工具，以确保您遵守此标准。这是一些的更常见的PEP8问题：

我们将行长度限制为80个字符以提高可读性

传递参数应该在逗号后面有空格，例如。 foo（arg1， arg2， kw1 ='bar'）

Travis-CI将运行flake8工具，并报告代码中的任何文体错误。生成任何警告将导致构建失败；因此这些是向pandas提交代码的要求的一部分。

在提交代码以在diff上运行它是有帮助的：

git diff master | flake8 --diff

此外，我们编写了一个工具来检查您的提交是否为PEP8，pip install pep8radius。看看PEP8修复在你的分支vs主人：

pep8radius master --diff

并进行以下更改：

pep8radius master --diff --in-place

其他标准在代码样式wiki页面中列出。

请尝试保持向后兼容性。pandas有很多用户有很多现有的代码，所以不要打破它，如果可能的话。如果你认为需要破解，清楚地说明为什么作为pull请求的一部分。此外，在更改方法签名并在需要时添加弃用警告时要小心。

Test-driven development/code writing ¶

pandas是认真的测试，并强烈鼓励贡献者拥抱测试驱动开发（TDD）。这个开发过程“依赖于重复一个非常短的开发周期：首先，开发人员编写一个（最初失败的）自动化测试用例，定义一个所需的改进或新的函数，然后产生最小量的代码通过该测试。，在实际写任何代码之前，你应该写你的测试。通常测试可以从原来的GitHub问题。但是，它总是值得考虑额外的用例和编写相应的测试。

添加测试是代码推送到pandas之后最常见的请求之一。因此，值得习惯于提前写测试，所以这从来不是一个问题。

像许多软件包一样，pandas使用鼻子测试系统和numpy.testing中的方便扩展。

Writing tests ¶

所有测试都应该进入特定软件包的tests子目录。此文件夹包含许多当前的测试示例，我们建议寻找这些灵感。如果您的测试需要处理文件或网络连接，则有关维基的测试页的更多信息。

pandas.util.testing模块有许多特殊的assert函数，可以更容易地说明Series或DataFrame对象是否是等价的。验证代码是否正确的最简单方法是显式构造期望的结果，然后将实际结果与预期的正确结果进行比较：

def test_pivot(self):
    data = {
        'index' : ['A', 'B', 'C', 'C', 'B', 'A'],
        'columns' : ['One', 'One', 'One', 'Two', 'Two', 'Two'],
        'values' : [1., 2., 3., 3., 2., 1.]
    }

    frame = DataFrame(data)
    pivoted = frame.pivot(index='index', columns='columns', values='values')

    expected = DataFrame({
        'One' : {'A' : 1., 'B' : 2., 'C' : 3.},
        'Two' : {'A' : 1., 'B' : 2., 'C' : 3.}
    })

    assert_frame_equal(pivoted, expected)

Running the test suite ¶

然后可以直接在您的Git克隆中运行测试（无需安装pandas）：

nosetests pandas

测试套件是详尽的，需要大约20分钟运行。通常，在运行整个套件之前，首先应围绕您的更改运行一部分测试。这是使用以下结构之一完成的：

  nosetests pandas/tests/[test-module].py
  nosetests pandas/tests/[test-module].py:[TestClass]
  nosetests pandas/tests/[test-module].py:[TestClass].[test_method]

.. versionadded:: 0.18.0

此外，可以运行

pd.test()

与一个导入的熊猫类似地运行测试。

Running the performance test suite ¶

性能很重要，值得考虑你的代码是否引入了性能回归。pandas正在迁移到asv基准，以便轻松监控关键pandas操作的性能。这些基准都在pandas/asv_bench目录中找到。asv支持python2和python3。

注意

asv基准套件是从以前的框架vbench中翻译出来的，所以很多风格问题都可能是代码自动转换的结果。

要使用asv的所有功能，您需要conda或virtualenv。有关详细信息，请查看asv安装网页。

要安装asv：

pip install git+https://github.com/spacetelescope/asv

如果您需要运行基准测试，请将您的目录更改为asv_bench/并运行：

asv continuous -f 1.1 upstream/master HEAD

您可以将HEAD替换为您正在使用的分支的名称，并报告更改超过10％的基准。该命令默认使用conda创建基准环境。如果要使用virtualenv，请写：

asv continuous -f 1.1 -E virtualenv upstream/master HEAD

应该将-E virtualenv选项添加到运行基准测试的所有asv命令。默认值在asv.conf.json中定义。

运行完整的测试套件可能需要长达一个小时，最多使用3GB的RAM。通常只需将一部分结果粘贴到pull请求中即可，以表明提交的更改不会导致意外的性能回退。您可以使用-b标志运行特定的基准，该标志采用正则表达式。例如，这将只运行来自pandas/asv_bench/benchmarks/groupby.py文件的测试：

asv continuous -f 1.1 upstream/master HEAD -b ^groupby

如果您只想从文件中运行特定的测试组，可以使用.作为分离器。例如：

asv continuous -f 1.1 upstream/master HEAD -b groupby.groupby_agg_builtins

将只运行groupby.py中定义的groupby_agg_builtins基准。

您还可以使用已安装在当前Python环境中的pandas版本运行基准套件。如果您没有virtualenv或conda，或正在使用上面讨论的setup.py 开发方法，对于就地构建，您需要设置PYTHONPATH，例如PYTHONPATH =“$ PWD /.." asv [remaining arguments]。您可以使用现有的Python环境通过以下方式运行基准：

asv run -e -E existing

或者，使用一个特定的Python解释器：

asv run -e -E existing:python3.5

这将从基准显示stderr，并使用来自您的$PATH的本地python。

有关如何编写基准和如何使用asv的信息，请参见asv文档。

Running Google BigQuery Integration Tests ¶

您需要创建JSON格式的Google BigQuery私钥，才能在本地计算机和Travis-CI上运行Google BigQuery集成测试。第一步是创建服务帐户。

在pull请求中跳过pandas.io.gbq的集成测试，因为运行Google BigQuery集成测试所需的凭据在Travis-CI上加密，只能从pandas-dev / pandas存储库。凭证将不可用于大熊猫的大熊猫。以下是在分支存储库上运行gbq集成测试的步骤：

转到Travis CI并使用您的GitHub帐户登录。
点击我的存储库列表旁边的+图标，然后为您的分支启用Travis构建。
点击齿轮图标编辑您的travis构建，并添加两个环境变量：
- GBQ_PROJECT_ID，其值为您的BigQuery项目的ID。
- SERVICE_ACCOUNT_KEY，其值为您为服务帐户下载的JSON密钥的内容。在JSON密钥周围使用单引号，以确保它被视为字符串。
对于这两个环境变量，保持“在构建日志中显示值”选项DISABLED。这些变量包含敏感数据，您不希望其内容在构建日志中显示。
您的分支应在推送后自动测试。您可以通过访问位于以下位置的Travis分支页检查状态：https://travis-ci.org/your-user-name/pandas/branches。单击您的分支的构建作业。展开构建日志中的以下行：ci / print_skipped.py /tmp/nosetests.xml。搜索术语test_gbq并确认不会跳过gbq集成测试。

Running the vbench performance test suite (phasing out)¶

历史上，pandas使用vbench库，以便轻松监视关键pandas操作的性能。这些基准都在pandas/vb_suite目录中找到。vbench目前只适用于python2。

安装vbench：

pip install git+https://github.com/pydata/vbench

Vbench还需要sqlalchemy，gitpython和psutil，都可以使用pip安装。如果您需要运行基准测试，请将目录更改为pandas root并运行：

./test_perf.sh -b master -t HEAD

这将检出主修订版并在主服务器和您的提交上运行套件。运行完整的测试套件可能需要长达一个小时，最多使用3GB的RAM。通常，将一个子集的结果粘贴到合并请求中就足以表明提交的更改不会导致意外的性能回退。

您可以使用带有正则表达式的-r标志运行特定的基准测试。

有关如何编写基准的信息，请参阅性能测试wiki。

Documenting your code ¶

更改应反映在位于doc/source/whatsnew/vx.y.z.txt中的发行说明中。此文件包含每个发行版的正在进行的更改日志。向此文件添加条目以记录您的修复，增强或（不可避免的）中断更改。添加条目时，请务必包含GitHub问题编号（使用``GH1234``其中1234是问题/拉取请求编号）。

如果您的代码是增强功能，则很可能需要在现有文档中添加使用示例。这可以按照above部分进行。此外，为了让用户知道添加此功能的时间，使用versionadded指令。sphinx语法是：

.. versionadded:: 0.17.0

这将把文本新的版本0.17.0放置sphinx指令。当添加新的函数或方法（示例）或新的关键字参数（示例）时，也应将其放在docstring中。

Contributing your changes to pandas¶

Committing your code ¶

保持样式修复一个单独的提交，使您的拉取请求更加可读。

完成更改后，您可以键入以下内容查看这些更改：

git status

如果你创建了一个新文件，它不是由git跟踪。通过键入以下内容添加：

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

做'git status'应该给出像：

# On branch shiny-new-feature
#
#       modified:   /relative/path/to/file-you-added.py
#

最后，使用解释性消息将更改提交到本地存储库。Pandas使用提交消息前缀和布局的约定。以下是一些常见的前缀以及何时使用它们的一般准则：

ENH：增强，新功能

BUG：错误修复

DOC：文档的添加/更新

TST：测试的添加/更新

BLD：更新构建过程/脚本

PERF：性能改进

CLN：代码清理

以下定义如何构造提交消息。请使用GH1234或＃1234在提交消息中引用相关的GitHub问题。任何一种风格都很好，但前者通常是首选：

主题行具有80 chars。

一个空白行。

（可选）提交消息体。

现在，您可以在本地存储库中提交更改：

git commit -m

Combining commits ¶

如果你有多个提交，你可能想把它们合并成一个提交，通常被称为“压缩”或“rebasing”。这是包维护者在提交拉取请求时的常见请求，因为它维护了更紧凑的提交历史。要重命名您的提交：

git rebase -i HEAD~#

其中＃是要组合的提交数。然后你可以选择相关的提交消息并丢弃其他。

要压缩到主分支：

git rebase -i master

Use the s option on a commit to squash, meaning to keep the commit messages, or f to fixup, meaning to merge the commit messages.

然后，您将需要强行推动分支（见下文）以用新的替换当前提交：

git push origin shiny-new-feature -f

Pushing your changes ¶

当您希望您的更改公开显示在您的GitHub页面上时，推送您的分叉功能部分的提交：

git push origin shiny-new-feature

这里origin是GitHub上远程仓库的默认名称。你可以看到远程仓库：

git remote -v

如果你按上面所述添加了上游仓库，你会看到：

origin  git@github.com:yourname/pandas.git (fetch)
origin  git@github.com: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上提交拉取请求。

Review your code ¶

当您准备要求进行代码审核时，请提交拉取请求。在你做之前，再次确保你已经遵循本文档中关于代码风格，测试，性能测试和文档的所有准则。您还应该仔细检查您的分支更改是根据它所基于的分支：

在GitHub上导航到您的存储库 - https://github.com/your-user-name/pandas
点击Branches
单击功能部门的Compare按钮
如果需要，请选择base和compare分支。这将分别是master和shiny-new-feature。

Finally, make the pull request ¶

如果一切看起来不错，你准备提出一个拉请求。拉取请求是来自本地存储库的代码如何可用于GitHub社区，可以查看并最终合并到主版本。此拉取请求及其关联的更改将最终提交到主分支，并在下一个版本中可用。要提交拉款请求：

在GitHub上导航到您的存储库
点击拉动请求按钮
然后，您可以点击Commits和文件已更改
在预览讨论标签中写入您对更改的说明
点击发送拉请求。

然后，此请求将转到存储库维护人员，他们将查看代码。如果你需要做更多的更改，你可以在你的分支，将它们推送到GitHub，并拉动请求将自动更新。将它们推送到GitHub是通过：

git push -f origin shiny-new-feature

这将自动更新您的拉取请求与最新的代码，并重新启动Travis-CI测试。

如果您的拉取请求与pandas.io.gbq模块相关，请参阅Running Google BigQuery Integration Tests一节，为您的拉取请求配置Google BigQuery服务帐户在Travis-CI。

Delete your merged branch (optional)¶

一旦你的特性分支被接受到上游，你可能想要摆脱分支。首先，将上游主合并到你的分支，所以git知道它是安全的删除你的分支：

git fetch upstream
git checkout master
git merge upstream/master

然后你可以做：

git branch -d shiny-new-feature

确保使用小写的-d，否则git将不会警告你，如果你的功能分支没有被实际合并。

分支将仍然存在于GitHub上，所以删除它有：

git push origin --delete shiny-new-feature