Python三引号字符串与文档字符串

Python三引号字符串与文档字符串——原始字符串、PEP 257规范与doctest三引号字符串是Python文档系统的基石。结合原始字符串它们构成了Python自文档化能力的基础。import inspectimport doctest# 原始字符串与三引号 # 原始字符串r 让反斜杠不再转义normal_path C:\\Users\\name\\file.txt # 需要双反斜杠raw_path rC:\Users\name\file.txt # 原始字符串更好print(f普通字符串: {normal_path})print(f原始字符串: {raw_path})# 原始字符串配合三引号适合正则表达式和多行文本regex_pattern r^ # 行首[\w\.-] # 用户名部分字母数字点连字符[\w\.-]\. # 域名部分\w{2,} # 顶级域名$ # 行尾print(f正则表达式注释版:\n{regex_pattern})# 三引号保留换行和缩进但小心前导空格multiline 第一行第二行缩进行print(multiline)# 模块文档字符串 # 每个模块应该有一个文档字符串本文件顶部已演示# 类与函数的文档字符串 class DocumentedClass:有完整文档的类。这个类演示了PEP 257规范的文档字符串风格。第一行是简要描述空一行后跟详细说明。def documented_method(self, param: str) - str:有文档的方法。参数使用间接说明风格不在签名中重复参数名。Args:param: 输入的字符串参数。Returns:处理后的字符串。return param.upper()def inline_docstring(self):单行文档字符串简洁明了适合简单方法。pass# __doc__ 和 help() # 访问文档字符串的两种方式def sample_function():这是一个示例函数。它展示了文档字符串的访问方式。passprint(f通过 __doc__ 访问: {sample_function.__doc__})# 查看类的文档print(fDocumentedClass 的文档: {DocumentedClass.__doc__})# inspect.getdoc 清理缩进 class MessyDoc:def method(self):这个文档有不对齐的缩进。使用 inspect.getdoc 可以自动清理这些缩进。即使有多层缩进也能正确处理。pass# 直接访问 __doc__ 会得到原始缩进raw_doc MessyDoc.method.__doc__print(f__doc__ 原始内容:\n{raw_doc})# inspect.getdoc 会清理前导空白cleaned_doc inspect.getdoc(MessyDoc.method)print(finspect.getdoc 清理后:\n{cleaned_doc})# PEP 257 文档字符串约定 class Pep257Demo:遵循PEP 257约定的文档字符串。规则1. 三引号前后没有空行单行的情况。2. 多行文档第一行是概要空行后跟详细描述。3. 结尾的三引号单独占一行。4. 每行不超过72个字符如果可能。def compound_function(self, a: int, b: int) - int:计算两个数的复合结果。这里的详细描述解释了算法背后的原理。使用自然段落来描述不需要严格的格式。但建议在描述参数和返回值时保持一致性。注意这个方法仅供演示PEP 257的风格。return (a b) * (a - b)# doctest 在文档字符串中 def factorial(n: int) - int:计算非负整数n的阶乘。文档字符串中的doctest示例可以同时作为文档和测试。 factorial(0)1 factorial(1)1 factorial(5)120 factorial(10)3628800边界情况测试 factorial(-1)Traceback (most recent call last):...ValueError: 输入必须为非负整数if n 0:raise ValueError(输入必须为非负整数)if n 1:return 1return n * factorial(n - 1)def fibonacci(n: int) - int:返回第n个斐波那契数。更多doctest示例 fibonacci(1)1 fibonacci(2)1 fibonacci(5)5 fibonacci(10)55 [fibonacci(i) for i in range(1, 7)][1, 1, 2, 3, 5, 8]if n 0:raise ValueError(输入必须为正整数)if n 2:return 1a, b 1, 1for _ in range(3, n 1):a, b b, a breturn b# 运行doctest通常放在模块末尾if __name__ __main__:doctest.testmod(verboseTrue)print(doctest 运行完毕所有测试通过)