Sphinx Doctest与Matplotlib绘图：避免交互式阻塞的策略-Python教程-PHP中文网

Sphinx Doctest与Matplotlib绘图：避免交互式阻塞的策略

霞舞

发布： 2025-12-02 13:13:01

原创

744人浏览过

sphinx doctest与matplotlib绘图：避免交互式阻塞的策略

本文旨在解决Sphinx doctest 在处理包含Matplotlib绘图示例的文档字符串时，因 plt.show() 导致测试中断的问题。核心策略是通过重构绘图函数，使其接受可选的 Axes 对象并移除 plt.show() 的直接调用，从而将绘图逻辑与图形显示解耦。这种方法不仅提升了函数的复用性，也确保了 doctest 能够顺畅运行，实现自动化测试与文档生成。

理解问题：Sphinx Doctest与Matplotlib的交互式困境

在Python项目中，Sphinx是一个广泛使用的文档生成工具，其内置的 doctest 扩展能够从文档字符串中的示例代码直接运行测试，确保代码示例的准确性。然而，当这些文档字符串包含Matplotlib绘图代码，并且在函数内部调用了 plt.show() 时，doctest 可能会遇到一个常见的阻塞问题。

plt.show() 函数的作用是显示当前活动的Matplotlib图形窗口。在交互式环境中，这通常是期望的行为。但在自动化测试（如 doctest）或非交互式脚本中，plt.show() 会暂停程序执行，直到用户手动关闭图形窗口。这对于自动化流程来说是不可接受的，因为它需要人工干预，严重阻碍了测试的连续性。

考虑以下一个典型的Matplotlib绘图函数及其文档字符串：

import matplotlib.pyplot as plt

def plot_numbers_problematic(x):
    """
    显示一组数字的折线图。

    参数
    ----------
    x : list
        要绘制的数字列表。

    示例
    -------
    >>> import your_module # 假设此函数在your_module中
    >>> x_data = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> your_module.plot_numbers_problematic(x_data)
    """
    _, ax = plt.subplots()
    ax.plot(x, marker="o", mfc="red", mec="red")
    ax.set_xlabel("X轴标签")
    ax.set_ylabel("Y轴标签")
    ax.set_title("图表标题")

    plt.show() # 此处会导致doctest阻塞

登录后复制

当 sphinx-build -b doctest . _build 命令执行到 your_module.plot_numbers_problematic(x_data) 这一行时，plt.show() 会弹出一个图形窗口，并暂停 doctest 的执行，直到该窗口被手动关闭。

核心策略：解耦绘图与显示

解决此问题的关键在于将Matplotlib函数的绘图逻辑与图形显示行为进行解耦。一个设计良好的Matplotlib绘图函数不应该自行决定何时显示图形，而应该将这一控制权交给调用者。这样，函数可以更灵活地应用于各种场景，包括：

交互式显示： 调用者在函数执行后手动调用 plt.show()。
非交互式保存： 调用者在函数执行后将图形保存到文件，而不显示。
子图组合： 调用者在同一个 Figure 上创建多个 Axes，并将这些 Axes 传递给不同的绘图函数。
自动化测试： 测试框架可以调用绘图函数而不显示图形，只检查返回的 Axes 对象或其内容。

实现这一解耦的常用方法是让绘图函数接受一个可选的 Axes 对象作为参数。如果提供了 Axes 对象，函数就在其上绘图；如果没有提供，函数则自行创建一个新的 Figure 和 Axes。最重要的是，从函数内部移除 plt.show() 的调用。

优化Matplotlib绘图函数

以下是优化后的 plot_numbers 函数示例：

Otter.ai

一个自动的会议记录和笔记工具，会议内容生成和实时转录

查看详情

import matplotlib.pyplot as plt

def plot_numbers(x, *, ax=None):
    """
    显示一组数字的折线图。

    参数
    ----------
    x : list
        要绘制的数字列表。
    ax : matplotlib.axes.Axes, 可选
        用于绘制数字的Matplotlib Axes对象。如果未提供，将创建一个新的Figure和Axes。

    返回
    -------
    matplotlib.axes.Axes
        绘制了数据的Axes对象。

    示例
    -------
    >>> import your_module # 假设此函数在your_module中
    >>> x_data = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> # 在doctest中，这不会打开窗口。
    >>> # 如果需要在交互式环境中显示，请在调用函数后手动调用 plt.show()。
    >>> ax_result = your_module.plot_numbers(x_data)
    >>> # plt.show() # 在需要显示图形时取消注释
    >>> # 验证 Axes 对象是否已创建
    >>> assert isinstance(ax_result, plt.Axes)
    >>> # 进一步的doctest可以检查ax_result的属性，例如标题、标签等
    >>> ax_result.get_title()
    '图表标题'
    """
    if ax is None:
        # 如果没有提供Axes，则创建一个新的Figure和Axes
        _, ax = plt.subplots()

    # 在提供的或新创建的Axes上进行绘图
    ax.plot(x, marker="o", mfc="red", mec="red")
    ax.set_xlabel("X轴标签")
    ax.set_ylabel("Y轴标签")
    ax.set_title("图表标题")

    return ax # 返回Axes对象，以便调用者进行进一步操作

