Pandas-2-2-中文文档-三十八-

Pandas 2.2 中文文档（三十八）

原文：pandas.pydata.org/docs/

pandas.errors.InvalidComparison

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

exception pandas.errors.InvalidComparison

由 _validate_comparison_value 引发的异常，表示比较无效。

注意

这是一个内部错误。

pandas.errors.InvalidIndexError

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

exception pandas.errors.InvalidIndexError

当尝试使用无效索引键时引发的异常。

示例

>>> idx = pd.MultiIndex.from_product([["x", "y"], [0, 1]])
>>> df = pd.DataFrame([[1, 1, 2, 2],
...                   [3, 3, 4, 4]], columns=idx)
>>> df
 x       y
 0   1   0   1
0   1   1   2   2
1   3   3   4   4
>>> df[:, 0]
Traceback (most recent call last):
InvalidIndexError: (slice(None, None, None), 0) 

pandas.errors.InvalidVersion

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

exception pandas.errors.InvalidVersion

发现了一个无效的版本，请参考 PEP 440。

示例

>>> pd.util.version.Version('1.')
Traceback (most recent call last):
InvalidVersion: Invalid version: '1.' 

pandas.errors.IntCastingNaNError

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

exception pandas.errors.IntCastingNaNError

当将带有 NaN 的数组转换（astype）为整数类型时引发异常。

示例

>>> pd.DataFrame(np.array([[1, np.nan], [2, 3]]), dtype="i8")
Traceback (most recent call last):
IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer 

pandas.errors.LossySetitemError

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

exception pandas.errors.LossySetitemError

当尝试在非无损 np.ndarray 上执行 setitem 时引发。

注意

这是一个内部错误。

pandas.errors.MergeError

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

exception pandas.errors.MergeError

在合并数据时引发的异常。

ValueError的子类。

Examples

>>> left = pd.DataFrame({"a": ["a", "b", "b", "d"],
...                     "b": ["cat", "dog", "weasel", "horse"]},
...                     index=range(4))
>>> right = pd.DataFrame({"a": ["a", "b", "c", "d"],
...                      "c": ["meow", "bark", "chirp", "nay"]},
...                      index=range(4)).set_index("a")
>>> left.join(right, on="a", validate="one_to_one",)
Traceback (most recent call last):
MergeError: Merge keys are not unique in left dataset; not a one-to-one merge 

pandas.errors.NoBufferPresent

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

exception pandas.errors.NoBufferPresent

在 _get_data_buffer 中引发异常，表示没有请求的缓冲区。

pandas.errors.NullFrequencyError

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

exception pandas.errors.NullFrequencyError

当freq为空时引发异常。

特别是DatetimeIndex.shift，TimedeltaIndex.shift，PeriodIndex.shift。

示例

>>> df = pd.DatetimeIndex(["2011-01-01 10:00", "2011-01-01"], freq=None)
>>> df.shift(2)
Traceback (most recent call last):
NullFrequencyError: Cannot shift with no freq 

pandas.errors.NumbaUtilError

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

exception pandas.errors.NumbaUtilError

不支持的 Numba 引擎例程引发的错误。

示例

>>> df = pd.DataFrame({"key": ["a", "a", "b", "b"], "data": [1, 2, 3, 4]},
...                   columns=["key", "data"])
>>> def incorrect_function(x):
...     return sum(x) * 2.7
>>> df.groupby("key").agg(incorrect_function, engine="numba")
Traceback (most recent call last):
NumbaUtilError: The first 2 arguments to incorrect_function
must be ['values', 'index'] 

pandas.errors.NumExprClobberingError

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

exception pandas.errors.NumExprClobberingError

尝试使用内置的 numexpr 名称作为变量名时引发的异常。

如果引擎设置为'numexpr'，则eval或query将抛出错误。如果安装了 numexpr 包，'numexpr' 是这些方法的默认引擎值。

示例

>>> df = pd.DataFrame({'abs': [1, 1, 1]})
>>> df.query("abs > 2") 
... # NumExprClobberingError: Variables in expression "(abs) > (2)" overlap...
>>> sin, a = 1, 2
>>> pd.eval("sin + a", engine='numexpr') 
... # NumExprClobberingError: Variables in expression "(sin) + (a)" overlap... 

pandas.errors.OptionError

pandas.pydata.org/docs/reference/api/pandas.errors.OptionError.html

exception pandas.errors.OptionError

pandas.options 引发的异常。

与 KeyError 检查向后兼容。

示例

>>> pd.options.context
Traceback (most recent call last):
OptionError: No such option 

pandas.errors.OutOfBoundsDatetime

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

exception pandas.errors.OutOfBoundsDatetime

当日期时间超出可表示范围时引发。

示例

>>> pd.to_datetime("08335394550")
Traceback (most recent call last):
OutOfBoundsDatetime: Parsing "08335394550" to datetime overflows,
at position 0 

pandas.errors.OutOfBoundsTimedelta

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

exception pandas.errors.OutOfBoundsTimedelta

当遇到无法表示的时间差值时引发。

表示应该在 timedelta64[ns]内。

示例

>>> pd.date_range(start="1/1/1700", freq="B", periods=100000)
Traceback (most recent call last):
OutOfBoundsTimedelta: Cannot cast 139999 days 00:00:00
to unit='ns' without overflow. 

pandas.errors.ParserError

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

exception pandas.errors.ParserError

在解析文件内容时遇到错误时引发的异常。

这是在像 read_csv 或 read_html 这样的函数解析文件内容时遇到错误时引发的通用错误。

另请参阅

read_csv

将 CSV（逗号分隔）文件读入 DataFrame 中。

read_html

将 HTML 表格读入 DataFrame 中。

示例

>>> data = '''a,b,c
... cat,foo,bar
... dog,foo,"baz'''
>>> from io import StringIO
>>> pd.read_csv(StringIO(data), skipfooter=1, engine='python')
Traceback (most recent call last):
ParserError: ',' expected after '"'. Error could possibly be due
to parsing errors in the skipped footer rows 

pandas.errors.ParserWarning

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

exception pandas.errors.ParserWarning

在读取不使用默认‘c’解析器的文件时引发警告。

当需要更改解析器时，通常从默认的‘c’解析器更改为‘python’时，由pd.read_csv和pd.read_table引发。

这是由于请求的引擎对 CSV 文件的特定属性进行解析时缺乏支持或功能。

目前，不支持‘c’选项包括以下参数：

1. 分隔符不是单个字符（例如，正则表达式分隔符）

2. 跳过底部行数大于 0

3. sep=None，delim_whitespace=False

可以通过在pd.read_csv和pd.read_table方法中添加engine='python'参数来避免警告。

另请参阅

pd.read_csv

将 CSV（逗号分隔）文件读入 DataFrame。

pd.read_table

将通用分隔文件读入 DataFrame。

示例

在pd.read_csv中使用非单个字符的分隔符：

>>> import io
>>> csv = '''a;b;c
...           1;1,8
...           1;2,1'''
>>> df = pd.read_csv(io.StringIO(csv), sep='[;,]')  
... # ParserWarning: Falling back to the 'python' engine... 

在pd.read_csv中添加engine='python'可以消除警告：

>>> df = pd.read_csv(io.StringIO(csv), sep='[;,]', engine='python') 

pandas.errors.PerformanceWarning

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

exception pandas.errors.PerformanceWarning

当可能会影响性能时引发警告。

示例

>>> df = pd.DataFrame({"jim": [0, 0, 1, 1],
...                    "joe": ["x", "x", "z", "y"],
...                    "jolie": [1, 2, 3, 4]})
>>> df = df.set_index(["jim", "joe"])
>>> df
 jolie
jim  joe
0    x    1
 x    2
1    z    3
 y    4
>>> df.loc[(1, 'z')]  
# PerformanceWarning: indexing past lexsort depth may impact performance.
df.loc[(1, 'z')]
 jolie
jim  joe
1    z        3 

pandas.errors.PossibleDataLossError

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

exception pandas.errors.PossibleDataLossError

当已经打开一个 HDFStore 文件时尝试打开时引发的异常。

例子

>>> store = pd.HDFStore('my-store', 'a') 
>>> store.open("w") 
... # PossibleDataLossError: Re-opening the file [my-store] with mode [a]... 

pandas.errors.PossiblePrecisionLoss

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

exception pandas.errors.PossiblePrecisionLoss

在具有超出或等于 int64 值的列上，to_stata 会引发警告。

当列值在 int64 值之外或等于 int64 值时，该列将被转换为 float64 类型。

示例

>>> df = pd.DataFrame({"s": pd.Series([1, 2**53], dtype=np.int64)})
>>> df.to_stata('test') 
... # PossiblePrecisionLoss: Column converted from int64 to float64... 

pandas.errors.PyperclipException

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

exception pandas.errors.PyperclipException

当剪贴板功能不支持时引发异常。

由 to_clipboard() 和 read_clipboard() 引发。

pandas.errors.PyperclipWindowsException

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

exception pandas.errors.PyperclipWindowsException(message)

当 Windows 不支持剪贴板功能时引发的异常。

由于其他窗口进程正在访问剪贴板，因此访问剪贴板句柄将被拒绝。

pandas.errors.SettingWithCopyError

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

exception pandas.errors.SettingWithCopyError

尝试在从DataFrame复制的切片上设置时引发异常。

mode.chained_assignment需要设置为‘raise’。这可能会在链式索引时无意中发生。

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

有关视图与复制的更多信息，请参阅用户指南。

示例

>>> pd.options.mode.chained_assignment = 'raise'
>>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
>>> df.loc[0:3]['A'] = 'a' 
... # SettingWithCopyError: A value is trying to be set on a copy of a... 

pandas.errors.SettingWithCopyWarning

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

exception pandas.errors.SettingWithCopyWarning

尝试在从 DataFrame 复制的切片上设置时引发警告。

mode.chained_assignment 需要设置为 ‘warn’。‘warn’ 是默认选项。这可能在链式索引时无意中发生。

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

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

示例

>>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
>>> df.loc[0:3]['A'] = 'a' 
... # SettingWithCopyWarning: A value is trying to be set on a copy of a... 

pandas.errors.SpecificationError

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

exception pandas.errors.SpecificationError

agg函数在函数不正确指定的情况下引发异常。

在两种情况下引发的异常。

第一种方式是在 DataFrame 或 Series 上使用嵌套重命名器（字典-字典）调用agg。

第二种方式是在 DataFrame 上调用agg，函数名称重复且未分配列名。

示例

>>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2],
...                    'B': range(5),
...                    'C': range(5)})
>>> df.groupby('A').B.agg({'foo': 'count'}) 
... # SpecificationError: nested renamer is not supported 

>>> df.groupby('A').agg({'B': {'foo': ['sum', 'max']}}) 
... # SpecificationError: nested renamer is not supported 

>>> df.groupby('A').agg(['min', 'min']) 
... # SpecificationError: nested renamer is not supported 

pandas.errors.UndefinedVariableError

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

exception pandas.errors.UndefinedVariableError(name, is_local=None)

当使用未定义的变量名时，由query或eval引发的异常。

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

例子

>>> df = pd.DataFrame({'A': [1, 1, 1]})
>>> df.query("A > x") 
... # UndefinedVariableError: name 'x' is not defined
>>> df.query("A > @y") 
... # UndefinedVariableError: local variable 'y' is not defined
>>> pd.eval('x + 1') 
... # UndefinedVariableError: name 'x' is not defined 

pandas.errors.UnsortedIndexError

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

exception pandas.errors.UnsortedIndexError

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

KeyError 的子类。

示例

>>> df = pd.DataFrame({"cat": [0, 0, 1, 1],
...                    "color": ["white", "white", "brown", "black"],
...                    "lives": [4, 4, 3, 7]},
...                   )
>>> df = df.set_index(["cat", "color"])
>>> df
 lives
cat  color
0    white    4
 white    4
1    brown    3
 black    7
>>> df.loc[(0, "black"):(1, "white")]
Traceback (most recent call last):
UnsortedIndexError: 'Key length (2) was greater
than MultiIndex lexsort depth (1)' 

pandas.errors.UnsupportedFunctionCall

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

exception pandas.errors.UnsupportedFunctionCall

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

例如，np.cumsum(groupby_object)。

Examples

>>> df = pd.DataFrame({"A": [0, 0, 1, 1],
...                    "B": ["x", "x", "z", "y"],
...                    "C": [1, 2, 3, 4]}
...                   )
>>> np.cumsum(df.groupby(["A"]))
Traceback (most recent call last):
UnsupportedFunctionCall: numpy operations are not valid with groupby.
Use .groupby(...).cumsum() instead 

pandas.errors.ValueLabelTypeMismatch

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

exception pandas.errors.ValueLabelTypeMismatch

警告：在包含非字符串值的类别列上，to_stata 函数引发的警告。

Examples

>>> df = pd.DataFrame({"categories": pd.Series(["a", 2], dtype="category")})
>>> df.to_stata('test') 
... # ValueLabelTypeMismatch: Stata value labels (pandas categories) must be 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()  
Your output may look something like this:
INSTALLED VERSIONS
------------------
commit           : 37ea63d540fd27274cad6585082c91b1283f963d
python           : 3.10.6.final.0
python-bits      : 64
OS               : Linux
OS-release       : 5.10.102.1-microsoft-standard-WSL2
Version          : #1 SMP Wed Mar 2 00:30:59 UTC 2022
machine          : x86_64
processor        : x86_64
byteorder        : little
LC_ALL           : None
LANG             : en_GB.UTF-8
LOCALE           : en_GB.UTF-8
pandas           : 2.0.1
numpy            : 1.24.3
... 

缺失值

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

NA 是表示可为空数据类型的缺失值的方式（见下文）：

NA	NA（"不可用"）缺失值指示符。

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

NaT	（N）ot-（A）-（T）ime，NaN 的时间等价物。

pandas.NA

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

pandas.NA

别名为

pandas.NaT

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

