三引号

三引号中的内容在 Python 中有特殊的用途，尤其是在你的代码示例中。让我用最简单的方式解释清楚：

---

三引号的本质

三引号 """...""" 是 多行字符串，可以包含换行和任意文本。但在特定场景下，它被赋予了特殊意义：

场景	作用
普通字符串	存储多行文本（例如长消息、SQL 查询等）
函数/类的文档字符串	描述代码功能（用 help() 或 IDE 查看时会显示）
doctest 测试	在文档字符串中嵌入可执行的测试用例（你代码中的用法！）

---

案例解析：

这段代码实现了一个计算平均值的函数 average，并用 doctest 模块进行简单测试。

# 测试模块
def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> average([20, 30, 70])  # 直接返回值，无需 print
    40.0
    >>> average([])  # 测试空列表
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return sum(values) / len(values)

if __name__ == "__main__":
    import doctest

    doctest_testmod = doctest.testmod(verbose=True)
    print(doctest_testmod)#TestResults(failed=0, attempted=1)

 

你的代码中三引号的作用

在你的代码中，三引号内的内容既是 文档字符串（用于说明函数用途），又包含 doctest 测试用例。具体分析如下：

1. 文档说明部分

def average(values):
    """Computes the arithmetic mean of a list of numbers.
    # 这里是一个简单的功能描述
    """
    return sum(values) / len(values)

• 用 help(average) 或 IDE 提示时会显示这段文本，解释函数功能。

2. doctest 测试部分

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> print(average([20, 30, 70]))  # 测试用例
    40.0
    """
    return sum(values) / len(values)

• >>> 开头的行：表示要执行的代码（模拟用户在 Python 交互式环境中的输入）。

• 下一行：表示期望的输出结果。

• doctest 模块会自动执行这些代码，并验证输出是否符合预期。

---

代码运行时的具体行为

当你执行以下代码时：

import doctest
testmod = doctest.testmod()

会发生以下事情：

1. 扫描所有文档字符串：查找 >>> 开头的代码片段。

2. 执行这些代码：像在 Python 交互式环境中一样运行它们。

3. 验证输出：检查实际输出是否与文档字符串中写的预期结果一致。

4. 报告结果：如果有测试失败，会显示错误信息。

---

对比普通注释 vs 文档测试

普通注释（无功能作用）

def average(values):
    # 这是一个计算平均值的函数
    # 参数 values 是数字列表
    return sum(values) / len(values)

• 只是给人看的文本，代码运行时完全忽略。

文档测试（有功能作用）

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> average([20, 30, 70])  # 这是一个测试用例！
    40.0
    """
    return sum(values) / len(values)

• 这段文本不仅是文档，还是自动化测试的一部分！

• 运行 doctest.testmod() 时会自动执行 >>> 后的代码，并检查结果是否为 40.0。

---

实际演示

假设你的代码保存在 average.py 中：

def average(values):
    """Computes the arithmetic mean of a list of numbers.

    >>> average([20, 30, 70])
    40.0
    >>> average([])
    Traceback (most recent call last):
        ...
    ZeroDivisionError: division by zero
    """
    return sum(values) / len(values)

if __name__ == "__main__":
    import doctest
    doctest.testmod(verbose=True)

运行结果：

• 若测试通过：

  Trying:
      average([20, 30, 70])
  Expecting:
      40.0
  ok
  Trying:
      average([])
  Expecting:
      Traceback (most recent call last):
          ...
      ZeroDivisionError: division by zero
  ok
  2 tests passed.

  若测试失败（例如函数返回错误值）：

  Failed example:
      average([20, 30, 70])
  Expected:
      40.0
  Got:
      42.0

  关键总结

  三引号内容类型	作用
  普通文档字符串	解释代码功能（给人看）
  doctest 测试	嵌入可执行测试用例（给机器运行）
  两者结合	既能生成友好的文档，又能自动验证代码正确性！

  在你的代码中，三引号内的内容既是文档，又是测试用例，实现了 “自文档化测试” 的效果。这是 Python 中非常优雅的设计！