pandas 文档字符串指南# 关于文档字符串和标准# Python 文档字符串是用于记录 Python 模块、类、函数或方法的字符串，因此程序员可以理解它的作用，而无需阅读实现的细节。 此外，从文档字符串自动生成在线 (html) 文档也是一种常见的做法。狮身人面像就是为了这个目的。 下一个示例给出了文档字符串的外观： 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。 PEP-257中定义了每个 Python 文档字符串应遵循的第一个约定 。 由于 PEP-257 相当广泛，因此还存在其他更具体的标准。对于 pandas，遵循 NumPy 文档字符串约定。这些约定在本文档中进行了解释： numpydoc 文档字符串指南 numpydoc 是一个 Sphinx 扩展，用于支持 NumPy 文档字符串约定。 该标准使用 reStructuredText (reST)。 reStructuredText 是一种标记语言，允许在纯文本文件中编码样式。有关 reStructuredText 的文档可以在以下位置找到： Sphinx reStructuredText 入门 快速重构文本参考 完整的重构文本规范 pandas 有一些帮助程序用于在相关类之间共享文档字符串，请参阅 共享文档字符串。 本文档的其余部分将总结上述所有指南，并将提供特定于 pandas 项目的其他约定。 编写文档字符串# 一般规则＃ 文档字符串必须用三个双引号定义。文档字符串之前或之后不应留下空行。文本从左引号后面的下一行开始。结束引号有自己的一行（这意味着它们不在最后一句话的末尾）。 在极少数情况下，文档字符串中会使用诸如粗体文本或斜体之类的休息样式，但通常会在反引号之间使用内联代码。以下内容被视为内联代码： 参数名称 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 部分：简短摘要# 简短摘要是一个句子，以简洁的方式表达了该函数的功能。 简短的摘要必须以大写字母开头，以点结尾，并且适合单行。它需要表达对象的作用而不提供细节。对于函数和方法，简短摘要必须以不定式动词开头。 好的： 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 部分：参数# 参数的详细信息将在本节中添加。该部分的标题为“Parameters”，后面是一行，“Parameters”一词的每个字母下都有一个连字符。节标题之前留有一个空行，但之后不留空行，并且在“参数”一词与连字符的行之间也不留空行。 标题后，必须记录签名中的每个参数，包括 *args和**kwargs，但不包括self。 参数由其名称定义，后跟一个空格、一个冒号、另一个空格和一个或多个类型。请注意，名称和冒号之间的空格很重要。没有为*args和定义类型**kwargs，但必须为所有其他参数定义类型。参数定义后，需要有一行参数说明，缩进，可以多行。描述必须以大写字母开头，以点结尾。 对于具有默认值的关键字参数，默认值将列在类型末尾的逗号后面。在这种情况下，类型的确切形式将是“int，默认0”。在某些情况下，解释默认参数的含义可能很有用，可以在逗号“int，default -1，表示所有 cpu”之后添加该参数。 如果默认值为None，则表示不会使用该值。相反，最好写成.当使用一个值时，我们将保留“str，默认无”的形式。例如，在 中，不是正在使用的值，而是表示压缩是可选的，如果未提供，则不使用压缩。在这种情况下我们将使用.只有在像and 的使用方式与or 的使用方式相同的情况下 ，我们才会指定“str、int 或 None，默认 None”。"str, default None""str, optional"Nonedf.to_csv(compression=None)None"str, optional"func(value=None)None0foo 好的： 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} 的字典 (str, int, int) 的元组 (str,) 的元组 一组 str 如果只允许一组值，请将它们列在大括号中并用逗号分隔（后跟空格）。如果这些值是有序的并且有顺序，则按此顺序列出它们。否则，首先列出默认值（如果有）： {0, 10, 25} {'简单', '高级'} {'低中高'} {'猫', '狗', '鸟'} 如果类型是在 Python 模块中定义的，则必须指定该模块： 日期时间.日期 日期时间.日期时间 小数.小数 如果类型位于包中，则还必须指定模块： numpy.ndarray scipy.sparse.coo_matrix 如果类型是 pandas 类型，还指定除 Series 和 DataFrame 之外的 pandas： 系列 数据框 pandas.Index pandas.Categorical pandas.arrays.SparseArray 如果确切的类型不相关，但必须与 NumPy 数组兼容，则可以指定 array-like。如果接受任何可以迭代的类型，则可以使用iterable： 类数组 可迭代的 如果接受多种类型，则用逗号分隔它们，最后两种类型除外，需要用“或”一词分隔： 整型或浮点型 浮点数、小数。小数或无 str 或 str 列表 如果None是可接受的值之一，则它始终需要是列表中的最后一个。 对于轴，约定是使用类似以下内容： axis : {0 或 'index', 1 或 'columns', None}, 默认 None 第 4 节：回报或收益# 如果该方法返回一个值，它将记录在本节中。此外，如果该方法产生其输出。 该部分的标题将以与“参数”相同的方式定义。名称“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() 第 5 节：另请参阅# 本节用于让用户了解与正在记录的功能相关的 pandas 功能。在极少数情况下，如果根本找不到相关的方法或函数，则可以跳过本节。 一个明显的例子是head()和tail()方法。正如tail()等效的 as但在orhead()的末尾 而不是在开头一样，最好让用户知道它。SeriesDataFrame 为了直观地了解什么可以被认为是相关的，这里有一些例子： 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 节：示例# 这是文档字符串中最重要的部分之一，尽管被放置在最后位置，因为人们通常通过示例比通过准确的解释更好地理解概念。 文档字符串中的示例除了说明函数或方法的用法之外，还必须是有效的 Python 代码，以确定的方式返回给定的输出，并且可以由用户复制和运行。 示例在 Python 终端中以会话形式呈现。>>>用于呈现代码。...用于从上一行继续的代码。输出在生成输出的最后一行代码之后立即显示（中间没有空行）。描述示例的注释可以在其前后添加空行。 举例说明的方式如下： 导入所需的库（除了numpy和pandas） 创建示例所需的数据 展示一个非常基本的示例，让您了解最常见的用例 添加带有说明的示例，说明如何将参数用于扩展功能 一个简单的例子可以是： 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] 示例应尽可能简洁。如果函数的复杂性需要较长的示例，建议使用标题为粗体的块。使用双星**将文本加粗，如 中。**this example** 示例的约定# 假设示例中的代码始终以这两行（未显示）开头： import numpy as np import pandas as pd 示例中使用的任何其他模块都必须显式导入，每行一个（按照PEP 8#imports）并避免使用别名。避免过多导入，但如果需要，首先从标准库导入，然后是第三方库（如 matplotlib）。 当用单个示例说明时Series使用名称ser，如果用单个示例说明则DataFrame使用名称df。对于索引， idx是首选名称。如果使用一组同构Series或 ，请将它们命名为, , ... 或, , ... 如果数据不是同构的，并且需要多个结构，则将它们命名为有意义的名称，例如和 。DataFrameser1ser2ser3df1df2df3df_maindf_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 pdimport 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. 注意： 我们将父文档字符串“附加”到子文档字符串，这些文档字符串最初是空的。 _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 以获得填充版本。