pandas.NaT

NaT 的别名

开发

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

• 为 pandas 做贡献

  • 错误报告和改进建议

  • 找到要贡献的问题

  • 提交拉取请求

  • 成功提交拉取请求的技巧

• 创建开发环境

  • 第一步：安装 C 编译器

  • 第二步：创建隔离环境

  • 第三步：构建并安装 pandas

• 为文档做贡献

  • 关于 pandas 文档

  • 更新 pandas 文档字符串

  • 如何构建 pandas 文档

  • 预览更改

• 为代码库做贡献

  • 代码规范

  • 预提交

  • 可选依赖项

  • 向后兼容性

  • 类型提示

  • 使用持续集成进行测试

  • 测试驱动开发

  • 运行测试套件

  • 运行性能测试套件

  • 记录代码

• pandas 维护

  • 角色

  • 任务

  • 问题分类

  • 调查回归

  • 关闭问题

  • 审查拉取请求

  • 回溯

  • 清理旧的问题

  • 清理旧的拉取请求

  • 成为 pandas 维护者

  • 合并拉取请求

  • 基准机

  • 发布流程

• 内部机制

  • 索引

  • 继承 pandas 数据结构

• 写时复制

  • 引用追踪

• 调试 C 扩展

  • 本地调试

  • 使用 Docker

  • 编辑器支持

• 扩展 pandas

  • 注册自定义访问器

  • 扩展类型

  • 继承 pandas 数据结构

  • 绘图后端

  • 与第三方类型进行算术运算

• 开发者

  • 将 pandas DataFrame 对象存储为 Apache Parquet 格式

• 政策

  • 版本策略

  • Python 支持

  • 安全策略

• 贡献者社区

  • 社区会议

  • 新贡献者会议

  • 日历

  • GitHub 问题跟踪器

  • 开发者邮件列表

  • 社区 Slack

贡献给 pandas

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

目录：

• 错误报告和增强请求

• 找到要贡献的问题

• 提交拉取请求

  • 版本控制，Git 和 GitHub

  • 开始使用 Git

  • 创建一个 pandas 分支

  • 创建一个功能分支

  • 进行代码更改

  • 推送您的更改

  • 创建拉取请求

  • 更新您的拉取请求

  • 更新开发环境

• 成功提交拉取请求的提示

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

错误报告和增强请求

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

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

找到要贡献的问题

如果您是 pandas 或开源开发的新手，我们建议搜索GitHub“问题”选项卡以找到您感兴趣的问题。未分配的问题标记为文档和好的第一个问题通常适合新贡献者。

一旦您找到一个有趣的问题，最好将问题分配给自己，这样其他人就不会重复处理它。在 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 社区可审查并合并到项目中以出现在下一个发布版中的方式。要提交拉取请求：

1. 转到 GitHub 上的您的存储库

2. 单击Compare & pull request按钮

3. 然后，您可以单击Commits和Files Changed以确保一切看起来都没问题。

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

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

5. 在Preview Discussion标签中写下您的更改描述

6. 点击发送 Pull Request。

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

更新您的 Pull Request

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

pandasmain分支中的更新也很重要，应在您的 Pull Request 中反映出来。要将您的特性分支与 pandasmain分支中的更改同步，运行：

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

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

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

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

1. 运行git add -u来暂存您更新的任何文件；

2. 运行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 社区可审查并合并到项目中以出现在下一个发布中的方式。要提交拉取请求：

1. 转到您在 GitHub 上的存储库

2. 单击比较和拉取请求按钮

3. 您随后可以单击Commits和Files Changed，以确保最后一次一切看起来都正常

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

   • ENH: 增强功能，新功能
   • BUG: 修复错误
   • DOC: 添加/更新文档
   • TST: 添加/更新测试
   • BLD: 更新构建过程/脚本
   • PERF: 性能改进
   • TYP: 类型注解
   • CLN: 代码清理

5. 在预览讨论选项卡中编写更改描述

6. 单击发送拉取请求。

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

更新您的拉取请求

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

重要的是要确保 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/，了解如何操作。

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

1. git add -u 将更新过的文件加入到暂存区；

2. 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 

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

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 社区可审查并合并到项目中以出现在下一个版本中的方式。提交拉取请求：

1. 转到您在 GitHub 上的存储库

2. 单击 Compare & pull request 按钮

3. 然后，单击 Commits 和 Files Changed，确保最后一次一切正常。

4. 写一个包含前缀的描述性标题。pandas 使用标题前缀约定。以下是一些常见的前缀以及何时使用它们的一般指南：

   • ENH: 增强，新功能
   • BUG: 修复 bug
   • DOC: 文档添加/更新
   • TST: 测试添加/更新
   • BLD: 构建过程/脚本的更新
   • PERF: 性能改进
   • TYP: 类型注释
   • CLN: 代码清理

5. 在 Preview Discussion 标签中写下您的更改描述

6. 点击 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/ 了解如何做到这一点的解释。

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

1. git add -u 将更新的任何文件加入到暂存区；

2. 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 的文档此处。

# 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 中启动远程会话，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 的文档此处。

# 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 设置虚拟环境的简要概述。详情请参阅官方虚拟环境用户指南。

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

使用 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 上工作的最佳方式是首先制作存储库的分叉。

1. 浏览到 GitHub 上的 pandas 存储库 并创建你自己的分叉。

2. 浏览到你的分叉。你的分叉将有一个类似于 noatamir/pandas-dev 的 URL，只是用你的 GitHub 用户名代替 noatamir。

启动 Gitpod

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

1. 如果你安装了扩展程序 - 你可以点击 Gitpod 按钮启动新的工作区。

2. 或者，如果你不想安装浏览器扩展程序，你可以访问gitpod.io/#https://github.com/USERNAME/pandas，将USERNAME替换为你的 GitHub 用户名。

3. 在这两种情况下，这将在你的网络浏览器中打开一个新的标签，并开始构建你的开发环境。请注意，这可能需要几分钟的时间。

4. 构建完成后，你将被引导到你的工作区，包括 VSCode 编辑器和你在 pandas 上工作所需的所有依赖项。当你第一次启动你的工作区时，你会注意到可能有一些操作正在运行。这将确保你安装了 pandas 的开发版本。

5. 当你的工作区准备好时，你可以通过输入来测试构建：

   $ python -m pytest pandas 
   

   请注意，此命令运行时间较长，因此一旦确认正在运行，您可能希望使用 ctrl-c 取消它。

快速的工作空间导览

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

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

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

1. 您当前的 Python 解释器 - 默认情况下，这是 pandas-dev，应显示在状态栏和终端上。您不需要激活 conda 环境，因为这将始终为您激活。

2. 您当前的分支始终显示在状态栏中。您还可以使用此按钮来更改或创建分支。

3. GitHub 拉取请求扩展 - 您可以使用此扩展从工作空间处理拉取请求。

4. 市场扩展 - 我们已向 pandas Gitpod 添加了一些基本扩展。但是，您还可以为自己安装其他扩展或语法突出显示主题，这些扩展将为您保留。

5. 您的工作空间目录 - 默认情况下，它是 /workspace/pandas-dev。不要更改此目录，因为这是 Gitpod 中保留的唯一目录。

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

• VSCode rst 扩展

• Markdown All in One

• VSCode Gitlens 扩展

• VSCode Git 图形扩展

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

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

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

1. 您不需要配置 git 用户名和电子邮件，因为在通过 GitHub 进行身份验证时应已完成此操作。除非您正在使用 GitHub 功能保持电子邮件地址私密。您可以在终端中使用命令 git config --list 检查 git 配置。使用 git config --global user.email “your-secret-email@users.noreply.github.com” 将您的电子邮件地址设置为您在 github 个人资料中使用的电子邮件地址进行提交。

2. 由于你是从自己的 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

1. 在pandas/doc/build/html中查看文档。

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

   

3. 一个简单的浏览器将会在编辑器的右侧打开。我们建议关闭它，然后点击弹出窗口中的在浏览器中打开按钮。

4. 要停止服务器，请点击状态栏上的端口：5500按钮。

选项 2：使用 rst 扩展

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

注意

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

1. 在编辑器中打开位于doc/source中的任何源文档文件。

2. 在 Mac 上使用Cmd`-`Shift`-`P或在 Linux 和 Windows 上使用Ctrl`-`Shift`-`P打开 VSCode 命令面板。开始输入“restructured”，然后选择“打开预览”或“打开侧边预览”。

   

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

   

如果你想要看到带有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 方面已知的问题。您可以通过两种方式解决此问题：

1. 新建一个全新的 Gitpod 工作区。

2. 前往您的 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 的最佳方式是首先创建该仓库的分支。

1. 浏览到GitHub 上的 pandas 存储库并创建你自己的分支。

2. 浏览到你的分支。你的分支将有一个类似于noatamir/pandas-dev的 URL，只是将noatamir替换为你的 GitHub 用户名。

启动 Gitpod

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

1. 如果你安装了扩展 - 你可以点击Gitpod按钮启动一个新的工作空间。

2. 或者，如果你不想安装浏览器扩展，你可以访问gitpod.io/#https://github.com/USERNAME/pandas，将USERNAME替换为你的 GitHub 用户名。

3. 在这两种情况下，这将在你的网络浏览器上打开一个新标签页并开始构建你的开发环境。请注意，这可能需要几分钟。

4. 一旦构建完成，你将被引导到你的工作空间，包括 VSCode 编辑器和你在 pandas 上工作所需的所有依赖项。第一次启动工作空间时，你���注意到可能有一些操作正在运行。这将确保你安装了 pandas 的开发版本。

5. 当你的工作空间准备好后，你可以通过输入以下内容来测试构建：

   $ python -m pytest pandas 
   

   请注意，这个命令运行起来需要一段时间，所以一旦确认它正在运行，你可能想要使用 ctrl-c 取消它。

快速工作空间导览

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

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

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

1. 你当前的 Python 解释器 - 默认情况下是pandas-dev，应该显示在状态栏和终端上。你不需要激活 conda 环境，因为这将始终为你激活。

2. 你当前的分支始终显示在状态栏中。你也可以使用这个按钮来更改或创建分支。

3. GitHub 拉取请求扩展 - 你可以使用这个扩展来处理来自工作空间的拉取请求。

4. Marketplace 扩展 - 我们已经为 pandas Gitpod 添加了一些必要的扩展。但是，你也可以安装其他扩展或语法高亮主题供你使用，并且这些将为你保留。

5. 你的工作空间目录 - 默认情况下是/workspace/pandas-dev。请不要更改，因为这是 Gitpod 中唯一保留的目录。

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

• VSCode rst 扩展

• Markdown All in One

• VSCode Gitlens 扩展

• VSCode Git 图表扩展

使用 Gitpod 的开发工作流程

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

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

1. 您不需要配置 git 用户名和电子邮件，因为在您通过 GitHub 进行身份验证时应该已经为您完成了此操作。除非您使用 GitHub 功能保持电子邮件地址私密。您可以在终端中使用命令 git config --list 检查 git 配置。使用 git config --global user.email “your-secret-email@users.noreply.github.com” 命令将您的电子邮件地址设置为您在 github 个人资料中用于提交的地址。

2. 由于您从自己的 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

1. 查看位于 pandas/doc/build/html 中的文档。

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

   

3. 简单的浏览器将会在编辑器的右侧打开。我们建议将其关闭，并单击弹出窗口中的Open in browser按钮。

4. 要停止服务器，请点击状态栏上的Port: 5500按钮。

选项 2：使用 rst 扩展

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

注意

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

1. 在编辑器中打开位于doc/source中的任何源文档文件。

2. 在 Mac 上使用Cmd`-`Shift`-`P或在 Linux 和 Windows 上使用Ctrl`-`Shift`-`P打开 VSCode 命令面板。开始输入“restructured”，然后选择“打开预览”或“打开侧边栏预览”。

   

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

   

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

选项 1：使用 Live Serve

1. 在pandas/doc/build/html中查看文档。

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

   

3. 一个简单的浏览器将在编辑器的右侧打开。我们建议关闭它，然后点击弹出窗口中的在浏览器中打开按钮。

4. 要停止服务器，请点击状态栏上的端口：5500按钮。

选项 2：使用 rst 扩展

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

注意

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

1. 在编辑器中打开位于doc/source中的任何源文档文件。

2. 在 Mac 上使用Cmd`-`Shift`-`P或在 Linux 和 Windows 上使用Ctrl`-`Shift`-`P打开 VSCode 命令面板。开始输入“restructured”，然后选择“打开预览”或“打开侧边栏预览”。

   

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

   

如果你想看到带有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 方面已知的问题。你可以通过两种方式解决这个问题：

1. 创建一个全新的 Gitpod 工作空间。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. 创建一个全新的 Gitpod 工作区。

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

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

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

致谢

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

为文档做出贡献

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

为文档做出贡献将使使用 pandas 的每个人受益。我们鼓励您帮助我们改进文档，您不必是 pandas 的专家！事实上，有些部分的文档在被专家编写后变得更糟糕。如果文档中的某些内容对您来说不合理，请在弄清楚后更新相关部分，这是确保它将帮助下一个人的好方法。请访问问题页面查看有关 Pandas 文档目前正在开放的问题的完整列表。

文档：

• 关于 pandas 文档

• 更新 pandas 文档字符串

• 如何构建 pandas 文档

  • 要求

  • 构建文档

  • 构建主分支文档

• 预览更改

关于 pandas 文档

文档采用reStructuredText编写，几乎就像用普通英语写作一样，并使用Sphinx构建。 Sphinx 文档有一个出色的reST 简介。请查阅 Sphinx 文档以对文档进行更复杂的更改。

关于文档的其他重要事项：

• pandas 文档包括两部分：代码本身中的文档字符串和此文件夹中的文档doc/。

  文档字符串清晰解释了各个函数的用法，而此文件夹中的文档包括每个主题的类似教程的概述以及其他一些信息（新功能、安装等）。

