Python实用技巧与概念大盘点 —— 第5篇

你可以看看我分享的一些关于Python技巧和窍门的帖子：

• Python实用技巧和窍门 — 第一篇
• Python实用技巧和窍门 — 第二篇
• Python实用技巧和窍门 — 第三篇
• Python实用技巧和窍门 — 第四篇

文档字符串是 Python 代码文档的关键部分。它们帮助开发人员理解代码组件的目的和功能。在 Python 中，文档字符串是用三重引号（""" 或 '''）包围的字符串，直接放在要记录的代码元素下面。Python 内置的 help() 函数和像 Sphinx 这样的文档生成工具会使用文档字符串，使其成为可维护和易访问代码的基础之一。

通常，docstring 会按照 Python 建议的 PEP 257 风格指南推荐的格式编写：

    def example(param1, param2):  
        """  
        简要说明该函数的功能。  

        如果需要，提供更详细的解释，包括任何特殊情况或需注意的事项。例如，  
        特殊情况或需注意的事项。  

        参数:  
            param1 (类型): param1 (str) 的解释。  
            param2 (类型): param2 (int) 的解释。  
        返回值:  
            类型 (str): 返回值的解释。  
        抛出:  
            异常类型 (ExceptionType): 解释异常何时被抛出。  
        """  
        ...

这种结构化的格式提高了可读性，并有助于工具提取有用的元数据。第一句应该提供简要描述该功能的目的，因为有些工具只提取这一句作为摘要。

单行文档字符串（docstring）适用于描述只需一句话就能说明目的的简单功能或方法的情况。

    def add(x, y):  
        """将两个数字相加并返回结果."""  
        return x + y

你可以通过其内置的 help() 函数或 __doc__ 属性来访问文档资料。

    help(add) # 或者 example.__doc__ (即示例的帮助文档)

    add.__doc__ # 或 example.__doc__

通过遵循这些实践，Python 开发者可以创建具有清晰文档、更易于维护的代码，从而简化开发流程，并让新贡献者更快上手。

Python 中的 doctest 模块允许你在文档中测试代码示例，这使得它既实用又强大，可以快速验证示例并确保文档的准确性，使其实用又可靠。通过在文档字符串中嵌入可测试的代码示例，doctest 会运行这些示例，确认它们按描述工作。这有助于防止文档中的代码示例与实际代码行为不一致。

要使用 doctest，只需在函数、方法或模块的文档字符串里添加形式为 Python 交互式会话的示例。每个示例以 >>>（Python REPL 提示符）开头，紧接着的是预期的输出。当 doctest 运行时，它会将实际输出与预期输出进行比较，并标记任何不匹配的地方。

    def add(a: int, b: int) -> int:  
        """  
        计算两个数字的总和。  

        示例（例如）:  
        >>> add(2, 3)  
        5  
        >>> add(-1, 1)  
        0  
        >>> add(4.5, 1.5)  
        6.0  
        """  
        return a + b

当你运行 doctest 命令时，它会执行代码示例，并验证结果是否正确。你可以在命令行中通过以下方式调用 doctest：

例如：

python -m doctest your_script.py

    python -m doctest <filename>.py

运行这个命令来使用doctest模块检查<filename>.py文件中的测试。

或者，你也可以在脚本中加入 doctest.testmod()，这样当运行该模块作为脚本时会自动执行测试。

if __name__ == "__main__":  
    import doctest  # 导入doctest模块
    doctest.testmod()  # 运行模块中的doctest测试

虽然 doctest 很方便，但它并不能完全替代它们。它最适合用于初始化、清理或高级断言都不复杂的简单情况。此外，它在处理像浮点数结果或非确定性输出这样的略有不同的输出时可能会有些棘手。

查看 add 函数的详细文档，了解其用法及其文档字符串。

    def add(a, b):  
        """  
        求两个数的和。  

        该函数接受两个数值输入，`a` 和 `b`，并返回它们的和。  

        适用于整数和小数。  

        参数:  
          a (int 或 float): 要相加的第一个数。  
          b (int 或 float): 要相加的第二个数。  

        返回:  
          int 或 float: `a` 和 `b` 的和。  

        示例:  
        >>> add(2, 3)  
        结果为 5  
        >>> add(-1, 1)  
        结果为 0  
        >>> add(4.5, 1.5)  
        结果为 6.0  
        """  
        return a + b  

将 doctest 集成到你的工作流程中可以使你的代码更可靠，文档更值得信赖，让其他人更容易理解和验证代码。

Python的列表推导是一种强大的工具，可以简洁地创建并操作数据。你可以直接从其他序列（如列表、字典或集合）中构建序列，只需一行代码。这比使用循环要简洁得多。

列表生成式最常见，通常用于基于已有列表或范围生成新列表。

举个例子，如何创建0到9这些数字的平方列表:

    # 语法格式：[expr for 项 in 迭代器 if 条件]  

    squares = [x**2 for x in range(10)]  
    # 输出结果：[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]  
# 结果如下：[0, 4, 16, 36, 64]

这让你可以以一种高度可读的方式创建经过过滤和转换的列表。

字典生成式可以从序列动态创建字典，其语法与列表推导式相似，但使用了键值对的形式。

下面是如何创建一个0到9的数字的平方字典的示例如下:

    # 语法：{键的表达式: 值的表达式 for 元素 in 可迭代对象（iterable） if 条件表达式}  

    squares_dict = {x: x**2 for x in range(10) （范围从0到9）}  
    # 输出结果如下：{0: 0, 1: 1, 2: 4, 3: 9, ..., 9: 81}

你也可以像列表推导那样，在字典推导中加入条件。

集合生成式与列表生成式类似，但生成集合而非列表。集合没有顺序，并且会自动去除重复值，因此当你需要唯一结果时很有用。

这是生成0到9这些数字的平方数集合的方法：

    # 语法如下：{表达式 for 元素 in 可迭代对象 if 条件}

    平方集合 = {x**2 for x in range(10)}  
    # 输出结果：{0, 1, 4, 9, 16, 25, 36, 49, 64, 81}

你也可以像对列表生成式那样，在字典生成式中加入条件，

生成器表达式与列表推导式类似，即生成器表达式会创建生成器而不是列表。生成器会按需逐个生成项目，这使得它们在处理大型数据集时更加节省内存。如果你只需要遍历数据一次，或者数据集太大无法一次性全部加载到内存中，这会特别有用。

生成器表达式使用圆括号 ()，而不是方括号 [] 或大括号 {}。

例如，这里有一个创建一个生成0到9这些数字平方数的生成器的方法：

    # 语法如下：(表达式 for 项 in 生成器 if 条件)

    squares_gen = (x**2 for x in range(10))

生成平方数的生成器：这将生成0到9的平方数。

在这个例子中，squares_gen 是一个生成器，每次迭代时才会产生一个平方。

    for square in squares_gen:  
        print(square)  

    # 输出结果: 0, 1, 4, 9, 16, 25, 36, 49, 64, 81.

然而，请记住，生成器表达式只能被迭代一次。如果你需要多次访问这些元素，可能更适合使用列表推导。