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

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

这是自 Python 3.5 以来的标准方式，尽管它自推出以来已经有了很大的发展。

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

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

Answer 2

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

"""
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
}

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

代码布局

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

白色space

在顶级函数和 classes 周围使用 2 个空行。
使用 1 个空行分隔函数内的大块代码。
class 方法定义前有 1 个空行。
避免多余的白色space。
少用空行。
始终在两边用 space 包围二元运算符，但要合理地将它们分组。
不要在关键字参数或默认参数值中使用 space。
不要用白色space排列运算符
不鼓励在同一行中使用多个语句。
避免在任何地方尾随白色space

大多数情况下评论应该是完整的句子。
及时更新评论
用“Strunk & White”英文写作
行内注释应与
语句必须以‘#’和一个space开头。
块注释应缩进到与代码相同的水平
紧随其后。
块注释中的每一行都以“#”开头。
为所有 public 模块、函数、classes 和
方法。
文档字符串以“””开头和结尾，例如“””一个文档字符串。 "".
单行文档字符串可以全部在同一行。
文档字符串应该将方法或函数的效果描述为
命令。
文档字符串应该以句号结尾。
记录 class 时，在文档字符串后插入一个空行。
最后一个“””应该单独占一行

有关此主题的更多详细信息。请阅读PEP 257 or it summary by here

Answer 3

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

函数头应为：

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

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

Docstrings Python Function when parameters are package objects like Pandas DataFrame

python

code-documentation