• 文档字符串遵循 pandas 惯例，基于Numpy Docstring Standard。请按照 pandas 文档字符串指南中的详细说明编写正确的文档字符串。

  • pandas 文档字符串指南

    • 关于文档字符串和标准

    • 编写文档字符串

    • 分享文档字符串

• 教程大量使用了IPython directive sphinx 扩展。此指令允许您在文档中放置将在文档构建期间运行的代码。例如：

  .. ipython:: python
  
      x = 2
      x**3 
  

  将被呈现为：

  In [1]: x = 2
  
  In [2]: x**3
  Out[2]: 8 
  

  文档中几乎所有代码示例都在文档构建过程中运行（���保存输出）。这种方法意味着代码示例始终是最新的，但这确实使文档构建变得更加复杂。

• 我们的 API 文档文件位于doc/source/reference，其中包含来自文档字符串的自动生成文档。对于类，有一些微妙之处，可以控制哪些方法和属性具有自动生成页面。

  我们有两个用于类的 autosummary 模板。

  1. _templates/autosummary/class.rst。当您想要自动生成类的每个公共方法和属性的页面时，请使用此模板。Attributes和Methods部分将由 numpydoc 自动添加到类的渲染文档中。请参见DataFrame以获取示例。

  2. _templates/autosummary/class_without_autosummary。当您想要选择一部分方法/属性自动生成页面时，请使用此模板。在使用此模板时，您应该在类文档字符串中包含一个Attributes和Methods部分。请参见CategoricalIndex以获取示例。

  每个方法都应该包含在doc/source/reference中的一个文档文件的toctree中，否则 Sphinx 会发出警告。

实用脚本scripts/validate_docstrings.py可用于获取 API 文档的 csv 摘要。还可以验证特定类、函数或方法的文档字符串中的常见错误。摘要还比较了在doc/source/reference文件中记录的方法列表（用于生成API 参考页面）和实际的公共方法。这将识别在doc/source/reference中记录但实际上不是类方法的方法，以及未在doc/source/reference中记录的现有方法。

更新 pandas 文档字符串

在改进单个函数或方法的文档字符串时，不一定需要构建完整的文档（请参见下一节）。但是，有一个脚本可以检查文档字符串（例如DataFrame.mean方法）：

python scripts/validate_docstrings.py pandas.DataFrame.mean 

如果存在格式错误，此脚本将指示一些格式错误，并且还将运行和测试文档字符串中包含的示例。请查看 pandas 文档字符串指南以获取有关如何格式化文档字符串的详细指南。

文档字符串中的示例（‘doctests’）必须是有效的 Python 代码，以确定性方式返回所呈现的输出，并且用户可以复制并运行。这可以通过上述脚本进行检查，并且还在 Travis 上进行测试。失败的 doctest 将阻止合并 PR。请查看文档字符串指南中的示例部分，获取一些使 doctests 通过的提示和技巧。

在进行包含文档字符串更新的 PR 时，最好在 github 的评论中发布验证脚本的输出。

如何构建 pandas 文档

要求

首先，你需要有一个开发环境才能构建 pandas（参见创建开发环境文档）。

构建文档

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

python make.py html 

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

第一次构建文档时，会花费相当长的时间，因为它必须运行所有代码示例并构建所有生成的文档字符串页面。在后续调用中，sphinx 将尝试仅构建已修改的页面。

如果你想进行完整的清理构建，请执行：

python make.py clean
python make.py html 

你可以告诉make.py只编译文档的一个部分，大大减少检查更改的周转时间。

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

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew 

作为对比，完整的文档构建可能需要 15 分钟，但单个部分可能只需 15 秒。后续构建，只处理您更改的部分，将更快。

构建将自动使用您机器上可用的核心数来加快文档构建速度。您可以覆盖此设置：

python make.py html --num-jobs 4 

在网页浏览器中打开以下文件，查看你刚刚构建的完整文档doc/build/html/index.html。

你将看到你的新文档得到改进的满足感！

构建主分支文档

当拉取请求合并到 pandas 的main分支时，Travis-CI 也会构建文档的主要部分。然后这些文档托管在这里，另请参阅持续集成部分。

预览更改

一旦提交拉取请求，GitHub Actions 将自动构建文档。要查看构建的站点：

1. 等待CI / Web and docs检查完成。

2. 点击旁边的Details。

3. 从Artifacts下拉菜单中，点击docs或website以下载站点的 ZIP 文件。

关于 pandas 文档

文档是用reStructuredText编写的，几乎就像用普通英语写作一样，并使用Sphinx构建。 Sphinx 文档有一个出色的reST 简介。查看 Sphinx 文档以执行更复杂的文档更改。

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

• pandas 文档包括两部分：代码本身中的文档字符串和此文件夹doc/中的文档。

  文档字符串提供了对各个函数使用的清晰解释，而此文件夹中的文档包括每个主题的类似教程的概述以及其他一些信息（新功能，安装等）。

• docstrings 遵循基于Numpy Docstring Standard的 pandas 约定。请遵循 pandas docstring 指南以获取有关如何编写正确 docstring 的详细说明。

  • pandas docstring 指南

    • 关于 docstrings 和标准

    • 编写 docstring

    • 分享 docstrings

• 教程大量使用了IPython directive sphinx 扩展。该指令允许您在文档中放置代码，这些代码将在文档构建过程中运行。例如：

  .. ipython:: python
  
      x = 2
      x**3 
  

  将呈现为：

  In [1]: x = 2
  
  In [2]: x**3
  Out[2]: 8 
  

  文档中几乎所有的代码示例都在文档构建过程中运行（并保存输出）。这种方法意味着代码示例始终是最新的，但这确实使文档构建变得更加复杂。

• 我们的 API 文档文件在doc/source/reference中存储了从 docstrings 自动生成的文档。对于类，有一些微妙之处，可以控制哪些方法和属性具有自动生成页面。

  我们有两个用于类的 autosummary 模板。

  1. _templates/autosummary/class.rst。当您想要自动生成类上的每个公共方法和属性的页面时，请使用此模板。Attributes和Methods部分将由 numpydoc 自动添加到类的渲染文档中。查看DataFrame以获取示例。

  2. _templates/autosummary/class_without_autosummary。当您想要为方法/属性的子集自动生成页面时，请使用此模板。在使用此模板时，您应该在类 docstring 中包含一个Attributes和Methods部分。查看CategoricalIndex以获取示例。

  每个方法都应包含在doc/source/reference中的一个文档文件的toctree中，否则 Sphinx 将发出警告。

实用脚本scripts/validate_docstrings.py可用于获取 API 文档的 csv 摘要。还可以验证特定类、函数或方法的 docstring 中的常见错误。摘要还比较了在doc/source/reference文件中记录的方法列表（用于生成API 参考页面）和实际的公共方法。这将识别在doc/source/reference中记录但实际上不是类方法的方法，以及未在doc/source/reference中记录的现有方法。

更新 pandas docstring

在改进单个函数或方法的 docstring 时，不一定需要构建完整的文档（请参阅下一节）。但是，有一个脚本可以检查 docstring（例如DataFrame.mean方法）：

python scripts/validate_docstrings.py pandas.DataFrame.mean 

如果存在格式错误，此脚本将指示，并且还将运行并测试文档字符串中包含的示例。请查阅 pandas 文档字符串指南以获取如何格式化文档字符串的详细指南。

文档字符串中的示例（'doctests'）必须是有效的 Python 代码，以确定性地返回所呈现的输出，并且用户可以复制并运行。这可以使用上述脚本检查，并且还在 Travis 上进行了测试。失败的 doctest 将阻止合并 PR。请查阅文档字符串指南中的示例部分，获取使 doctests 通过的一些技巧和窍门。

在提交带有文档字符串更新的 PR 时，在 github 上发布验证脚本的输出是一个好习惯。

如何构建 pandas 文档

要求

首先，你需要有一个开发环境才能构建 pandas（参见创建开发环境的文档）。

构建文档

那么如何构建文档呢？在控制台中导航到你的本地doc/目录，并运行：

python make.py html 

接下来，你可以在文件夹doc/build/html/中找到 HTML 输出。

第一次构建文档时，会花费相当长的时间，因为它必须运行所有代码示例并构建所有生成的文档字符串页面。在随后的调用中，sphinx 将尝试仅构建已修改的页面。

如果你想进行完整的清理构建，执行以下命令：

python make.py clean
python make.py html 

你可以告诉make.py只编译文档的单个部分，大大减少了检查更改的回转时间。

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

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew 

作为对比，完整的文档构建可能需要 15 分钟，但单个部分可能只需 15 秒。随后的构建，只处理你已更改的部分，会更快。

构建将自动使用您计算机上可用的核心数来加速文档构建。您可以覆盖这一设置：

python make.py html --num-jobs 4 

在浏览器中打开以下文件，即可查看刚刚构建的完整文档doc/build/html/index.html。

然后，你会满意地看到你的新的和改进的文档！

构建主分支文档

当拉取请求合并到 pandas main 分支时，Travis-CI 也会构建文档的主要部分。然后这些文档托管在这里，还请参阅持续集成部分。

要求

首先，你需要有一个开发环境才能构建 pandas（参见创建开发环境的文档）。

构建文档

那么如何构建文档呢？在控制台中导航到你的本地doc/目录，并运行：

python make.py html 

接下来，你可以在文件夹doc/build/html/中找到 HTML 输出。

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

如果要进行完全清理构建，请执行：

python make.py clean
python make.py html 

你可以告诉 make.py 只编译文档的一个部分，大大减少检查更改的时间。

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

# compile the docs with only a single section, relative to the "source" folder.
# For example, compiling only this guide (doc/source/development/contributing.rst)
python make.py clean
python make.py --single development/contributing.rst

# compile the reference docs for a single function
python make.py clean
python make.py --single pandas.DataFrame.join

# compile whatsnew and API section (to resolve links in the whatsnew)
python make.py clean
python make.py --whatsnew 

作为对比，完整的文档构建可能需要 15 分钟，但单个部分可能只需要 15 秒。后续构建，只处理您已更改的部分，速度会更快。

构建将自动使用您计算机上可用的核心数加快文档构建速度。您可以覆盖此设置：

python make.py html --num-jobs 4 

在网络浏览器中打开以下文件，查看刚刚构建的完整文档 doc/build/html/index.html。

然后，您将满足地看到您的新和改进的文档！

构建主分支文档

当拉取请求合并到 pandas 的 main 分支时，Travis-CI 也会构建文档的主要部分。这些文档随后托管在 这里，另请参阅 持续集成 部分。

预览更改

一旦提交拉取请求，GitHub Actions 将自动构建文档。要查看构建的站点：

1. 等待 CI / Web and docs 检查完成。

2. 点击旁边的 Details。

3. 从 Artifacts 下拉菜单中，点击 docs 或 website 以下载站点的 ZIP 文件。

pandas 文档字符串指南

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

关于文档字符串和标准

Python 文档字符串是用于记录 Python 模块、类、函数或方法的字符串，以便程序员可以在不阅读实现细节的情况下了解其功能。

此外，从文档字符串自动生成在线（html）文档是一种常见做法。Sphinx用于此目的。

下一个示例展示了文档字符串的样式：

def add(num1, num2):
  """
 Add up two integer numbers.

 This function simply wraps the ``+`` operator, and does not
 do anything interesting, except for illustrating what
 the docstring of a very simple function looks like.

 Parameters
 ----------
 num1 : int
 First number to add.
 num2 : int
 Second number to add.

 Returns
 -------
 int
 The sum of ``num1`` and ``num2``.

 See Also
 --------
 subtract : Subtract one integer from another.

 Examples
 --------
 >>> add(2, 2)
 4
 >>> add(25, 0)
 25
 >>> add(10, -10)
 0
 """
    return num1 + num2 

存在一些关于文档字符串的标准，使它们更易阅读，并允许它们轻松导出到其他格式，如 html 或 pdf。

每个 Python 文档字符串应遵循的第一个约定在PEP-257中定义。

由于 PEP-257 相当广泛，还存在其他更具体的标准。在 pandas 的情况下，遵循 NumPy 文档字符串约定。这些约定在本文档中有解释：

• numpydoc 文档字符串指南

numpydoc 是一个支持 NumPy 文档字符串约定的 Sphinx 扩展。

该标准使用 reStructuredText（reST）。reStructuredText 是一种标记语言，允许在纯文本文件中编码样式。关于 reStructuredText 的文档可以在以下找到：

• Sphinx reStructuredText 入门

• 快速 reStructuredText 参考

• 完整的 reStructuredText 规范

pandas 有一些辅助功能，用于在相关类之间共享文档字符串，请参见共享文档字符串。

本文的其余部分将总结上述所有准则，并提供特定于 pandas 项目的其他约定。

编写文档字符串

一般规则

文档字符串必须用三个双引号定义。在文档字符串之前或之后不应留下空行。文本从开头引号的下一行开始。结束引号有自己的一行（这意味着它们不在最后一句的末尾）。

在罕见情况下，文档字符串中会使用 reST 样式，如粗体文本或斜体文本，但常见的是内联代码，用反引号括起来。以下被视为内联代码：

• 参数的名称

• Python 代码，模块，函数，内置，类型，文字…（例如os，list，numpy.abs，datetime.date，True）

• 一个 pandas 类（形式为:class:pandas.Series``）

• 一个 pandas 方法（形式为:meth:pandas.Series.sum``）

• 一个 pandas 函数（形式为:func:pandas.to_datetime``）

注意

要仅显示链接类、方法或函数的最后一个组件，请在其前面加上~。例如，:class:~pandas.Series``将链接到pandas.Series，但只显示最后部分Series作为链接文本。有关详细信息，请参阅Sphinx 交叉引用语法。

好的：

def add_values(arr):
  """
 Add the values in ``arr``.

 This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

 Some sections are omitted here for simplicity.
 """
    return sum(arr) 

不好的：

