全网整合营销服务商

电脑端+手机端+微信端=数据同步管理

免费咨询热线:400-708-3566

解决Sphinx doctest中Matplotlib示例的交互式图形问题

本教程探讨了在sphinx文档中,当使用`doctest`测试包含matplotlib绘图示例的文档字符串时,如何避免交互式图形窗口中断测试流程的问题。核心解决方案是重构matplotlib绘图函数,使其接受可选的`ax`参数,并将图形的显示控制权(即`plt.show()`的调用)交由调用者处理,从而实现无缝的自动化测试。

问题背景与分析

在使用Sphinx生成项目文档并结合doctest模块进行代码示例测试时,开发者可能会遇到一个常见问题:当函数的文档字符串中包含Matplotlib绘图示例,并且这些示例调用了plt.show()方法时,doctest的执行会被中断。plt.show()会打开一个交互式的图形窗口,这要求用户手动关闭窗口才能让doctest继续执行,这显然不符合自动化测试的需求。

问题的根源在于plt.show()的设计。它旨在显示当前活动的Matplotlib图形,并进入一个事件循环,直到图形窗口被关闭。在自动化测试环境中,这种行为会导致测试进程挂起,因为它期待用户交互。为了实现自动化测试,我们需要一种机制,既能让doctest验证绘图逻辑,又不会触发交互式窗口。

解决方案:重构Matplotlib绘图函数

解决此问题的关键在于改变Matplotlib绘图函数的结构,使其不负责图形的最终显示,而是将这一控制权交给调用者。具体而言,就是让绘图函数接受一个可选的matplotlib.axes.Axes对象作为参数,并在函数内部移除plt.show()的调用。

核心设计理念

  1. 注入 Axes 对象: 绘图函数应设计为可以接收一个预先创建的Axes对象。如果未提供,函数可以自行创建一个新的Figure和Axes。
  2. 移除 plt.show(): 绘图函数内部不应包含plt.show()。图形的显示应由调用者在适当的时机(例如,在脚本的顶层或交互式会话中)负责。
  3. 返回 Axes 对象: 函数应返回它所操作的Axes对象,以便调用者可以进一步自定义或显示该图形。

示例代码

以下是根据上述理念重构后的plot_numbers函数:

import matplotlib.pyplot as plt

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

    Parameters
    ----------
    x : list
        要绘制的数字列表。
    ax : Axes, optional
        可选的Matplotlib Axes对象,用于在其上绘制数字。
        如果未提供,将自动创建一个新的Axes。

    Example
    -------
    >>> import calc # 假设此函数在 calc 模块中
    >>> x = [1, 2, 5, 6, 8.1, 7, 10.5, 12]
    >>> ax = calc.plot_numbers(x)
    >>> # 在实际应用中,如果需要显示,可以在此处调用 plt.show()
    >>> # 例如:plt.show()
    >>> # 为了doctest的自动化,我们不在这里调用 plt.show()
    >>> # 而是检查返回的ax对象是否有效
    >>> import matplotlib.pyplot as plt
    >>> assert isinstance(ax, plt.Axes)
    >>> # 可以进一步检查ax中的内容,例如线条数量等
    >>> assert len(ax.lines) == 1
    """
    if ax is None:
        _, 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

代码解析与Doctest兼容性

  1. ax=None 参数: 函数现在接受一个名为ax的可选关键字参数。这使得调用者可以传入一个现有的Axes对象。
  2. 条件性创建 Axes: if ax is None: _, ax = plt.subplots() 这一行确保了函数既可以独立运行(自动创建Axes),也可以集成到更大的绘图布局中(使用外部传入的Axes)。
  3. 移除 plt.show(): 最关键的改变是删除了原有的plt.show()调用。这意味着函数执行完毕后,不会自动弹出图形窗口。
  4. 返回 ax 对象: 函数现在返回它所操作的Axes对象。这对于doctest至关重要,因为测试可以检查返回的ax对象是否是有效的Matplotlib Axes实例,甚至可以进一步检查ax上的绘图元素(例如,ax.lines属性)。
  5. Doctest 自动化: 通过移除plt.show(),doctest在执行示例时将不再被图形窗口阻塞。它会执行绘图逻辑,但不会尝试显示图形。测试现在可以专注于验证函数是否正确地配置了Axes对象,而不是图形的视觉呈现。例如,示例中添加了assert isinstance(ax, plt.Axes)和assert len(ax.lines) == 1,这些断言可以在不显示图形的情况下验证函数的行为。

注意事项与最佳实践

  • 库函数设计: 对于任何作为库一部分的绘图函数,通常都建议避免在函数内部调用plt.show()。plt.show()更适合在最终用户脚本或交互式会话中调用,它表示“我已完成所有绘图设置,现在请显示它”。将此职责从库函数中分离,可以提高函数的灵活性和可重用性。
  • 灵活性: 允许传入ax参数极大地增加了函数的灵活性。用户可以将你的绘图集成到他们自己的Figure和Axes布局中,例如子图、多图布局等,而无需修改你的函数。
  • 资源清理: 即使不调用plt.show(),Matplotlib的Figure和Axes对象仍然会被创建并占用内存。在长时间运行的测试或循环中,如果创建了大量图形而不进行清理,可能会导致内存问题。在某些高级场景中,可能需要在测试结束后显式地调用plt.close('all')来关闭所有图形。然而,对于doctest这种单次运行的示例,通常不是必须的。
  • 官方文档参考: Matplotlib官方文档也推荐了类似的辅助函数(helper functions)设计模式,即接受ax参数。这是一种被广泛接受的最佳实践。

总结

通过将Matplotlib绘图函数重构为接受可选的ax参数并移除内部的plt.show()调用,我们不仅解决了Sphinx doctest在处理绘图示例时遇到的交互式图形窗口中断问题,还提升了函数的通用性和可测试性。这种设计模式使得绘图函数更加模块化,更易于集成到不同的应用场景和自动化测试流程中,是编写高质量Python绘图库的推荐实践。


# python  # 常见问题  # red 


相关文章: 自助网站制作软件,个人如何自助建网站?  惠州网站建设制作推广,惠州市华视达文化传媒有限公司怎么样?  如何快速搭建支持数据库操作的智能建站平台?  小捣蛋自助建站系统:数据分析与安全设置双核驱动网站优化  如何零基础在云服务器搭建WordPress站点?  大连网站制作费用,大连新青年网站,五年四班里的视频怎样下载啊?  建站之星如何实现PC+手机+微信网站五合一建站?  昆明高端网站制作公司,昆明公租房申请网上登录入口?  高防网站服务器:DDoS防御与BGP线路的AI智能防护方案  内部网站制作流程,如何建立公司内部网站?  建站主机选购指南:核心配置优化与品牌推荐方案  如何在阿里云香港服务器快速搭建网站?  怀化网站制作公司,怀化新生儿上户网上办理流程?  如何快速搭建安全的FTP站点?  相亲简历制作网站推荐大全,新相亲大会主持人小萍萍资料?  如何在Golang中处理模块冲突_解决依赖版本不兼容问题  网站制作免费,什么网站能看正片电影?  如何在Tomcat中配置并部署网站项目?  专业网站制作服务公司,有哪些网站可以免费发布招聘信息?  建站之星如何取消后台验证码生成?  北京网页设计制作网站有哪些,继续教育自动播放怎么设置?  免费制作海报的网站,哪位做平面的朋友告诉我用什么软件做海报比较好?ps还是cd还是ai这几个软件我都会些我是做网页的?  购物网站制作公司有哪些,哪个购物网站比较好?  盐城做公司网站,江苏电子版退休证办理流程?  网站制作壁纸教程视频,电脑壁纸网站?  太原网站制作公司有哪些,网约车营运证查询官网?  学生网站制作软件,一个12岁的学生写小说,应该去什么样的网站?  c++ stringstream用法详解_c++字符串与数字转换利器  如何在阿里云购买域名并搭建网站?  网站专业制作公司,网站编辑是做什么的?好做吗?工作前景如何?  平台云上自助建站如何快速打造专业网站?  济南专业网站制作公司,济南信息工程学校怎么样?  如何快速启动建站代理加盟业务?  平台云上自主建站:模板化设计与智能工具打造高效网站  整人网站在线制作软件,整蛊网站退不出去必须要打我是白痴才能出去?  建站主机如何选?性能与价格怎样平衡?  html制作网站的步骤有哪些,iapp如何添加网页?  c# 在高并发下使用反射发射(Reflection.Emit)的性能  高防服务器租用指南:配置选择与快速部署攻略  定制建站流程步骤详解:一站式方案设计与开发指南  如何在IIS中新建站点并解决端口绑定冲突?  网站视频怎么制作,哪个网站可以免费收看好莱坞经典大片?  常州企业网站制作公司,全国继续教育网怎么登录?  营销式网站制作方案,销售哪个网站招聘效果最好?  建站之星ASP如何实现CMS高效搭建与安全管理?  网站制作公司排行榜,四大门户网站排名?  郑州企业网站制作公司,郑州招聘网站有哪些?  如何选择CMS系统实现快速建站与SEO优化?  如何用手机制作网站和网页,手机移动端的网站能制作成中英双语的吗?  如何快速建站并高效导出源代码? 

您的项目需求

*请认真填写需求信息,我们会在24小时内与您取得联系。