39、Python 文档字符串、兼容性及版本相关规范

Python 文档字符串、兼容性及版本相关规范

1. 文档字符串约定

在 Python 代码中，字符串字面量可作为文档使用。虽不被 Python 字节码编译器识别，也不能作为运行时对象属性访问，但软件工具可提取两种额外的文档字符串：
- 属性文档字符串 ：在模块、类或 __init__ 方法顶层的简单赋值语句后立即出现的字符串字面量。
- 附加文档字符串 ：紧跟在另一个文档字符串之后的字符串字面量。

为保持一致性，文档字符串应使用 """ 三重双引号 """ 。若文档字符串中使用反斜杠，使用 r""" 原始三重双引号 """ ；对于 Unicode 文档字符串，使用 u""" Unicode 三重引号字符串 """ 。

文档字符串有单行和多行两种形式：
- 单行文档字符串 ：适用于非常明显的情况，应放在一行。例如：

def kos_root():
    """Return the pathname of the KOS root directory."""
    global _kos_root
    if _kos_root: return _kos_root
    ...

使用时需注意：
- 即使字符串可放在一行，也使用三重引号，便于后续扩展。
- 结束引号与开始引号在同