def func():

  """Some function.

 With several mistakes in the docstring.

 It has a blank like after the signature ``def func():``.

 The text 'Some function' should go in the line after the
 opening quotes of the docstring, not in the same line.

 There is a blank line between the docstring and the first line
 of code ``foo = 1``.

 The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar 
```  ### 第 1 节：简短摘要

简短摘要是一个简洁表达函数功能的单个句子。

简短摘要必须以大写字���开头，以句点结束，并适合在一行内。它需要表达对象的功能，而不提供详细信息。对于函数和方法，简短摘要必须以不定式动词开头。

**好的：**

```py
def astype(dtype):
  """
 Cast Series type.

 This section will provide further details.
 """
    pass 

不好的：

def astype(dtype):
  """
 Casts Series type.

 Verb in third-person of the present simple, should be infinitive.
 """
    pass 

def astype(dtype):
  """
 Method to cast Series type.

 Does not start with verb.
 """
    pass 

def astype(dtype):
  """
 Cast Series type

 Missing dot at the end.
 """
    pass 

def astype(dtype):
  """
 Cast Series type from its current type to the new type defined in
 the parameter dtype.

 Summary is too verbose and doesn't fit in a single line.
 """
    pass 
```  ### 第 2 节：扩展摘要

扩展摘要提供了函数的详细信息。它不应该详细说明参数，或讨论实现注意事项，这些应该在其他部分中说明。

简短摘要和扩展摘要之间留有一个空行。扩展摘要中的每个段落都以句点结束。

扩展摘要应提供函数的用途及其用例的详细信息，如果不太通用的话。

```py
def unstack():
  """
 Pivot a row index to columns.

 When using a MultiIndex, a level can be pivoted so each value in
 the index becomes a column. This is especially useful when a subindex
 is repeated for the main index, and data is easier to visualize as a
 pivot table.

 The index level will be automatically removed from the index when added
 as columns.
 """
    pass 
```  ### 第 3 节：参数

参数的详细信息将添加在此部分。此部分的标题为“参数”，下面是一个以“参数”每个字母下面的连字符为分隔的线。在部分标题之前留有一个空行，但之后不留空行，也不在“参数”一词下面的线和连字符之间留空行。

在标题之后，必须记录签名中的每个参数，包括`*args`和`**kwargs`，但不包括`self`。

参数由其名称定义，后面跟着一个空格，一个冒号，另一个空格，以及类型（或类型）。请注意名称和冒号之间的空格很重要。对于`*args`和`**kwargs`不定义类型，但对于所有其他参数必须定义类型。在参数定义之后，需要有一个带缩进的参数描述行，可以有多行。描述必须以大写字母开头，并以句点结束。

对于带有默认值的关键字参数，类型后面会列出默认值，具体形式为“int, default 0”。在某些情况下，解释默认参数的含义可能很有用，可以在逗号后面添加“int, default -1，表示所有 cpu”。

在默认值为 `None` 的情况下，意味着该值不会被使用。与 `"str, default None"` 不同，更倾向于写成 `"str, optional"`。当 `None` 是被使用的值时，我们将保持`"str, default None"`形式。例如，在 `df.to_csv(compression=None)` 中，`None` 不是被使用的值，而是表示压缩是可选的，如果未提供，则不使用压缩。在这种情况下，我们将使用 `"str, optional"`。仅在类似 `func(value=None)` 和 `None` 被使用与 `0` 或 `foo` 相同的方式时，我们将指定“str, int or None, default None”。

**好：**

```py
class Series:
    def plot(self, kind, color='blue', **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Parameters
 ----------
 kind : str
 Kind of matplotlib plot.
 color : str, default 'blue'
 Color name or rgb code.
 **kwargs
 These parameters will be passed to the matplotlib plotting
 function.
 """
        pass 

不好：

