如何为Python自定义模块函数实现类似内置help()的帮助效果

Python内置的help()函数不需要你额外实现打印逻辑，它会自动读取目标对象的元信息（函数签名、所属模块、定义位置等）和文档字符串（docstring），只要按规范写好docstring，就能达到和pandas.read_excel等内置/第三方库函数完全一致的帮助输出效果。

具体实现步骤 #

• 第一步：在函数定义的第一行（紧接def行，中间不能有空行）写入三引号包裹的docstring，按规范说明函数功能、参数、返回值、异常、使用示例即可。
• 第二步：如果需要模块级的帮助提示，在.py文件的最开头（所有导入、函数定义之前）写入模块级docstring即可。
• 第三步：直接调用help(你的函数名)就能输出标准化帮助内容，不需要额外开发。

代码示例 #

针对你给出的shanky_calculate_average函数，按照pandas使用的NumPy/reST风格docstring修改后代码如下：

def shanky_calculate_average(*args):
    """计算输入数值的算术平均值
    接收任意数量的数值参数，返回所有参数的算术平均值，参数为空时触发除零错误。

    Parameters
    ----------
    *args : int or float
        任意个参与平均值计算的数值参数，不支持非数值类型传入。

    Returns
    -------
    float
        所有输入参数的算术平均值。

    Raises
    ------
    ZeroDivisionError
        未传入任何参数时触发。
    TypeError
        传入非数值类型参数、无法执行sum求和时触发。

    Examples
    --------
    >>> shanky_calculate_average(1, 2, 3, 4)
    2.5
    >>> shanky_calculate_average(10, 20)
    15.0
    """
    my_average  = sum(args) / len(args)
    return my_average

效果说明 #

写完上述内容后，在交互环境导入该函数，执行help(shanky_calculate_average)，输出结构和pandas等标准库/第三方库的帮助完全一致：

1. 开头自动显示函数签名、所属模块、定义文件路径
2. 之后依次展示你写的函数功能说明、参数列表、返回值说明、异常说明、使用示例
3. 排版完全遵循Python内置帮助的统一格式

补充说明 #

如果需要自定义特殊的帮助输出逻辑，可以通过修改对象的__doc__属性、或者为自定义类实现__help__()方法实现，但绝大多数场景下，按规范写标准docstring完全可以满足需求，不需要额外开发逻辑。

内容的提问来源于stack exchange，提问作者Aryan Satyam