python - 当参数是 Pandas DataFrame 等包对象时的 Docstrings Python 函数

Question

我想知道当其中一个参数是包的对象(例如 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

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

Answer 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 个空行。
• 避免多余的空格。
• 谨慎使用空行。
• 始终在二元运算符两边留一个空格，但要合理地将它们分组。
• 不要在关键字参数或默认参数值中使用空格。
• 不要使用空格来排列运算符。
• 不鼓励在同一行中使用多个语句。
• 避免在任何地方使用尾随空格

评论

• 在大多数情况下，评论应该是完整的句子。
• 及时更新评论
• 用“Strunk & White”英语写作
• 行内注释应至少由两个空格分隔
• 声明必须以“#”和一个空格开头。
• block 注释应与代码缩进到同一级别
• 紧随其后。
• block 注释中的每一行都以“#”开头。
• 为所有公共(public)模块、函数、类和编写文档字符串
• 方法。
• 文档字符串以“””开头和结尾，例如“””一个文档字符串。 “”。
• 单行文档字符串可以全部在同一行。
• 文档字符串应该将方法或函数的效果描述为
• 命令。
• 文档字符串应该以句号结尾。
• 记录类时，在文档字符串后插入一个空行。
• 最后一个“””单独占一行

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