class Series:
    def plot(self, kind, **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Note the blank line between the parameters title and the first
 parameter. Also, note that after the name of the parameter ``kind``
 and before the colon, a space is missing.

 Also, note that the parameter descriptions do not start with a
 capital letter, and do not finish with a dot.

 Finally, the ``**kwargs`` parameter is missing.

 Parameters
 ----------

 kind: str
 kind of matplotlib plot
 """
        pass 

参数类型

在指定参数类型时，可以直接使用 Python 内置数据类型（优选使用 Python 类型，而不是更冗长的字符串、整数、布尔值等）：

• int

• float

• str

• bool

对于复杂类型，定义子类型。对于 dict 和 tuple，由于存在多种类型，我们使用括号来帮助阅读类型（花括号用于 dict，普通括号用于 tuple）：

• int 列表

• {str : int} 字典

• (str, int, int) 元组

• (str,) 元组

• set of str

如果只允许一组值，则用花括号将它们列出，并用逗号（后跟一个空格）分隔。如果值是有序的并且有顺序，请按此顺序列出。否则，如果有默认值，请先列出默认值：

如果类型在 Python 模块中定义，则必须指定模块：

• datetime.date

• datetime.datetime

• decimal.Decimal

如果类型在包中，则还必须指定模块：

• numpy.ndarray

• scipy.sparse.coo_matrix

如果类型是 pandas 类型，则除了 Series 和 DataFrame 外，还要指定 pandas：

• Series

• DataFrame

• pandas.Index

• pandas.Categorical

• pandas.arrays.SparseArray

如果确切类型不重要，但必须与 NumPy 数组兼容，则可以指定类似数组。如果接受任何可迭代的类型，则可使用 iterable：

• array-like

• iterable

如果接受多种类型，则用逗号分隔它们，除了最后两种类型，它们需要用‘or’分隔：

• int 或 float

• float, decimal.Decimal 或 None

• str 或 str 列表

如果 None 是可接受的值之一，则始终需要将其列为列表的最后一项。

对于轴，惯例是使用类似以下的内容：

• axis : {0 or ‘index’, 1 or ‘columns’, None}, 默认为 None ### Section 4: returns or yields

如果方法返回一个值，将在此部分中记录它。如果方法输出其输出，则也会记录在这里。

与“参数”相同的方式定义部分的标题。以“Returns”或“Yields”为名称，后跟一行连字符，连字符数量与前一个单词中的字母数量相同。

返回值的文档也与参数类似。但在这种情况下，除非方法返回或产生多个值（值的元组），否则不会提供名称。

“Returns”和“Yields”的类型与“Parameters”的类型相同。此外，描述必须以句点结束。

举例来说，对于单个数值：

def sample():
  """
 Generate and return a random number.

 The value is sampled from a continuous uniform distribution between
 0 and 1.

 Returns
 -------
 float
 Random number generated.
 """
    return np.random.random() 

对于多个数值：

import string

def random_letters():
  """
 Generate and return a sequence of random letters.

 The length of the returned string is also random, and is also
 returned.

 Returns
 -------
 length : int
 Length of the returned string.
 letters : str
 String of random letters.
 """
    length = np.random.randint(1, 10)
    letters = ''.join(np.random.choice(string.ascii_lowercase)
                      for i in range(length))
    return length, letters 

如果该方法产生其值：

def sample_values():
  """
 Generate an infinite sequence of random numbers.

 The values are sampled from a continuous uniform distribution between
 0 and 1.

 Yields
 ------
 float
 Random number generated.
 """
    while True:
        yield np.random.random() 
```  ### Section 5: see also

此部分用于让用户了解与所记录的功能相关的 pandas 功能。在极少数情况下，如果找不到任何相关方法或函数，可以跳过此部分。

一个明显的例子是 `head()` 和 `tail()` 方法。因为 `tail()` 在 `Series` 或 `DataFrame` 的末尾执行与 `head()` 类似的操作，而不是在开头，所以最好让用户知道这一点。

为了直观地了解什么可以被视为相关的，这里有一些例子：

+   `loc` 和 `iloc`，因为它们做的是相同的事情，但在一个情况下提供索引，在另一个情况下提供位置。

+   `max` 和 `min`，因为它们相反操作。

+   `iterrows`，`itertuples` 和 `items`，因为一个用户要查找遍历列的方法很容易最终找到遍历行的方法，反之亦然。

+   `fillna` 和 `dropna`，因为这两种方法都用于处理缺失值。

+   `read_csv` 和 `to_csv`，因为它们是互补的。

+   `merge` 和 `join`，因为一个是另一个的概括。

+   `astype` 和 `pandas.to_datetime`，因为用户可能正在阅读 `astype` 的文档以了解如何转换为日期，而转换方法是使用 `pandas.to_datetime`。

+   `where` 与 `numpy.where` 相关，因为其功能是基于它的。

在决定相关内容时，您应该主要凭借常识，并考虑对于阅读文档的用户来说什么可能有用，特别是对于经验较少的用户。

当与其他库（主要是 `numpy`）相关时，首先使用模块的名称（而不是别名，如 `np`）。如果函数位于不是主要的模块中，比如 `scipy.sparse`，则列出完整的模块（例如 `scipy.sparse.coo_matrix`）。

这个部分有一个标题，“See Also”（注意大写的 S 和 A），后面跟着由破折号构成的一行，并且前面有一个空行。

在标题之后，我们将为每个相关方法或函数添加一行，后跟一个空格、一个冒号、另一个空格和一个简短的描述，说明这个方法或函数做什么，在这个上下文中为什么是相关的，以及所记录的函数与被引用的函数之间的关键区别是什么。描述还必须以句点结束。

请注意在“Returns”和“Yields”中，描述位于类型之后的一行上。然而，在这个部分中，它位于同一行上，中间用冒号分隔。如果描述不适合在同一行上，则可以继续到其他必须进一步缩进的行上。

例如：

```py
class Series:
    def head(self):
  """
 Return the first 5 elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying the whole of it.

 Returns
 -------
 Series
 Subset of the original series with the 5 first values.

 See Also
 --------
 Series.tail : Return the last 5 elements of the Series.
 Series.iloc : Return a slice of the elements in the Series,
 which can also be used to return the first or last n.
 """
        return self.iloc[:5] 
```  ### Section 6: notes

这是一个可选部分，用于有关算法实现的注释，或者记录函数行为的技术方面。

如果您熟悉算法的实现，或者在编写函数示例时发现一些反直觉的行为，请随意跳过它。

本节遵循扩展摘要部分相同的格式。### 第 7 节：示例

这是文档字符串中最重要的部分之一，尽管它位于最后位置，因为人们通常通过示例而不是准确的解释更容易理解概念。

在文档字符串中的示例除了说明函数或方法的用法外，必须是有效的 Python 代码，以确定性方式返回给定输出，并且用户可以复制并运行。

示例以 Python 终端中的会话形式呈现。使用`>>>`来呈现代码。使用`...`表示从上一行继续的代码。输出立即在生成输出的最后一行代码之后呈现（中间没有空行）。可以在示例描述之前和之后添加空行以添加描述示例的注释。

展示示例的方式如下：

1.  导入所需的库（除了`numpy`和`pandas`）

1.  创建示例所需的数据

1.  展示一个非常基本的例子，给出最常见用例的概念

1.  添加带有说明的示例，说明参数如何用于扩展功能

一个简单的例子可能是：

```py
class Series:

    def head(self, n=5):
  """
 Return the first elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying all of it.

 Parameters
 ----------
 n : int
 Number of values to return.

 Return
 ------
 pandas.Series
 Subset of the original series with the n first values.

 See Also
 --------
 tail : Return the last n elements of the Series.

 Examples
 --------
 >>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
 ...                'Lion', 'Monkey', 'Rabbit', 'Zebra'])
 >>> ser.head()
 0   Ant
 1   Bear
 2   Cow
 3   Dog
 4   Falcon
 dtype: object

 With the ``n`` parameter, we can change the number of returned rows:

 >>> ser.head(n=3)
 0   Ant
 1   Bear
 2   Cow
 dtype: object
 """
        return self.iloc[:n] 

示例应尽可能简洁。在函数复杂性需要长示例的情况下，建议使用加粗标题的块。使用双星号**使文本加粗，就像**这个例子**中一样。

示例的约定

示例中的代码始终假定以未显示的这两行开头：

import numpy as np
import pandas as pd 

示例中使用的任何其他模块必须显式导入，每行一个（如PEP 8#imports中建议的），避免使用别名。避免过多的导入，但如果需要，首先导入标准库，然后是第三方库（如 matplotlib）。

当使用单个Series进行示例说明时，请使用名称ser，如果使用单个DataFrame进行说明，请使用名称df。对于索引，首选名称为idx。如果使用一组同质的Series或DataFrame，请将它们命名为ser1、ser2、ser3...或df1、df2、df3... 如果数据不是同质的，并且需要多个结构，请使用有意义的名称命名它们，例如df_main和df_to_join。

示例中使用的数据应尽可能紧凑。建议行数约为 4 行，但应根据具体示例合理确定。例如，在head方法中，建议使用大于 5 的值，以显示具有默认值的示例。如果进行mean操作，我们可以使用类似[1, 2, 3]的数据，这样很容易看出返回的值是平均值。

对于更复杂的示例（例如分组），避免使用没有解释的数据，比如随机数字矩阵，列为 A、B、C、D…而是使用一个有意义的示例，这样更容易理解概念。除非示例要求，否则使用动物的名称，以保持示例一致。并且它们的数字属性。

调用方法时，关键字参数head(n=3)优先于位置参数head(3)。

好：

class Series:

    def mean(self):
  """
 Compute the mean of the input.

 Examples
 --------
 >>> ser = pd.Series([1, 2, 3])
 >>> ser.mean()
 2
 """
        pass

    def fillna(self, value):
  """
 Replace missing values by ``value``.

 Examples
 --------
 >>> ser = pd.Series([1, np.nan, 3])
 >>> ser.fillna(0)
 [1, 0, 3]
 """
        pass

    def groupby_mean(self):
  """
 Group by index and return mean.

 Examples
 --------
 >>> ser = pd.Series([380., 370., 24., 26],
 ...               name='max_speed',
 ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
 >>> ser.groupby_mean()
 index
 falcon    375.0
 parrot     25.0
 Name: max_speed, dtype: float64
 """
        pass

    def contains(self, pattern, case_sensitive=True, na=numpy.nan):
  """
 Return whether each value contains ``pattern``.

 In this case, we are illustrating how to use sections, even
 if the example is simple enough and does not require them.

 Examples
 --------
 >>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
 >>> ser.contains(pattern='a')
 0    False
 1    False
 2     True
 3      NaN
 dtype: bool

 **Case sensitivity**

 With ``case_sensitive`` set to ``False`` we can match ``a`` with both
 ``a`` and ``A``:

 >>> s.contains(pattern='a', case_sensitive=False)
 0     True
 1    False
 2     True
 3      NaN
 dtype: bool

 **Missing values**

 We can fill missing values in the output using the ``na`` parameter:

 >>> ser.contains(pattern='a', na=False)
 0    False
 1    False
 2     True
 3    False
 dtype: bool
 """
        pass 

不好：

def method(foo=None, bar=None):
  """
 A sample DataFrame method.

 Do not import NumPy and pandas.

 Try to use meaningful data, when it makes the example easier
 to understand.

 Try to avoid positional arguments like in ``df.method(1)``. They
 can be all right if previously defined with a meaningful name,
 like in ``present_value(interest_rate)``, but avoid them otherwise.

 When presenting the behavior with different parameters, do not place
 all the calls one next to the other. Instead, add a short sentence
 explaining what the example shows.

 Examples
 --------
 >>> import numpy as np
 >>> import pandas as pd
 >>> df = pd.DataFrame(np.random.randn(3, 3),
 ...                   columns=('a', 'b', 'c'))
 >>> df.method(1)
 21
 >>> df.method(bar=14)
 123
 """
    pass 
```  #### 使示例通过 doctest 的提示

使示例通过验证脚本的 doctest 有时可能会有些棘手。以下是一些注意事项：

+   导入所有需要的库（除了 pandas 和 NumPy，它们已经作为`import pandas as pd`和`import numpy as np`导入）并定义你在示例中使用的所有变量。

+   尽量避免使用随机数据。然而，在某些情况下，随机数据可能是可以接受的，比如如果你正在记录的函数涉及概率分布，或者如果生成有意义的函数结果所需的数据量太大，手动创建会非常繁琐。在这些情况下，始终使用固定的随机种子使生成的示例可预测。例如：

    ```py
    >>> np.random.seed(42)
    >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)}) 
    ```

+   如果你有一个跨越多行的代码片段，你需要在后续行上使用‘…’：

    ```py
    >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
    ...                   columns=['A', 'B']) 
    ```

+   如果你想展示出引发异常的情况，可以这样做：

    ```py
    >>> pd.to_datetime(["712-01-01"])
    Traceback (most recent call last):
    OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00 
    ```

    包含“Traceback（最近一次调用的最后）:”是必要的，但对于实际错误只需提供错误名称即可。

+   如果结果中有一小部分可能会变化（例如对象表示中的哈希），可以使用`...`表示此部分。

    如果你想要展示`s.plot()`返回一个 matplotlib AxesSubplot 对象，这将导致 doctest 失败。

    ```py
    >>> s.plot()
    <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690> 
    ```

    但是，你可以这样做（注意需要添加的注释）

    ```py
    >>> s.plot()  
    <matplotlib.axes._subplots.AxesSubplot at ...> 
    ```  #### 示例中的图表

pandas 中有一些返回图表的方法。为了渲染文档中示例生成的图表，存在`.. plot::`指令。

要使用它，请将下一个代码放在“示例”标题后面，如下所示。生成文档时，图表将自动生成。

```py
class Series:
    def plot(self):
  """
 Generate a plot with the ``Series`` data.

 Examples
 --------

 .. plot::
 :context: close-figs

 >>> ser = pd.Series([1, 2, 3])
 >>> ser.plot()
 """
        pass 
```  ## 共享文档字符串

pandas 有一个系统，可以在类之间共享文档字符串，稍有不同。这有助于我们保持文档字符串一致，同时为用户阅读保持清晰。在编写时会增加一些复杂性。

每个共享的文档字符串都会有一个基础模板和变量，比如`{klass}`。稍后使用`doc`装饰器填充变量。最后，文档字符串也可以使用`doc`装饰器追加。

在本示例中，我们将正常创建一个父文档字符串（这类似于`pandas.core.generic.NDFrame`）。然后我们将有两个子文档字符串（像`pandas.core.series.Series`和`pandas.core.frame.DataFrame`）。我们将在此文档字符串中替换类名。

```py
class Parent:
    @doc(klass="Parent")
    def my_function(self):
  """Apply my function to {klass}."""
        ...

class ChildA(Parent):
    @doc(Parent.my_function, klass="ChildA")
    def my_function(self):
        ...

class ChildB(Parent):
    @doc(Parent.my_function, klass="ChildB")
    def my_function(self):
        ... 

结果文档字符串为

>>> print(Parent.my_function.__doc__)
Apply my function to Parent.
>>> print(ChildA.my_function.__doc__)
Apply my function to ChildA.
>>> print(ChildB.my_function.__doc__)
Apply my function to ChildB. 

注意：

1. 我们将父文档字符串“附加”到最初为空的子文档字符串上。

我们的文件通常会包含一个模块级别的_shared_doc_kwargs，其中包含一些常见的替换值（例如klass、axes等）。

您可以一次性进行替换和附加，例如

@doc(template, **_shared_doc_kwargs)
def my_function(self):
    ... 

其中template可能来自模块级别的_shared_docs字典，将函数名称映射到文档字符串。在可能的情况下，我们更喜欢使用doc，因为文档字符串编写过程略微接近正常。

查看pandas.core.generic.NDFrame.fillna以获取一个示例模板，以及填充版本的pandas.core.series.Series.fillna和pandas.core.generic.frame.fillna。

关于文档字符串和标准

Python 文档字符串是用于记录 Python 模块、类、函数或方法的字符串，以便程序员可以了解其功能，而无需阅读实现细节。

此外，从文档字符串自动生成在线（html）文档是一种常见做法。Sphinx用于此目的。

下一个示例给出了文档字符串的外观：

def add(num1, num2):
  """
 Add up two integer numbers.

 This function simply wraps the ``+`` operator, and does not
 do anything interesting, except for illustrating what
 the docstring of a very simple function looks like.

 Parameters
 ----------
 num1 : int
 First number to add.
 num2 : int
 Second number to add.

 Returns
 -------
 int
 The sum of ``num1`` and ``num2``.

 See Also
 --------
 subtract : Subtract one integer from another.

 Examples
 --------
 >>> add(2, 2)
 4
 >>> add(25, 0)
 25
 >>> add(10, -10)
 0
 """
    return num1 + num2 

存在一些关于文档字符串的标准，使它们更易于阅读，并允许它们轻松导出到其他格式，如 html 或 pdf。

每个 Python 文档字符串应遵循的第一个约定在PEP-257中定义。

由于 PEP-257 相当广泛，还存在其他更具体的标准。在 pandas 的情况下，遵循 NumPy 文档字符串约定。这些约定在本文档中有解释：

• numpydoc 文档字符串指南

numpydoc 是一个支持 NumPy 文档字符串约定的 Sphinx 扩展。

标准使用 reStructuredText（reST）。reStructuredText 是一种标记语言，允许在纯文本文件中编码样式。关于 reStructuredText 的文档可以在以下找到：

• Sphinx reStructuredText 入门

• 快速 reStructuredText 参考

• 完整的 reStructuredText 规范

pandas 有一些辅助功能，用于在相关类之间共享文档字符串，请参阅共享文档字符串。

本文档的其余部分将总结上述所有准则，并提供特定于 pandas 项目的额外约定。

编写文档字符串

一般规则

文档字符串必须用三个双引号定义。在文档字符串之前或之后不应留下空行。文本从开头引号的下一行开始。结束引号有自己的一行（这意味着它们不在最后一句的末尾）。

在罕见的情况下，文档字符串中会使用 reST 样式，如粗体文本或斜体文本，但通常会使用内联代码，该代码位于反引号之间。以下内容被视为内联代码：

• 参数的名称

• Python 代码，模块，函数，内置类型，字面值…（例如 os，list，numpy.abs，datetime.date，True）

• 一个 pandas 类（形式为 :class:pandas.Series``）

• 一个 pandas 方法（形式为 :meth:pandas.Series.sum``）

• 一个 pandas 函数（形式为 :func:pandas.to_datetime``）

注

为了仅显示链接类，方法或函数的最后组件，请以 ~ 为前缀。例如，:class:~pandas.Series`` 将链接到 pandas.Series，但只显示最后一部分 Series 作为链接文本。有关详细信息，请参阅 Sphinx 交叉引用语法。

好的：

def add_values(arr):
  """
 Add the values in ``arr``.

 This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

 Some sections are omitted here for simplicity.
 """
    return sum(arr) 

不好的：

def func():

  """Some function.

 With several mistakes in the docstring.

 It has a blank like after the signature ``def func():``.

 The text 'Some function' should go in the line after the
 opening quotes of the docstring, not in the same line.

 There is a blank line between the docstring and the first line
 of code ``foo = 1``.

 The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar 
```  ### 第一部分：简短摘要

简短摘要是一句话，简洁地表达函数的作用。

简短摘要必须以大写字母开头，以句点结束，并适合一行。它需要表达对象的作用，而不提供细节。对于函数和方法，简短摘要必须以不定式动词开头。

**好的：**

```py
def astype(dtype):
  """
 Cast Series type.

 This section will provide further details.
 """
    pass 

不好的：

def astype(dtype):
  """
 Casts Series type.

 Verb in third-person of the present simple, should be infinitive.
 """
    pass 

def astype(dtype):
  """
 Method to cast Series type.

 Does not start with verb.
 """
    pass 

def astype(dtype):
  """
 Cast Series type

 Missing dot at the end.
 """
    pass 

def astype(dtype):
  """
 Cast Series type from its current type to the new type defined in
 the parameter dtype.

 Summary is too verbose and doesn't fit in a single line.
 """
    pass 
```  ### 第二部分：扩展摘要

扩展摘要提供了函数的详细信息。它不应该详细说明参数，或者讨论实现注意事项，这些内容在其他部分中。

简短摘要和扩展摘要之间留有一个空行。扩展摘要中的每个段落都以句点结尾。

扩展摘要应提供有关函数为什么有用以及它们的用例的详细信息，如果不太通用的话。

```py
def unstack():
  """
 Pivot a row index to columns.

 When using a MultiIndex, a level can be pivoted so each value in
 the index becomes a column. This is especially useful when a subindex
 is repeated for the main index, and data is easier to visualize as a
 pivot table.

 The index level will be automatically removed from the index when added
 as columns.
 """
    pass 
```  ### 第三部分：参数

将在此部分添加参数的详细信息。此部分的标题为“参数”，下面是一行带有单词“参数”的连字符。标题之前留有一个空行，但标题后面没有空行，在单词“参数”所在行和带连字符的行之间也没有空行。

在标题之后，必须记录签名中的每个参数，包括 `*args` 和 `**kwargs`，但不包括 `self`。

参数由其名称定义，后面跟着一个空格，一个冒号，另一个空格，以及类型（或类型）。注意名称和冒号之间的空格很重要。`*args` 和 `**kwargs` 不定义类型，但所有其他参数必须定义类型。在参数定义之后，必须有一个带缩进的参数描述行，可以有多行。描述必须以大写字母开头，并以句点结束。

对于具有默认值的关键字参数，类型后面会列出默认值。在这种情况下，类型的确切形式将是“int，默认值为 0”。在某些情况下，解释默认参数的含义可能很有用，这可以在逗号后面添加“int，默认值为-1，表示所有 CPU”。

在默认值为`None`的情况下，意味着不会使用该值。与“str，default None”相比，更倾向于写成“str，optional”。当`None`是一个被使用的值时，我们将保持形式“str，default None”。例如，在`df.to_csv(compression=None)`中，`None`不是一个被使用的值，但意味着压缩是可选的，如果未提供压缩，则不使用压缩。在这种情况下，我们将使用“str，optional”。仅在像`func(value=None)`和`None`被使用与`0`或`foo`相同的方式时，我们将指定“str，int 或 None，默认为 None”。

**好的：**

```py
class Series:
    def plot(self, kind, color='blue', **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Parameters
 ----------
 kind : str
 Kind of matplotlib plot.
 color : str, default 'blue'
 Color name or rgb code.
 **kwargs
 These parameters will be passed to the matplotlib plotting
 function.
 """
        pass 

不好：

class Series:
    def plot(self, kind, **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Note the blank line between the parameters title and the first
 parameter. Also, note that after the name of the parameter ``kind``
 and before the colon, a space is missing.

 Also, note that the parameter descriptions do not start with a
 capital letter, and do not finish with a dot.

 Finally, the ``**kwargs`` parameter is missing.

 Parameters
 ----------

 kind: str
 kind of matplotlib plot
 """
        pass 

参数类型

在指定参数类型时，可以直接使用 Python 内置数据类型（Python 类型优先于更冗长的字符串、整数、布尔值等）：

• 整数

• 浮点数

• str

• 布尔值

对于复杂类型，定义子类型。对于dict和tuple，由于存在多种类型，我们使用括号来帮助阅读类型（大括号用于dict，普通括号用于tuple）：

• int 列表

• {str: int}字典

• （str、int、int）元组

• （str，）元组

• str 集合

如果只有一组允许的值，请用大括号列出它们，并用逗号（后跟一个空格）分隔。如果这些值是有序的，并且它们有一个顺序，请按此顺序列出它们。否则，如果有默认值，请首先列出默认值：

如果类型在 Python 模块中定义，则必须指定模块：

• datetime.date

• datetime.datetime

• decimal.Decimal

如果类型在一个包中，也必须指定模块：

• numpy.ndarray

• scipy.sparse.coo_matrix

如果类型是 pandas 类型，则除了 Series 和 DataFrame 外，还要指定 pandas：

• Series

• DataFrame

• pandas.Index

• pandas.Categorical

• pandas.arrays.SparseArray

如果确切的类型不相关，但必须与 NumPy 数组兼容，则可以指定 array-like。如果接受可迭代的任何类型，可以使用 iterable：

• array-like

• 可迭代对象

如果接受的类型超过一个，用逗号分隔它们，除了最后两种类型，它们需要用单词'or'分隔：

• 整数或浮点数

• 浮点数、decimal.Decimal 或 None

• str 或 str 列表

如果None是接受的值之一，则它始终需要是列表中的最后一个。

对于轴，惯例是使用类似于：

• 轴：{0 或'index'，1 或'columns'，None}，默认为 None ### 第 4 节：返回或产出

如果方法返回一个值，将在本节中记录它。如果方法产生其输出。

该部分的标题将与“参数”相同。使用名称“返回”或“产出”，后跟一行与前一个单词中的字母数相同的连字符。

返回的文档与参数类似。但在这种情况下，不提供名称，除非该方法返回或产出多个值（值的元组）。

“返回”和“产出”的类型与“参数”的类型相同。此外，描述必须以句点结束。

例如，对于单个值：

def sample():
  """
 Generate and return a random number.

 The value is sampled from a continuous uniform distribution between
 0 and 1.

 Returns
 -------
 float
 Random number generated.
 """
    return np.random.random() 

当有多个值时：

import string

def random_letters():
  """
 Generate and return a sequence of random letters.

 The length of the returned string is also random, and is also
 returned.

 Returns
 -------
 length : int
 Length of the returned string.
 letters : str
 String of random letters.
 """
    length = np.random.randint(1, 10)
    letters = ''.join(np.random.choice(string.ascii_lowercase)
                      for i in range(length))
    return length, letters 

如果方法产生它的值：

def sample_values():
  """
 Generate an infinite sequence of random numbers.

 The values are sampled from a continuous uniform distribution between
 0 and 1.

 Yields
 ------
 float
 Random number generated.
 """
    while True:
        yield np.random.random() 
```  ### 第 5 节：参见

本节用于让用户了解与正在文档化的功能相关的 pandas 功能。在极少数情况下，如果找不到任何相关的方法或函数，可以跳过此节。

一个明显的例子是 `head()` 和 `tail()` 方法。由于 `tail()` 做的是 `head()` 的等效操作，但是在 `Series` 或 `DataFrame` 的末尾而不是开头，因此让用户知道这一点是很好的。

为了直观地了解什么可以被视为相关，这里有一些例子：

+   `loc` 和 `iloc`，因为它们做的事情相同，但在一个情况下提供索引，在另一个情况下提供位置。

+   `max` 和 `min`，因为它们起相反的作用。

+   `iterrows`、`itertuples` 和 `items`，因为用户可能在寻找按列迭代的方法时最终找到了按行迭代的方法，反之亦然。

+   `fillna` 和 `dropna`，因为这两种方法都用于处理缺失值。

+   `read_csv` 和 `to_csv`，因为它们是互补的。

+   `merge` 和 `join`，因为其中一个是另一个的概括。

+   `astype` 和 `pandas.to_datetime`，因为用户可能在阅读 `astype` 的文档以了解如何转换为日期，而做法是使用 `pandas.to_datetime`。

+   `where` 和 `numpy.where` 相关，因为它的功能基于它。

决定相关内容时，你应该主要运用常识，考虑对于阅读文档的用户而言哪些内容可能有用，尤其是对于那些经验较少的用户。

当与其他库（主要是 `numpy`）相关时，首先使用模块的名称（而不是别名，如 `np`）。如果函数在一个不是主要的模块中，比如 `scipy.sparse`，则列出完整的模块（例如 `scipy.sparse.coo_matrix`）。

本节有一个标题，“参见”（注意大写的 S 和 A），后面跟着带有连字符的行，并且前面有一个空行。

在标题之后，我们会为每个相关的方法或函数添加一行，后跟一个空格，一个冒号，另一个空格，以及一个简短的描述，说明此方法或函数在这个上下文中的相关性，以及所记录的函数与被引用的函数之间的关键差异。描述还必须以句点结束。

注意在“返回”和“产出”中，描述位于类型之后的行。然而，在本节中，它位于同一行上，中间有一个冒号。如果描述不适合在同一行上，可以延续到其他行，必须进一步缩进。

例如：

```py
class Series:
    def head(self):
  """
 Return the first 5 elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying the whole of it.

 Returns
 -------
 Series
 Subset of the original series with the 5 first values.

 See Also
 --------
 Series.tail : Return the last 5 elements of the Series.
 Series.iloc : Return a slice of the elements in the Series,
 which can also be used to return the first or last n.
 """
        return self.iloc[:5] 
```  ### 第 6 节：注解

这是一个可选的部分，用于记录算法实现的注解，或者记录函数行为的技术方面。

请随意跳过，除非您熟悉算法的实现，或者在为函数编写示例时发现一些违反直觉的行为。

本节遵循与扩展摘要部分相同的格式。### 第 7 节：示例

这是文档字符串中最重要的部分之一，尽管通常被放在最后的位置，因为人们更容易通过示例而不是准确的解释来理解概念。

文档字符串中的示例，除了说明函数或方法的用法外，还必须是有效的 Python 代码，以确定的方式返回给定的输出，并且可以由用户复制并运行。

示例以 Python 终端中的会话形式呈现。`>>>`用于展示代码。`...`用于继续上一行的代码。输出立即在生成输出的最后一行代码之后呈现（中间没有空行）。在示例之前和之后可以添加描述示例的注释，中间有空行。

呈现示例的方式如下：

1.  导入所需的库（除了`numpy`和`pandas`）

1.  创建示例所需的数据

1.  展示一个非常基本的示例，以便了解最常见的用例

1.  添加带有说明的示例，说明参数如何用于扩展功能

一个简单的示例可能是：

```py
class Series:

    def head(self, n=5):
  """
 Return the first elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying all of it.

 Parameters
 ----------
 n : int
 Number of values to return.

 Return
 ------
 pandas.Series
 Subset of the original series with the n first values.

 See Also
 --------
 tail : Return the last n elements of the Series.

 Examples
 --------
 >>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
 ...                'Lion', 'Monkey', 'Rabbit', 'Zebra'])
 >>> ser.head()
 0   Ant
 1   Bear
 2   Cow
 3   Dog
 4   Falcon
 dtype: object

 With the ``n`` parameter, we can change the number of returned rows:

 >>> ser.head(n=3)
 0   Ant
 1   Bear
 2   Cow
 dtype: object
 """
        return self.iloc[:n] 

示例应尽可能简洁。在函数复杂性需要长示例的情况下，建议使用粗体标题的块。使用双星**使文本加粗，就像**这个例子**中一样。

示例的约定

示例中的代码始终假定以这两行开头，但没有显示：

import numpy as np
import pandas as pd 

示例中使用的任何其他模块必须显式导入，每行一个（如在PEP 8#imports中推荐的）并避免使用别名。避免过多的导入，但如果需要，首先是来自标准库的导入，然后是第三方库（如 matplotlib）。

当用单个Series说明示例时，请使用名称ser，如果用单个DataFrame说明，则使用名称df。对于索引，idx是首选名称。如果使用一组同类的Series或DataFrame，请将它们命名为ser1、ser2、ser3...或df1、df2、df3... 如果数据不同类，并且需要多个结构，请用有意义的名称命名它们，例如df_main和df_to_join。

示例中使用的数据应尽可能紧凑。推荐行数约为 4，但对于特定示例，使其为合理数字。例如，在head方法中，它需要比 5 更高，以显示具有默认值的示例。如果进行mean，我们可以使用类似[1, 2, 3]的东西，这样很容易看到返回的值是均值。

对于更复杂的示例（例如分组），避免使用没有解释的数据，比如由随机数字组成的带有列 A、B、C、D 的矩阵…… 而是使用一个有意义的示例，这样更容易理解概念。除非示例要求，否则使用动物的名称，以保持示例的一致性。以及它们的数值属性。

在调用方法时，关键字参数 head(n=3) 优先于位置参数 head(3)。

好：

class Series:

    def mean(self):
  """
 Compute the mean of the input.

 Examples
 --------
 >>> ser = pd.Series([1, 2, 3])
 >>> ser.mean()
 2
 """
        pass

    def fillna(self, value):
  """
 Replace missing values by ``value``.

 Examples
 --------
 >>> ser = pd.Series([1, np.nan, 3])
 >>> ser.fillna(0)
 [1, 0, 3]
 """
        pass

    def groupby_mean(self):
  """
 Group by index and return mean.

 Examples
 --------
 >>> ser = pd.Series([380., 370., 24., 26],
 ...               name='max_speed',
 ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
 >>> ser.groupby_mean()
 index
 falcon    375.0
 parrot     25.0
 Name: max_speed, dtype: float64
 """
        pass

    def contains(self, pattern, case_sensitive=True, na=numpy.nan):
  """
 Return whether each value contains ``pattern``.

 In this case, we are illustrating how to use sections, even
 if the example is simple enough and does not require them.

 Examples
 --------
 >>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
 >>> ser.contains(pattern='a')
 0    False
 1    False
 2     True
 3      NaN
 dtype: bool

 **Case sensitivity**

 With ``case_sensitive`` set to ``False`` we can match ``a`` with both
 ``a`` and ``A``:

 >>> s.contains(pattern='a', case_sensitive=False)
 0     True
 1    False
 2     True
 3      NaN
 dtype: bool

 **Missing values**

 We can fill missing values in the output using the ``na`` parameter:

 >>> ser.contains(pattern='a', na=False)
 0    False
 1    False
 2     True
 3    False
 dtype: bool
 """
        pass 

不好：

def method(foo=None, bar=None):
  """
 A sample DataFrame method.

 Do not import NumPy and pandas.

 Try to use meaningful data, when it makes the example easier
 to understand.

 Try to avoid positional arguments like in ``df.method(1)``. They
 can be all right if previously defined with a meaningful name,
 like in ``present_value(interest_rate)``, but avoid them otherwise.

 When presenting the behavior with different parameters, do not place
 all the calls one next to the other. Instead, add a short sentence
 explaining what the example shows.

 Examples
 --------
 >>> import numpy as np
 >>> import pandas as pd
 >>> df = pd.DataFrame(np.random.randn(3, 3),
 ...                   columns=('a', 'b', 'c'))
 >>> df.method(1)
 21
 >>> df.method(bar=14)
 123
 """
    pass 
```  #### 通过 doctest 测试的示例的提示

使示例通过验证脚本的 doctest 有时可能会很棘手。以下是一些注意点：

+   导入所有所需的库（除了 pandas 和 NumPy，它们已经被导入为 `import pandas as pd` 和 `import numpy as np`），并定义您在示例中使用的所有变量。

+   尽量避免使用随机数据。但在某些情况下，使用随机数据可能是可以的，比如您要记录的函数处理概率分布，或者如果需要创建使函数结果有意义的数据量太大，手动创建它非常麻烦。在这些情况下，始终使用固定的随机种子使生成的示例可预测。例如：

    ```py
    >>> np.random.seed(42)
    >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)}) 
    ```

+   如果您有一个跨越多行的代码片段，您需要在连续的行上使用 '...'：

    ```py
    >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
    ...                   columns=['A', 'B']) 
    ```

+   如果要显示引发异常的情况，可以执行：

    ```py
    >>> pd.to_datetime(["712-01-01"])
    Traceback (most recent call last):
    OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00 
    ```

    必须包含“Traceback (most recent call last):”，但对于实际错误，只需提供错误名称即可。

+   如果结果中有一个可以变化的小部分（例如对象表示中的哈希），则可以使用 `...` 表示此部分。

    如果要显示 `s.plot()` 返回一个 matplotlib AxesSubplot 对象，这将导致 doctest 失败。

    ```py
    >>> s.plot()
    <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690> 
    ```

    然而，您可以执行以下操作（注意需要添加的注释）

    ```py
    >>> s.plot()  
    <matplotlib.axes._subplots.AxesSubplot at ...> 
    ```  #### 示例中的绘图

pandas 中有一些返回绘图的方法。为了渲染文档中示例生成的图形，存在 `.. plot::` 指令。

要使用它，请在“示例”标题之后放置下面显示的代码。构建文档时将自动生成图形。

```py
class Series:
    def plot(self):
  """
 Generate a plot with the ``Series`` data.

 Examples
 --------

 .. plot::
 :context: close-figs

 >>> ser = pd.Series([1, 2, 3])
 >>> ser.plot()
 """
        pass 
