当参数是像 Pandas DataFrame 这样的包对象时，Docstrings Python 函数答案

【问题标题】：Docstrings Python Function when parameters are package objects like Pandas DataFrame当参数是像 Pandas DataFrame 这样的包对象时，Docstrings Python 函数
【发布时间】：2021-12-28 05:15:23
【问题描述】：

我想知道当参数之一是包对象（例如 pandas DataFrame）时如何记录 python 函数。

我用这个方法，但是 PyCharm(python IDE) 不明白。

def foo(df , no , l_int):
'''
Parameters
-------------
df:Pandas DataFrame
no:int 
l_int:list of int

Returns
-------------
'''

在 PyCharm 中显示如下：

def foo(df: Any,
        no: int,
        l_int: list[int]) -> None

这是解决此问题的标准方法吗？谢谢。

【问题讨论】：

标签： python code-documentation

【解决方案1】：

让我告诉你一个一般的经验法则。如果您的参数像 DataFrame 一样是封装的数据，则通过显示参数数据类型的内部结构或返回数据类型来举例说明，例如

"""
Parameters
-------------
df:Pandas DataFrame : (here some explanation)
no:int 
l_int:list of int

Examples:

df: 
{
 Give a detailed example by showing the internal data of the datatype so that anyone reading the docstring knows exactly what is encapsulated by this datatype
}

-------------
"""

代码布局

始终使用四个空格来缩进代码。不要使用标签，标签引入混乱，最好不要考虑。
包装您的代码，使行数不超过 79 个字符。这有助于使用小型显示器的用户，并可以在较大的显示器上并排打开多个代码文件。
垂直对齐文本时，第一行不应有参数

空格

在顶级函数和类周围使用 2 个空行。
使用 1 个空行分隔函数内的大块代码。
类方法定义前 1 个空行。
避免多余的空格。
谨慎使用空行。
始终在两侧用空格包围二元运算符，但要合理分组。
请勿在关键字参数或默认参数值中使用空格。
请勿使用空格来排列运算符。
不鼓励在同一行使用多个语句。
避免在任何地方出现尾随空格

在大多数情况下，评论应该是完整的句子。
使 cmets 保持最新
用“Strunk & White”英文书写
内联 cmets 应至少用两个空格分隔
语句必须以“#”和一个空格开头。
块 cmets 应缩进到与代码相同的级别
紧随其后。
块 cmets 中的每一行都以“#”开头。
为所有公共模块、函数、类和
方法。
文档字符串以 """ 开头和结尾，例如 """ 文档字符串。 """。
单行文档字符串可以在同一行。
文档字符串应将方法或函数的效果描述为
命令。
文档字符串应以句点结尾。
记录类时，在文档字符串后插入一个空行。
最后一个 """ 应该单独一行

有关此主题的更多详细信息。请阅读PEP 257或here的摘要

【讨论】：

【解决方案2】：

这是自 Python 3.5 以来的标准方式，尽管自引入以来已经发展了很多。

我要做的一件事是将 df 的类型更改为 pandas.DataFrame 以使其更具表现力。

此外，PyCharm 似乎很好地理解了您的方法。重新格式化只是添加类型声明。

【讨论】：

【解决方案3】：

Any 不是描述性类型注释。您需要一个 Pandas 数据框，或 pd.DataFrame，但 PyCharm 似乎无法推断出这一点。

函数头应为：

import pandas as pd
def foo(df: pd.DataFrame,
        no: int,
        l_int: list[int]) -> None

【讨论】：