Python中不可忽视的docstring妙用

def greet(name):
    """返回一个问候信息。
    参数：
    name (str): 被问候者的名字。
    返回：
    str: 问候信息。
    """
    return f"Hello, {name}!"

def calculate_area(radius):
    """计算圆的面积。
    这是一个多行docstring示例。
    可以在这里详细描述函数的行为和注意事项。
    参数：
    radius (float): 圆的半径。
    返回：
    float: 圆的面积。
    """
    import math
    return math.pi * radius ** 2

def add(x, y):
    """计算两个数的和。
    Args:
        x (int or float): 第一个数。
        y (int or float): 第二个数。
    Returns:
        int or float: 两个数的和。
    """
    return x + y

def multiply(a, b):
    """
    计算两个数的乘积。
    Parameters
    ----------
    a : int or float
        第一个数。
    b : int or float
        第二个数。
    Returns
    -------
    int or float
        两个数的乘积。
    """
    return a * b

def divide(x, y):
    """
    计算两个数的商。
    :param x: 被除数。
    :type x: int or float
    :param y: 除数。
    :type y: int or float
    :return: 商。
    :rtype: float
    :raises ZeroDivisionError: 当除数为零时抛出。
    """
    if y == 0:
        raise ZeroDivisionError("除数不能为零")
    return x / y

"""
math_operations模块
这个模块提供了简单的数学运算函数，包括加法、减法、乘法和除法。
"""
 
def add(x, y):
    """计算两个数的和。"""
    return x + y
 
def subtract(x, y):
    """计算两个数的差。"""
    return x - y

class Calculator:
    """一个简单的计算器类。
    这个类提供了基本的数学运算功能，包括加法和减法。
    """
 
    def add(self, x, y):
        """计算两个数的和。"""
        return x + y
 
    def subtract(self, x, y):
        """计算两个数的差。"""
        return x - y

def multiply(x, y):
    """计算两个数的乘积。
    参数：
    x (int or float): 第一个数。
    y (int or float): 第二个数。
    返回：
    int or float: 两个数的乘积。
    """
    return x * y

def subtract(x, y):
    """计算两个数的差。"""
    return x - y
 
help(subtract)

def divide(x, y):
    """计算两个数的商。"""
    return x / y
 
print(divide.__doc__)

def calculate_statistics(data):
    """计算给定数据集的基本统计量。
    该函数返回数据集的平均值、中位数和标准差。
    参数：
    data (list of float): 一个包含数值的列表。
    返回：
    dict: 包含'average'，'median'和'std_dev'键的字典，分别对应平均值、中位数和标准差。
    异常：
    ValueError: 当数据集为空时抛出。
    """
    if not data:
        raise ValueError("数据集不能为空")
 
    average = sum(data) / len(data)
    median = sorted(data)[len(data) // 2]
    variance = sum((x - average) ** 2 for x in data) / len(data)
    std_dev = variance ** 0.5
 
    return {"average": average, "median": median, "std_dev": std_dev}