```  ### 通用规则

文档字符串必须用三个双引号定义。在文档字符串之前或之后不应该留下空行。文本从开头引号的下一行开始。闭合引号有它们自己的一行（这意味着它们不是在最后一个句子的末尾）。

在文档字符串中，偶尔会使用 reST 样式，比如粗体文本或斜体文本，但常见的是使用内联代码，这些代码被放置在反引号之间。以下内容被视为内联代码：

+   参数的名称

+   Python 代码、模块、函数、内置函数、类型、字面值……（例如 `os`、`list`、`numpy.abs`、`datetime.date`、`True`）

+   一个 pandas 类（以 `:class:`pandas.Series`` 形式）

+   一个 pandas 方法（以 `:meth:`pandas.Series.sum`` 形式）

+   一个 pandas 函数（以 `:func:`pandas.to_datetime`` 形式）

注意

要仅显示链接类、方法或函数的最后一个组件，请在其前面加上`~`。例如，`:class:`~pandas.Series``将链接到`pandas.Series`，但只显示最后部分`Series`作为链接文本。有关详细信息，请参阅[Sphinx 交叉引用语法](https://www.sphinx-doc.org/en/stable/domains.html#cross-referencing-syntax)。

**好：**

```py
def add_values(arr):
  """
 Add the values in ``arr``.

 This is equivalent to Python ``sum`` of :meth:`pandas.Series.sum`.

 Some sections are omitted here for simplicity.
 """
    return sum(arr) 