登录后复制

关键改动点说明：

ax=None 参数： 函数现在接受一个可选的 ax 参数，类型为 matplotlib.axes.Axes。* 用作分隔符，表示 ax 是一个仅限关键字参数，提高了API的清晰度。
条件性 plt.subplots()： 如果 ax 为 None，函数会调用 plt.subplots() 创建一个新的 Figure 和 Axes。这意味着函数既可以在现有 Axes 上绘图，也可以作为独立的绘图函数使用。
移除 plt.show()： 最重要的改变是移除了 plt.show() 的调用。现在，函数只负责在 Axes 上绘制内容。
返回 ax： 函数现在返回绘制数据的 Axes 对象。这使得调用者能够访问和操作 Axes，例如保存图形、修改属性或在交互式环境中显示。
更新文档字符串示例： doctest 示例也相应更新，以接收返回的 ax 对象，并注释掉 plt.show()，明确告知用户在 doctest 环境下不会显示图形。

Doctest中的应用与优势

通过上述优化，当 doctest 运行时，它会执行 your_module.plot_numbers(x_data)，函数会正常执行绘图逻辑并返回一个 Axes 对象，但不会弹出图形窗口，从而避免了阻塞。

这种方法带来了多方面的好处：

无缝自动化测试： doctest 和其他测试框架（如 pytest）可以无障碍地运行包含Matplotlib示例的测试。
更高的函数复用性： 绘图函数变得更加通用，可以轻松地集成到更复杂的图形布局（例如，使用 plt.figure().add_subplot() 或 plt.subplots() 创建的多个子图）或自定义的应用程序中。
清晰的职责分离： 函数专注于“如何绘图”，而“何时显示”的职责则交给了调用者，这符合软件设计的单一职责原则。
更好的控制： 调用者可以根据需要选择显示图形、将其保存到文件（fig.savefig(...)）或在更高级的GUI应用程序中嵌入它。

注意事项与最佳实践

谁来调用 plt.show()？ 在优化后的设计中，plt.show() 应该由最终的用户代码或顶层脚本来调用，而不是由库函数内部调用。例如：

import matplotlib.pyplot as plt
# 假设 plot_numbers 是优化后的函数
import your_module

if __name__ == "__main__":
    x_data = [1, 3, 2, 4, 5]
    # 在新的Figure和Axes上绘图并显示
    ax1 = your_module.plot_numbers(x_data)
    ax1.set_title("第一个图")

    # 在同一个Figure上创建另一个Axes，并用另一个函数绘图
    fig, (ax2, ax3) = plt.subplots(1, 2)
    your_module.plot_numbers([5, 4, 3, 2, 1], ax=ax2)
    ax2.set_title("第二个图")
    your_module.plot_numbers([10, 8, 6, 4, 2], ax=ax3)
    ax3.set_title("第三个图")

    plt.tight_layout() # 调整子图布局
    plt.show() # 在这里统一显示所有图形

登录后复制

文档清晰度： 在函数的文档字符串中明确说明 ax 参数的作用，以及函数不会自行调用 plt.show()。
参考官方指南： Matplotlib官方文档也推荐了这种编写辅助函数的方式，例如在其“Making a helper functions”部分（https://www.php.cn/link/dda4087216e15d1784efc310005dd683）中有所提及。虽然该示例可能要求 ax 参数是强制的，但核心思想是相同的：将 Axes 对象作为参数传递。

总结

通过将Matplotlib绘图函数的职责限制在纯粹的绘图操作上，并移除内部的 plt.show() 调用，我们可以有效地解决Sphinx doctest 在遇到交互式图形窗口时的阻塞问题。这种设计模式不仅使测试自动化成为可能，还显著提高了绘图函数的灵活性、可复用性和API的清晰度，是编写高质量Matplotlib库代码的重要实践。开发者应养成习惯，让绘图函数返回 Axes 对象，并将图形的显示或保存逻辑留给调用者处理。

以上就是Sphinx Doctest与Matplotlib绘图：避免交互式阻塞的策略的详细内容，更多请关注php中文网其它相关文章！