Python三引号('''和""")的两种核心用法：多行字符串与文档注释

在 Python 语法体系中，由连续三个单引号 ''' 或三个双引号 """ 括起来的表达式，本质上都是多行字符串字面量（Multiline String Literal）。在实际工程开发中，三引号主要承担两个截然不同的核心职责：一是作为保留换行与格式的多行字符串变量，用于处理大段文本、模板与 SQL 语句；二是作为模块、类与函数的文档注释（Docstring），由 Python 解释器在编译期绑定到代码对象的 __doc__ 属性，供运行时反射与文档工具链解析。本文将围绕这两个核心维度，系统拆解它们的语法机制、底层编译差异、典型用法以及常见陷阱。

一、三引号作为多行字符串：格式保留与文本构建

日常编写单行字符串时，我们习惯使用单引号 '...' 或双引号 "..."。当文本中出现换行或双引号混用时，开发者往往需要书写繁琐的 \n 转义符或反斜杠转义。三引号从语法层面彻底消除了这种摩擦，它允许文本直接在编辑器中跨越多行，并将换行符和空行如实记录到字符串内部。

1. 换行与引号嵌套的基本特性

在三引号内部，可以直接换行，也可以自由使用单引号和双引号而无需转义，只要内部不连续出现三个闭合引号即可。例如在拼接 SQL 语句或 HTML 片段时：

# 示例 1：使用三引号构建包含格式的 SQL 语句
sql_query = """
SELECT id, user_name, created_at
FROM users
WHERE status = 'active'
  AND role = "admin"
ORDER BY created_at DESC;
"""

print(repr(sql_query))
# 输出结果首尾会带有换行符：'\nSELECT id, user_name, created_at\nFROM users\n...'

仔细观察上面的输出可以发现：在 """ 之后直接回车换行，该换行符会成为字符串内容的第一字符。同理，闭合三引号前的一行换行也会被计入。如果不希望首尾产生多余的空行，可以使用行尾反斜杠 \ 来抵消换行，或者使用字符串的 strip() 方法。

2. 缩进陷阱与处理技巧

在类或函数内部定义多行字符串时，为了维持代码缩进的美观，开发者常常会将每行文字向右对齐。然而，三引号并不会自动过滤这些前置空格，这会导致字符串实际内容包含大量不需要的前导空格：

import textwrap

def generate_report():
    # 错误示范：代码缩进会直接被写入字符串
    bad_msg = """
        尊敬的用户：
        您的账号已激活。
    """
    
    # 正确做法：配合标准库 textwrap.dedent 剔除公共缩进
    good_msg = textwrap.dedent("""
        尊敬的用户：
        您的账号已激活。
    """).strip()
    return good_msg

print(repr(generate_report()))
# 输出：'尊敬的用户：\n您的账号已激活。'

二、三引号作为文档注释：Docstring 的原理与约定

虽然三引号在语法上只是字符串，但当它出现在模块最顶部、类定义内部的第一行、或者函数/方法体内部的第一行时，Python 解释器会赋予它特殊的语法语义——将其标记为文档字符串（Docstring）。

1. __doc__ 属性与编译机制

当 Python 编译器解析代码时，如果发现代码块的第一个可执行语句是字面量字符串，它不会生成常规的 POP_TOP 丢弃指令，而是直接将该字符串绑定到该代码对象的 __doc__ 属性上。这个属性在运行时始终可用，支撑了 Python 强大的自省（Introspection）体系。

def calculate_tax(amount: float, rate: float = 0.05) -> float:
    """计算含税总额。

    Args:
        amount: 基础金额，必须大于等于 0。
        rate: 税率，默认为 5%。

    Returns:
        float: 计算后的含税总额。
    """
    return amount * (1.0 + rate)

# 运行时自省读取
print(calculate_tax.__doc__)

# 交互式查看格式化文档
help(calculate_tax)

2. PEP 257 规范与风格标准

Python 官方在 PEP 257 中对 Docstring 的书写制定了严格的行业约定：

• 统一定界符：无论单双引号在语法上多一致，文档注释一律使用三个双引号 """，保持团队风格统一。
• 单行文档：当函数功能极其简单时，可写在一行内，首尾三个双引号置于同一行，句末加句号，例如 """Return the pathname of the KRNL module."""。
• 多行文档：第一行放置简明概要，空一行后展开详细说明、参数列表（Args）、返回值（Returns）以及抛出异常（Raises），闭合的 """ 单独成行。

三、Docstring 工程化：从编写到自动化文档构建

文档注释绝不仅仅是给阅读源码的人查看的，它贯穿于 Python 现代软件工程的整个生命周期：从开发期的 IDE 悬停提示，到测试调试时的交互式审查，再到部署阶段静态站点的全自动生成。

动态提取与清洗 Docstring

当需要从已有函数提取文档进行结构化展示或输出时，直接使用 obj.__doc__ 往往包含缩进。标准库 inspect.cleandoc 提供了与 Python 内部一致的缩进修剪算法：

import inspect

def process_data(items: list) -> int:
    """对传入的列表项进行前置清洗与去重计数。
    
    参数:
        items: 输入数据序列。
    """
    return len(set(items))

# 使用 inspect.cleandoc 获取干净对齐的文本
clean_doc = inspect.cleandoc(process_data.__doc__)
print(clean_doc)

四、核心误区澄清与对比总结

很多 Python 初学者甚至经验丰富的工程师在谈及三引号时，常会产生一个根深蒂固的概念偏差：“三引号是 Python 的多行注释语法”。

核心辨析：在 Python 词法语法规则中，唯一的注释标记是井号（#）。三引号从来都不是“多行注释语法”，它永远是一个合法的字符串表达式。

之所以大家常用三引号临时注释几行废弃代码，是因为在 Python 语法中，一个单独放置且未赋值给任何变量的字符串字面量是一个合法的空操作表达式（Expression Statement）。在大多数情况下，执行它不会带来副作用，因此表面上达到了“注释”代码的效果。然而：

• 如果这段未赋值的三引号出现在函数体内或模块顶层第一行，它会直接篡改模块或函数的 __doc__ 属性，覆盖原本真正的文档；
• 在没有优化编译或较老版本的解释器中，未赋值的字面量依然会生成 LOAD_CONST 字节码，增加无谓的代码体积与解析负担；
• 真正的注释（#）在词法分析阶段就会被词法扫描器（Tokenizer）直接丢弃，根本不会进入抽象语法树（AST）和字节码。

五、编写规范与开发总结

准确把握三引号的两种核心角色，能够让代码的意图清晰可读，同时避免隐藏的格式污染与性能问题。在日常编码与工程协同中，建议牢记以下实践准则：

1. 编写文档注释统一使用三个双引号 """：严格遵循 PEP 257 规范，将其置于模块、类或函数的首行，明确定义参数、返回值和异常。
2. 慎防多行文本缩进污染：当在缩进代码块中定义多行文本模板时，优先结合 textwrap.dedent() 剔除多余前置空白，确保文本纯净。
3. 拒绝用三引号充当常规多行注释：内部实现细节说明或临时停用代码段，应始终使用多行 #。现代代码编辑器均提供 Ctrl+/（或 Cmd+/）的快捷批量注释功能，既规范高效，又不会造成字节码冗余或意外覆盖 __doc__。