不好：

def func():

  """Some function.

 With several mistakes in the docstring.

 It has a blank like after the signature ``def func():``.

 The text 'Some function' should go in the line after the
 opening quotes of the docstring, not in the same line.

 There is a blank line between the docstring and the first line
 of code ``foo = 1``.

 The closing quotes should be in the next line, not in this one."""

    foo = 1
    bar = 2
    return foo + bar 

第 1 节：简短摘要

简短摘要是一句话，简洁地表达函数的作用。

简短摘要必须以大写字母开头，以句点结束，并适合在一行内。它需要表达对象的作用，而不提供细节。对于函数和方法，简短摘要必须以不定式动词开头。

好：

def astype(dtype):
  """
 Cast Series type.

 This section will provide further details.
 """
    pass 

不好：

def astype(dtype):
  """
 Casts Series type.

 Verb in third-person of the present simple, should be infinitive.
 """
    pass 

def astype(dtype):
  """
 Method to cast Series type.

 Does not start with verb.
 """
    pass 

def astype(dtype):
  """
 Cast Series type

 Missing dot at the end.
 """
    pass 

def astype(dtype):
  """
 Cast Series type from its current type to the new type defined in
 the parameter dtype.

 Summary is too verbose and doesn't fit in a single line.
 """
    pass 

第 2 节：扩展摘要

扩展摘要提供了函数的详细信息。不应该深入讨论参数的细节，或者讨论实现注意事项，这些应该放在其他部分。

简短摘要和扩展摘要之间留有一个空行。扩展摘要中的每个段落都以句点结束。

扩展摘要应提供函数的用途及其用例的详细信息，如果不是太通用的话。

def unstack():
  """
 Pivot a row index to columns.

 When using a MultiIndex, a level can be pivoted so each value in
 the index becomes a column. This is especially useful when a subindex
 is repeated for the main index, and data is easier to visualize as a
 pivot table.

 The index level will be automatically removed from the index when added
 as columns.
 """
    pass 

第 3 节：参数

参数的详细信息将在此部分添加。此部分的标题为“参数”，后跟��个下划线线，下划��下面是单词“参数”的每个字母。在部分标题之前留有一个空行，但在之后不留空行，在单词“参数”下划线和下划线之间也不留空行。

在标题之后，必须记录签名中的每个参数，包括*args和**kwargs，但不包括self。

参数由其名称定义，后跟一个空格，一个冒号，另一个空格，以及类型（或类型）。请注意名称和冒号之间的空格很重要。对于*args和**kwargs不定义类型，但对于所有其他参数必须定义类型。在参数定义之后，需要有一行参数描述，缩进，并且可以有多行。描述必须以大写字母开头，并以句点结束。

对于具有默认值的关键字参数，将在类型末尾的逗号后列出默认值。在这种情况下，类型的确切形式将是“int，默认值 0”。在某些情况下，解释默认参数的含义可能很有用，可以在逗号后添加“int，默认值-1，表示所有 cpu”。

在默认值为None的情况下，意味着该值将不被使用。与“str，默认为 None”相比，更倾向于写“str，可选”。当None是一个被使用的值时，我们将保持“str，默认为 None”的形式。例如，在df.to_csv(compression=None)中，None不是一个被使用的值，而是表示压缩是可选的，如果不提供，则不使用压缩。在这种情况下，我们将使用“str，可选”。只有在像func(value=None)和None被用作0或foo一样使用时，我们将指定“str，int 或 None，默认为 None”。

好：

