摘要：文档字符串是 Python 代码文档的关键组成部分。它们提供了一种简单且标准化的方式来记录模块、函数、类和方法，使开发人员能够了解代码组件的用途和功能。在 Python 中，文档字符串只是用三引号（“”“ 或 '''）括起来的字符串文字，直接放置在它记录的元素
·
文档字符串是 Python 代码文档的关键组成部分。它们提供了一种简单且标准化的方式来记录模块、函数、类和方法，使开发人员能够了解代码组件的用途和功能。在 Python 中，文档字符串只是用三引号（“”“ 或 '''）括起来的字符串文字，直接放置在它记录的元素下方。Python 的内置 help 函数和文档生成工具（如 Sphinx）利用文档字符串，使其成为可维护和可访问代码的基础。
文档字符串通常遵循 Python 的 PEP 257 样式指南推荐的特定结构：
def example(param1, param2): """ Brief description of what the function does. More detailed explanation if needed, including any edge cases or considerations. Args: param1 (type): Explanation of param1. param2 (type): Explanation of param2. Returns: type: Explanation of the return value. Raises: exceptionType: Explanation of when the exception is raised. """ ...这种结构化方法增强了可读性，并帮助工具提取有用的元数据。值得注意的是，第一行应提供函数用途的简要概述，因为某些工具仅提取此初始行进行摘要。
单行文档字符串非常适合简单的函数或方法，其中一行就足以描述目的。
def add(x, y): """Add two numbers and return the result.""" return x + y可以使用其内置的 help 函数或 __doc__ 属性来访问文档。
help(add) # or example.__doc__add.__doc__ # or example.__doc__通过遵守这些实践，Python 开发人员可以创建文档齐全、可维护的代码，从而简化新贡献者的开发和入门流程。
Python 中的 doctest 模块允许您将代码作为其文档的一部分进行测试，这使其成为快速验证示例和确保您的文档准确的便捷而强大的工具。通过在文档字符串中嵌入可测试的代码示例， doctest 会运行这些示例以确认它们按描述工作。这有助于防止文档中的代码腐烂，因为示例与实际代码行为不一致。
要使用 doctest，只需在函数、方法或模块文档字符串中以 Python 交互式会话的形式添加示例。每个示例都以 >>>（Python REPL 提示符）开头，预期输出紧随其后。当 doctest 运行时，它会将实际输出与预期输出进行比较，并标记任何不匹配。
def add(a: int, b: int) -> int: """ Calculate the sum of two numbers. Example: >>> add(2, 3) 5 >>> add(-1, 1) 0 >>> add(4.5, 1.5) 6.0 """ return a + b当您运行 doctest 时，它将执行文档字符串中的代码并验证结果是否匹配。您可以从命令行在此脚本上调用 doctest：
python -m doctest .py或者，您可以在脚本中添加 doctest.testmod 以在模块作为脚本执行时自动运行测试：
if __name__ == "__main__": import doctest doctest.testmod虽然 doctest 很方便，但它并不能完全替代更广泛的测试框架，例如 unittest 或 pytest 。它最适合没有复杂设置、拆解或高级断言的简单情况。它还可能难以处理略有不同的输出（如浮点结果或非确定性输出）。
请参阅 add 函数的综合文档以了解
有关 DocString 中附加的有关其用法的更多信息。
将 doctest 合并到您的工作流程中可以使您的代码更可靠，文档更值得信赖，从而使其他人能够有效地理解和验证代码行为。
Python 推导式是以简洁、可读的方式创建和操作数据的强大工具。此技术允许您直接从其他序列构建序列（如列表、字典或集），所有这些都在一行代码中完成。与使用 Loop 相比，这可能是一个显著的改进。
列表推导式是最常见的类型，通常用于基于现有列表或范围创建列表。
创建 0 到 9 的方格列表的示例 hwo：
# Syntax: [expression for item in iterable if condition]squares = [x**2 for x in range(10)]# Output: [0, 1, 4, 9, 16, 25, 36, 49, 64, 81]上面的推导式从 range（10） 中取出每个数字，将其平方，并将其添加到 squares 列表中。您还可以包含条件语句来筛选元素。
如何添加条件以仅包含偶数个方块的示例：
even_squares = [x**2 for x in range(10) if x % 2 == 0]# Output: [0, 4, 16, 36, 64]字典推导式对于从序列动态创建字典非常有用。语法类似于列表推导式，但使用键值结构。
创建 0 到 9 的平方字典的示例 hwo：
# Syntax: {key_expression: value_expression for item in iterable if condition}squares_dict = {x: x**2 for x in range(10)}# Output: {0: 0, 1: 1, 2: 4, 3: 9, ..., 9: 81}您还可以像对待列表推导式一样将条件应用于字典推导式。
集合推导式的工作方式与列表推导式类似，但生成的是集合而不是列表。集是无序的，会自动删除重复值，因此当您需要唯一的结果时，这非常有用。
如何为数字 0 到 9 创建一组正方形的示例：
# Syntax: {expression for item in iterable if condition}squares_set = {x**2 for x in range(10)}# Output: {0, 1, 4, 9, 16, 25, 36, 49, 64, 81}生成器推导式类似于列表推导式，但创建的是生成器而不是列表。生成器一次生成一个项目，并且仅在需要时生成，从而使它们具有内存效率，尤其是对于大型数据集。如果您只需要迭代一次数据，或者数据集太大而无法一次全部放入内存，这将特别有用。
生成器推导式的语法使用括号 而不是方括号 或大括号 {}。
如何为数字 0 到 9 的平方创建生成器的示例：
# Syntax: (expression for item in iterable if condition)squares_gen = (x**2 for x in range(10))在此示例中，squares_gen 是一个生成器对象，仅当迭代每个正方形时，它才会生成每个正方形。
for square in squares_gen: print(square)# Output: 0, 1, 4, 9, 16, 25, 36, 49, 64, 81但是，请记住，生成器推导式只能迭代一次。如果需要多次访问元素，则列表推导式可能更合适。
来源：自由坦荡的湖泊AI一点号