class Series:
    def plot(self, kind, color='blue', **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Parameters
 ----------
 kind : str
 Kind of matplotlib plot.
 color : str, default 'blue'
 Color name or rgb code.
 **kwargs
 These parameters will be passed to the matplotlib plotting
 function.
 """
        pass 

不好：

class Series:
    def plot(self, kind, **kwargs):
  """
 Generate a plot.

 Render the data in the Series as a matplotlib plot of the
 specified kind.

 Note the blank line between the parameters title and the first
 parameter. Also, note that after the name of the parameter ``kind``
 and before the colon, a space is missing.

 Also, note that the parameter descriptions do not start with a
 capital letter, and do not finish with a dot.

 Finally, the ``**kwargs`` parameter is missing.

 Parameters
 ----------

 kind: str
 kind of matplotlib plot
 """
        pass 

参数类型

在指定参数类型时，可以直接使用 Python 内置数据类型（优先使用 Python 类型，而不是更冗长的字符串、整数、布尔值等）：

• 整数

• 浮点数

• 字符串

• 布尔值

对于复杂类型，定义子类型。对于dict和tuple，由于存在多种类型，我们使用括号来帮助阅读类型（大括号用于dict，普通括号用于tuple）：

• 整数列表

• 字典

• 元组（str，int，int）

• 元组（str，）

• 字符串集合

在只允许一组值的情况下，将它们用大括号分隔并用逗号（后跟一个空格）分隔。如果值是有序的并且有顺序，请按此顺序列出。否则，如果有默认值，请首先列出默认值：

如果类型在 Python 模块中定义，则必须指定模块：

• datetime.date

• datetime.datetime

• decimal.Decimal

如果类型在一个包中，必须同时指定模块：

• numpy.ndarray

• scipy.sparse.coo_matrix

如果类型是 pandas 类型，则还需指定 pandas，除了 Series 和 DataFrame：

• Series

• 数据框

• pandas.Index

• pandas.Categorical

• pandas.arrays.SparseArray

如果确切的类型不重要，但必须与 NumPy 数组兼容，则可以指定类似数组。如果接受任何可迭代的类型，则可以使用可迭代：

• 类似数组

• 可迭代

如果接受多种类型，请用逗号分隔，除了最后两种类型，它们需要用“或”分隔：

• 整数或浮点数

• 浮点数、decimal.Decimal 或 None

• 字符串或字符串列表

如果None是被接受的值之一，则它总是需要在列表中的最后。

对于轴，惯例是使用类似于：

• 轴：{0 或‘索引’，1 或‘列’，无}，默认无 #### 参数类型

在指定参数类型时，可以直接使用 Python 内置数据类型（优先使用 Python 类型，而不是更冗长的字符串、整数、布尔值等）：

• 整数

• 浮点数

• 字符串

• 布尔值

对于复杂类型，定义子类型。对于dict和tuple，由于存在多种类型，我们使用括号来帮助阅读类型（大括号用于dict，普通括号用于tuple）：

• 整数列表

• 字典

• 元组（str，int，int）

• 元组（str，）

• 字符串集合

如果只允许一组值，则用大括号列出它们，并用逗号（后跟一个空格）分隔。如果值是有序的并且有顺序，请按此顺序列出它们。否则，如果有默认值，请首先列出默认值：

如果类型在 Python 模块中定义，则必须指定模块：

• datetime.date

• datetime.datetime

• decimal.Decimal

如果类型在一个包中，则必须同时指定模块：

• numpy.ndarray

• scipy.sparse.coo_matrix

如果类型是 pandas 类型，则除了 Series 和 DataFrame 外，还要指定 pandas：

• Series

• DataFrame

• pandas.Index

• pandas.Categorical

• pandas.arrays.SparseArray

如果确切类型不相关，但必须与 NumPy 数组兼容，则可以指定类似数组。如果接受可以迭代的任何类型，则可以使用 iterable：

• 类似数组

• 可迭代的

如果接受多种类型，请用逗号分隔它们，除了最后两种类型需要用“or”分隔的单词之外：

• int 或 float

• float、decimal.Decimal 或 None

• str 或 str 的列表

如果 None 是可接受的值之一，则它始终需要在列表中的最后。

对于轴，惯例是使用类似以下的内容：

• axis：{0 或 ‘index’，1 或 ‘columns’，None}，默认为 None

第四节：返回或产出

如果方法返回一个值，则将在此部分中记录该值。如果方法也产生其输出。

节的标题将与“Parameters”相同的方式定义。使用名称“Returns”或“Yields”，后跟一行连字符，连字符数与前面单词的字母数相同。

返回的文档也类似于参数。但是在这种情况下，除非方法返回或产出多个值（一组值的元组），否则不会提供名称。

“Returns”和“Yields”的类型与“Parameters”的类型相同。此外，描述必须以句点结束。

例如，对于单个值：

def sample():
  """
 Generate and return a random number.

 The value is sampled from a continuous uniform distribution between
 0 and 1.

 Returns
 -------
 float
 Random number generated.
 """
    return np.random.random() 

带有多个值：

import string

def random_letters():
  """
 Generate and return a sequence of random letters.

 The length of the returned string is also random, and is also
 returned.

 Returns
 -------
 length : int
 Length of the returned string.
 letters : str
 String of random letters.
 """
    length = np.random.randint(1, 10)
    letters = ''.join(np.random.choice(string.ascii_lowercase)
                      for i in range(length))
    return length, letters 

如果方法产生其值：

def sample_values():
  """
 Generate an infinite sequence of random numbers.

 The values are sampled from a continuous uniform distribution between
 0 and 1.

 Yields
 ------
 float
 Random number generated.
 """
    while True:
        yield np.random.random() 

第五节：参见

这个部分用于让用户了解与正在文档化的功能相关的 pandas 功能。在极少数情况下，如果根本找不到任何相关的方法或函数，可以跳过此部分。

显而易见的例子是 head() 和 tail() 方法。由于 tail() 执行的操作与 head() 相当，但是在 Series 或 DataFrame 的末尾而不是开头进行，因此让用户知道这一点是很好的。

为了对什么可以被认为是相关的有所了解，这里有一些例子：

• loc 和 iloc，因为它们执行相同的操作，但在一个情况下提供索引，在另一个情况下提供位置

• max 和 min，因为它们执行相反的操作

• iterrows、itertuples 和 items，因为很容易让寻找用于迭代列的方法的用户最终进入用于迭代行的方法，反之亦然

• fillna 和 dropna，因为这两种方法都用于处理缺失值

• read_csv 和 to_csv，因为它们是互补的

• merge 和 join，因为其中一个是另一个的泛化

• astype 和 pandas.to_datetime，因为用户可能正在阅读 astype 的文档以了解如何转换为日期，而正确的方法是使用 pandas.to_datetime

• where 与 numpy.where 相关，因为它的功能是基于它的

在决定相关内容时，你应该主要依靠常识，思考对阅读文档的用户有用的内容，特别是对于经验较少的用户。

当涉及到其他库（主要是 numpy）时，首先使用模块的名称（而不是别名像 np）。如果函数在不是主要的模块中，比如 scipy.sparse，列出完整的模块（例如 scipy.sparse.coo_matrix）。

这一部分有一个标题，“参见”（注意大写的 S 和 A），后面跟着由破折号组成的行，并在前面有一个空行。

在标题之后，我们将为每个相关的方法或函数添加一行，后面跟着一个空格，一个冒号，另一个空格，以及一个简短的描述，说明这个方法或函数在这个上下文中的相关性，以及文档化函数和被引用函数之间的主要区别是什么。描述还必须以句点结束。

请注意，在“Returns”和“Yields”中，描述位于类型的下一行上。然而，在这一部分中，它位于同一行上，中间有一个冒号。如果描述不适合在同一行上，则可以继续到其他行，这些行必须进一步缩进。

例如：

class Series:
    def head(self):
  """
 Return the first 5 elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying the whole of it.

 Returns
 -------
 Series
 Subset of the original series with the 5 first values.

 See Also
 --------
 Series.tail : Return the last 5 elements of the Series.
 Series.iloc : Return a slice of the elements in the Series,
 which can also be used to return the first or last n.
 """
        return self.iloc[:5] 

第 6 部分：注意事项

这是一个可选部分，用于关于算法实现的笔记，或者记录函数行为的技术细节。

可以跳过这部分，除非你熟悉算法的实现，或者在编写函数示例时发现了一些反直觉的行为。

这一部分的格式与扩展摘要部分相同。

第 7 部分：示例

尽管放在最后位置，但这是 docstring 中最重要的部分之一，因为人们通常通过示例而不是准确的解释更好地理解概念。

文档字符串中的示例除了说明函数或方法的使用方法外，还必须是有效的 Python 代码，以确定的方式返回给定的输出，并且可以被用户复制并运行。

示例被呈现为 Python 终端中的会话。 >>> 用于呈现代码。 ... 用于从上一行继续的代码。输出立即在生成输出的最后一行代码之后呈现（中间没有空行）。在示例之前和之后可以添加描述示例的注释，这些注释用空行分隔。

示例的呈现方式如下：

1. 导入所需的库（除了 numpy 和 pandas）

2. 创建示例所需的数据

3. 显示一个非常基本的示例，给出最常见用例的概念

4. 添加带有解释的示例，说明参数如何用于扩展功能

一个简单的示例可能是：

class Series:

    def head(self, n=5):
  """
 Return the first elements of the Series.

 This function is mainly useful to preview the values of the
 Series without displaying all of it.

 Parameters
 ----------
 n : int
 Number of values to return.

 Return
 ------
 pandas.Series
 Subset of the original series with the n first values.

 See Also
 --------
 tail : Return the last n elements of the Series.

 Examples
 --------
 >>> ser = pd.Series(['Ant', 'Bear', 'Cow', 'Dog', 'Falcon',
 ...                'Lion', 'Monkey', 'Rabbit', 'Zebra'])
 >>> ser.head()
 0   Ant
 1   Bear
 2   Cow
 3   Dog
 4   Falcon
 dtype: object

 With the ``n`` parameter, we can change the number of returned rows:

 >>> ser.head(n=3)
 0   Ant
 1   Bear
 2   Cow
 dtype: object
 """
        return self.iloc[:n] 

示例应尽可能简洁。在函数复杂性要求较长示例的情况下，建议使用加粗标题的块。使用双星号**使文本加粗，如**这个示例**。

示例的约定

示例中的代码始终假定以未显示的这两行开头：

import numpy as np
import pandas as pd 

示例中使用的任何其他模块都必须显式导入，每行一个（如PEP 8#imports中推荐的），避免使用别名。避免过多的导入，但如果需要，标准库的导入优先，然后是第三方库（如 matplotlib）。

当用单个Series说明示例时，请使用名称ser，如果用单个DataFrame说明，请使用名称df。对于索引，首选名称为idx。如果使用一组同质的Series或DataFrame，请将它们命名为ser1、ser2、ser3…或df1、df2、df3…如果数据不是同质的，并且需要多个结构，则使用有意义的名称，例如df_main和df_to_join。

示例中使用的数据应尽可能紧凑。建议行数约为 4 行，但应根据具体示例的情况确定。例如，在head方法中，建议行数大于 5，以显示具有默认值的示例。如果进行mean操作，我们可以使用类似[1, 2, 3]的数据，这样很容易看出返回的值是平均值。

对于更复杂的示例（例如分组），避免使用没有解释的数据，比如具有 A、B、C、D 列的随机数矩阵…而是使用一个有意义的示例，这样更容易理解概念。除非示例需要，否则使用动物的名称，以保持示例的一致性。以及它们的数值属性。

在调用该方法时，优先使用关键字参数head(n=3)而不是位置参数head(3)。

好的做法：

class Series:

    def mean(self):
  """
 Compute the mean of the input.

 Examples
 --------
 >>> ser = pd.Series([1, 2, 3])
 >>> ser.mean()
 2
 """
        pass

    def fillna(self, value):
  """
 Replace missing values by ``value``.

 Examples
 --------
 >>> ser = pd.Series([1, np.nan, 3])
 >>> ser.fillna(0)
 [1, 0, 3]
 """
        pass

    def groupby_mean(self):
  """
 Group by index and return mean.

 Examples
 --------
 >>> ser = pd.Series([380., 370., 24., 26],
 ...               name='max_speed',
 ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
 >>> ser.groupby_mean()
 index
 falcon    375.0
 parrot     25.0
 Name: max_speed, dtype: float64
 """
        pass

    def contains(self, pattern, case_sensitive=True, na=numpy.nan):
  """
 Return whether each value contains ``pattern``.

 In this case, we are illustrating how to use sections, even
 if the example is simple enough and does not require them.

 Examples
 --------
 >>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
 >>> ser.contains(pattern='a')
 0    False
 1    False
 2     True
 3      NaN
 dtype: bool

 **Case sensitivity**

 With ``case_sensitive`` set to ``False`` we can match ``a`` with both
 ``a`` and ``A``:

 >>> s.contains(pattern='a', case_sensitive=False)
 0     True
 1    False
 2     True
 3      NaN
 dtype: bool

 **Missing values**

 We can fill missing values in the output using the ``na`` parameter:

 >>> ser.contains(pattern='a', na=False)
 0    False
 1    False
 2     True
 3    False
 dtype: bool
 """
        pass 

不好的做法：

def method(foo=None, bar=None):
  """
 A sample DataFrame method.

 Do not import NumPy and pandas.

 Try to use meaningful data, when it makes the example easier
 to understand.

 Try to avoid positional arguments like in ``df.method(1)``. They
 can be all right if previously defined with a meaningful name,
 like in ``present_value(interest_rate)``, but avoid them otherwise.

 When presenting the behavior with different parameters, do not place
 all the calls one next to the other. Instead, add a short sentence
 explaining what the example shows.

 Examples
 --------
 >>> import numpy as np
 >>> import pandas as pd
 >>> df = pd.DataFrame(np.random.randn(3, 3),
 ...                   columns=('a', 'b', 'c'))
 >>> df.method(1)
 21
 >>> df.method(bar=14)
 123
 """
    pass 
```  #### 通过 doctests 的提示

通过 doctests 的验证脚本使示例通过有时可能会有些棘手。以下是一些注意事项：

+   导入所有需要的库（除了 pandas 和 NumPy，它们已经作为`import pandas as pd`和`import numpy as np`导入）并定义您在示例中使用的所有变量。

+   尽量避免使用随机数据。但在某些情况下，随机数据可能是可以接受的，比如您正在记录处理概率分布的函数，或者如果需要大量数据才能使函数结果有意义，手动创建数据非常繁琐。在这些情况下，始终使用固定的随机种子使生成的示例可预测。例如：

    ```py
    >>> np.random.seed(42)
    >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)}) 
    ```

+   如果您有一个跨越多行的代码片段，需要在续行上使用‘…’：

    ```py
    >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
    ...                   columns=['A', 'B']) 
    ```

+   如果您想展示引发异常的情况，可以执行以下操作：

    ```py
    >>> pd.to_datetime(["712-01-01"])
    Traceback (most recent call last):
    OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00 
    ```

    包含 “Traceback (most recent call last):” 是必不可少的，但实际错误只需提供错误名称即可。

+   如果结果中有一小部分可能会变化（例如，对象表示中的哈希值），您可以使用 `...` 来表示这部分。

    如果要显示 `s.plot()` 返回 matplotlib AxesSubplot 对象，这将导致文档测试失败。

    ```py
    >>> s.plot()
    <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690> 
    ```

    但是，您可以执行以下操作（注意需要添加的注释）

    ```py
    >>> s.plot()  
    <matplotlib.axes._subplots.AxesSubplot at ...> 
    ```  #### 示例中的绘图

pandas 中有一些返回图形的方法。为了渲染文档中示例生成的图形，存在 `.. plot::` 指令。

要使用它，请将下一行代码放在“示例”标题后，如下所示。当构建文档时，图形将自动生成。

```py
class Series:
    def plot(self):
  """
 Generate a plot with the ``Series`` data.

 Examples
 --------

 .. plot::
 :context: close-figs

 >>> ser = pd.Series([1, 2, 3])
 >>> ser.plot()
 """
        pass 
```  #### 示例的约定

示例中的代码始终假定以未显示的这两行开头：

```py
import numpy as np
import pandas as pd 

示例中使用的任何其他模块都必须明确导入，每行一个（如PEP 8#imports中建议的），避免使用别名。避免过多的导入，但如果需要，标准库的导入首先进行，然后是第三方库（例如 matplotlib）。

在用单个 Series 说明示例时，使用名称 ser，如果用单个 DataFrame 说明，使用名称 df。对于索引，首选名称是 idx。如果使用一组同质的 Series 或 DataFrame，请将它们命名为 ser1、ser2、ser3… 或 df1、df2、df3… 如果数据不同质，并且需要多个结构，则使用有意义的名称，例如 df_main 和 df_to_join。

示例中使用的数据应尽可能紧凑。建议行数约为 4，但根据具体示例选择一个合理的数字。例如，在 head 方法中，需要高于 5，以显示默认值的示例。如果执行 mean，我们可以使用类似 [1, 2, 3] 的内容，这样很容易看到返回的值是平均值。

对于更复杂的示例（例如分组），避免使用没有解释的数据，比如随机数矩阵，列为 A、B、C、D… 而是使用有意义的示例，这样更容易理解概念。除非示例需要，否则使用动物的名称，以保持示例的一致性。以及它们的数值属性。

在调用方法时，关键字参数 head(n=3) 优先于位置参数 head(3)。

好的：

class Series:

    def mean(self):
  """
 Compute the mean of the input.

 Examples
 --------
 >>> ser = pd.Series([1, 2, 3])
 >>> ser.mean()
 2
 """
        pass

    def fillna(self, value):
  """
 Replace missing values by ``value``.

 Examples
 --------
 >>> ser = pd.Series([1, np.nan, 3])
 >>> ser.fillna(0)
 [1, 0, 3]
 """
        pass

    def groupby_mean(self):
  """
 Group by index and return mean.

 Examples
 --------
 >>> ser = pd.Series([380., 370., 24., 26],
 ...               name='max_speed',
 ...               index=['falcon', 'falcon', 'parrot', 'parrot'])
 >>> ser.groupby_mean()
 index
 falcon    375.0
 parrot     25.0
 Name: max_speed, dtype: float64
 """
        pass

    def contains(self, pattern, case_sensitive=True, na=numpy.nan):
  """
 Return whether each value contains ``pattern``.

 In this case, we are illustrating how to use sections, even
 if the example is simple enough and does not require them.

 Examples
 --------
 >>> ser = pd.Series('Antelope', 'Lion', 'Zebra', np.nan)
 >>> ser.contains(pattern='a')
 0    False
 1    False
 2     True
 3      NaN
 dtype: bool

 **Case sensitivity**

 With ``case_sensitive`` set to ``False`` we can match ``a`` with both
 ``a`` and ``A``:

 >>> s.contains(pattern='a', case_sensitive=False)
 0     True
 1    False
 2     True
 3      NaN
 dtype: bool

 **Missing values**

 We can fill missing values in the output using the ``na`` parameter:

 >>> ser.contains(pattern='a', na=False)
 0    False
 1    False
 2     True
 3    False
 dtype: bool
 """
        pass 

不好的：

def method(foo=None, bar=None):
  """
 A sample DataFrame method.

 Do not import NumPy and pandas.

 Try to use meaningful data, when it makes the example easier
 to understand.

 Try to avoid positional arguments like in ``df.method(1)``. They
 can be all right if previously defined with a meaningful name,
 like in ``present_value(interest_rate)``, but avoid them otherwise.

 When presenting the behavior with different parameters, do not place
 all the calls one next to the other. Instead, add a short sentence
 explaining what the example shows.

 Examples
 --------
 >>> import numpy as np
 >>> import pandas as pd
 >>> df = pd.DataFrame(np.random.randn(3, 3),
 ...                   columns=('a', 'b', 'c'))
 >>> df.method(1)
 21
 >>> df.method(bar=14)
 123
 """
    pass 

通过文档测试使示例通过的提示

使示例在验证脚本中通过文档测试有时可能会很棘手。以下是一些注意事项：

• 导入所有需要的库（除了 pandas 和 NumPy，它们已经被导入为 import pandas as pd 和 import numpy as np），并定义您在示例中使用的所有变量。

• 尽量避免使用随机数据。但是在某些情况下，使用随机数据可能是可以的，比如您要记录的函数处理概率分布，或者使函数结果有意义所需的数据量太大，手动创建这些数据非常麻烦。在这些情况下，始终使用固定的随机种子使生成的示例可预测。例如：

  >>> np.random.seed(42)
  >>> df = pd.DataFrame({'normal': np.random.normal(100, 5, 20)}) 
  

• 如果您有一个跨越多行的代码片段，您需要在连续的行上使用…：

  >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], index=['a', 'b', 'c'],
  ...                   columns=['A', 'B']) 
  

• 如果您想展示引发异常的情况，可以这样做：

  >>> pd.to_datetime(["712-01-01"])
  Traceback (most recent call last):
  OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 712-01-01 00:00:00 
  

  对于实际错误，包含“Traceback（最近的调用最后）”是至关重要的，但实际错误只需要错误名称即可。

• 如果结果中有一小部分可能会变化（例如对象表示中的哈希），您可以使用...表示此部分。

  如果您想展示 s.plot() 返回 matplotlib AxesSubplot 对象，这将导致 doctest 失败

  >>> s.plot()
  <matplotlib.axes._subplots.AxesSubplot at 0x7efd0c0b0690> 
  

  然而，您可以这样做（注意需要添加的注释）

  >>> s.plot()  
  <matplotlib.axes._subplots.AxesSubplot at ...> 
  

示例中的图表

pandas 中有一些返回图表的方法。为了渲染文档中示例生成的图表，存在.. plot::指令。

要使用它，请按照下面所示的“示例”标题后面放置下一个代码。生成文档时，图将自动生成。

class Series:
    def plot(self):
  """
 Generate a plot with the ``Series`` data.

 Examples
 --------

 .. plot::
 :context: close-figs

 >>> ser = pd.Series([1, 2, 3])
 >>> ser.plot()
 """
        pass 

共享文档字符串

pandas 有一个用于在类之间共享文档字符串的系统，其中略有不同。这帮助我们保持文档字符串的一致性，同时保持用户阅读时的清晰度。在编写时会带来一些复杂性的代价。

每个共享文档字符串都将具有基本模板和变量，如{klass}。稍后使用doc装饰器填充变量。最后，文档字符串也可以使用doc装饰器附加。

在这个例子中，我们将以正常方式创建一个父文档字符串（这类似于 pandas.core.generic.NDFrame）。然后我们会有两个子文档字符串（像 pandas.core.series.Series 和 pandas.core.frame.DataFrame）。我们将在这个文档字符串中替换类名。

class Parent:
    @doc(klass="Parent")
    def my_function(self):
  """Apply my function to {klass}."""
        ...

class ChildA(Parent):
    @doc(Parent.my_function, klass="ChildA")
    def my_function(self):
        ...

class ChildB(Parent):
    @doc(Parent.my_function, klass="ChildB")
    def my_function(self):
        ... 

结果文档字符串是

>>> print(Parent.my_function.__doc__)
Apply my function to Parent.
>>> print(ChildA.my_function.__doc__)
Apply my function to ChildA.
>>> print(ChildB.my_function.__doc__)
Apply my function to ChildB. 

注意：

1. 我们将父文档字符串“附加”到最初为空的子文档字符串上。

我们的文件通常包含一个模块级别的_shared_doc_kwargs，其中包含一些常见的替换值（如klass、axes等）。

您可以使用类似于以下内容的一次性替换和附加：

@doc(template, **_shared_doc_kwargs)
def my_function(self):
    ... 

其中template可能来自一个模块级别的_shared_docs字典，将函数名映射到文档字符串。在可能的情况下，我们更喜欢使用doc，因为文档字符串编写过程稍微接近于正常。

参见 pandas.core.generic.NDFrame.fillna 以获取示例模板，以及填充版本的 pandas.core.series.Series.fillna 和 pandas.core.generic.frame.fillna。