企业官网建设流程全解析

CPython turtle 模块修复解析：关闭屏幕后重建画面不再抛出 turtle.Terminator

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython

导读

本文围绕 CPython 标准库turtle模块的一则 NEWS 变更（gh-issue-70758）展开：当用户关闭前一个 turtle 图形窗口后再次创建新屏幕时，第一条 turtle 命令不再抛出turtle.Terminator异常。文章将结合 Lib/turtle.py 源码，深入剖析Terminator异常的设计意图、TurtleScreen._RUNNING运行标志的传递机制、Screen()单例与窗口销毁的生命周期，并给出可复现、可验证的完整分析与测试路径，帮助读者理解 turtle 图形编程的底层运行模型。

一、变更条目概览

本次变更记录在 CPython 仓库的 NEWS 条目文件 Misc/NEWS.d/next/Library/2022-01-03-12-50-42.gh-issue-70758.2NjFW_.rst 中，原始描述为：

Creating a newturtlescreen after the previous one was closed no longer raisesturtle.Terminatoron the first turtle command.

翻译过来即是：在关闭前一个 turtle 屏幕之后创建新的屏幕，第一条 turtle 命令不再抛出turtle.Terminator。

这则条目虽短，但背后涉及 turtle 模块中一套完整的"运行状态标志 + 屏幕生命周期"机制。要理解这次修复，需要先弄清三个关键概念：Terminator异常、TurtleScreen._RUNNING标志，以及屏幕对象的创建与销毁流程。

二、Terminator异常：turtle 的"停止执行"信号

2.1 异常定义

Terminator是turtle模块自定义的异常类型，定义在 Lib/turtle.py#L860-L866：

class Terminator (Exception): """Will be raised in TurtleScreen.update, if _RUNNING becomes False. This stops execution of a turtle graphics script. Main purpose: use in the Demo-Viewer turtle.Demo.py. """ pass

从其文档字符串可以看出设计意图：

• 当TurtleScreen._RUNNING变为False时，turtle 的内部操作会抛出Terminator；
• 抛出该异常的目的在于停止 turtle 图形脚本的执行；
• 主要使用场景是 turtle 自带的演示查看器（Demo-Viewer，即turtle.Demo.py），当用户关闭某个演示窗口后，相关脚本应立即停止，而不是继续在已销毁的画布上执行绘图命令。

2.2 抛出点：三处关键代码路径

在当前源码中，raise Terminator一共出现在三个位置：

①TurtleScreen._incrementudc（Lib/turtle.py#L1329-L1336）

def _incrementudc(self): """Increment update counter.""" if not TurtleScreen._RUNNING: TurtleScreen._RUNNING = True raise Terminator if self._tracing > 0: self._updatecounter += 1 self._updatecounter %= self._tracing

这是"更新计数器"的递增方法：当屏幕不再处于运行状态时，任何试图触发重绘的路径都会先复位_RUNNING，再抛出Terminator，从而打断脚本流程。

② 全局函数模板__func_body（Lib/turtle.py#L4107-L4121）

turtle 模块通过动态生成机制把RawTurtle/Turtle和TurtleScreen/Screen的方法批量暴露为模块级函数（如forward()、circle()、bgcolor()等）。这些函数的统一模板如下：

__func_body = """\ def {name}{paramslist}: if {obj} is None: if not TurtleScreen._RUNNING: TurtleScreen._RUNNING = True raise Terminator {obj} = {init} try: return {obj}.{name}{argslist} except TK.TclError: if not TurtleScreen._RUNNING: TurtleScreen._RUNNING = True raise Terminator raise """

模板中有两处Terminator抛出逻辑：

• 当全局 turtle 对象（Turtle._pen或Turtle._screen）尚为None、需要惰性初始化时，如果_RUNNING为False，则复位标志并抛出Terminator；
• 当调用底层 Tkinter 方法抛出TK.TclError（典型场景是画布/窗口已被销毁）时，同样检查_RUNNING，若为False则抛出Terminator。

这个模板由_make_global_funcs（Lib/turtle.py#L4123-L4138）对_tg_screen_functions和_tg_turtle_functions两组函数列表批量实例化。

③TurtleScreen._incrementudc之外的update相关路径

Terminator的类文档声称"在TurtleScreen.update中抛出"，实际抛出现场位于update内部调用的_incrementudc，这与文档描述一致——update是刷新画布的核心方法（Lib/turtle.py#L1338-L1347），任何绘图动作最终都会经由重绘机制走到_incrementudc。

三、TurtleScreen._RUNNING：屏幕运行状态的"全局开关"

_RUNNING是定义在TurtleScreen类上的类变量（Lib/turtle.py#L963）：

class TurtleScreen(TurtleScreenBase): ... _RUNNING = True

它扮演着"当前 turtle 图形系统是否在运行"的全局开关角色，贯穿整个模块：

值得注意的是，在__init__中重置_RUNNING的地方，源码专门写了一条注释：

# A new screen means that turtle graphics is running again. TurtleScreen._RUNNING = True

这正是本次 gh-issue-70758 修复的核心落点（详见第五节）。

四、屏幕生命周期：从创建到销毁的完整链路

4.1Screen()单例工厂

模块级函数Screen()是获取屏幕对象的唯一入口（Lib/turtle.py#L3822-L3828）：

def Screen(): """Return the singleton screen object. If none exists at the moment, create a new one and return it, else return the existing one.""" if Turtle._screen is None: Turtle._screen = _Screen() return Turtle._screen

它是一个单例访问器：如果Turtle._screen尚为None，则创建新的_Screen实例并缓存；否则直接返回既有实例。

4.2_Screen.__init__：根窗口与画布的惰性创建

_Screen是TurtleScreen的子类（Lib/turtle.py#L3830），其构造函数（L3836-L3851）按需创建 Tk 根窗口与画布：

class _Screen(TurtleScreen): _root = None _canvas = None _title = _CFG["title"] def __init__(self): if _Screen._root is None: _Screen._root = self._root = _Root() self._root.title(_Screen._title) self._root.ondestroy(self._destroy) if _Screen._canvas is None: width = _CFG["width"] height = _CFG["height"] canvwidth = _CFG["canvwidth"] canvheight = _CFG["canvheight"] leftright = _CFG["leftright"] topbottom = _CFG["topbottom"] self._root.setupcanvas(width, height, canvwidth, canvheight) _Screen._canvas = self._root._getcanvas() TurtleScreen.__init__(self, _Screen._canvas) self.setup(width, height, leftright, topbottom)

关键点：

• _root与_canvas也是类级单例，在窗口被销毁并重置前只会创建一次；
• 根窗口创建后，通过self._root.ondestroy(self._destroy)把_destroy注册为窗口关闭协议的回调；
• 画布创建后，调用TurtleScreen.__init__(self, _Screen._canvas)完成屏幕初始化——正是这一步会执行TurtleScreen._RUNNING = True的复位逻辑。

4.3_Root与窗口关闭协议

_Root是基于 TkinterTK.Tk的根窗口类（Lib/turtle.py#L429-L452）：

class _Root(TK.Tk): """Root class for Screen based on Tkinter.""" def __init__(self): TK.Tk.__init__(self) ... def ondestroy(self, destroy): self.wm_protocol("WM_DELETE_WINDOW", destroy)

ondestroy通过 Tk 的窗口管理器协议WM_DELETE_WINDOW注册回调：用户点击窗口标题栏的关闭按钮时，_destroy会被调用。

4.4_destroy与bye()：屏幕的"善后清理"

_destroy是窗口销毁时执行的核心清理逻辑（Lib/turtle.py#L3910-L3918）：

def _destroy(self): root = self._root if root is _Screen._root: Turtle._pen = None Turtle._screen = None _Screen._root = None _Screen._canvas = None TurtleScreen._RUNNING = False root.destroy()

它做了四件事：

1. 把模块级 turtle 对象引用Turtle._pen、Turtle._screen重置为None；
2. 把类级单例_Screen._root、_Screen._canvas重置为None，允许下一次Screen()调用重新创建全新的根窗口与画布；
3. 将TurtleScreen._RUNNING置为False，宣告图形系统停止运行；
4. 调用 Tk 的root.destroy()真正销毁窗口。

而公开方法bye()就是对_destroy的直接封装（Lib/turtle.py#L3920-L3926）：

def bye(self): """Shut the turtlegraphics window. Example (for a TurtleScreen instance named screen): >>> screen.bye() """ self._destroy()

同样，exitonclick()（Lib/turtle.py#L3928）在用户点击画布后也会进入清理流程。也就是说，关闭 turtle 窗口存在两条路径：程序内调用bye()/exitonclick()，或用户直接点击窗口关闭按钮（经由WM_DELETE_WINDOW→_destroy），两条路径最终都会走到_destroy并把_RUNNING置为False。

五、问题复现与修复原理

5.1 修复前的故障场景

综合上述机制，修复前的故障链条可以还原为：

1. 用户第一次调用Screen()创建屏幕，TurtleScreen._RUNNING为True，一切正常；
2. 用户调用bye()（或直接关闭窗口），_destroy执行：单例引用被清空、_RUNNING被置为False、Tk 窗口被销毁；
3. 用户再次调用Screen()，由于Turtle._screen已为None，会创建一个全新的_Screen——但此时TurtleScreen._RUNNING仍停留在False；
4. 在新屏幕上执行第一条 turtle 命令（例如forward(100)），该命令经由__func_body模板生成，若内部触发_incrementudc或遇到惰性初始化/TK.TclError检查，就会因为_RUNNING == False而抛出turtle.Terminator，导致新屏幕上的脚本意外中断。

这正是 NEWS 条目所描述的用户可见症状：关闭旧屏幕后新建屏幕，第一条 turtle 命令抛turtle.Terminator。

5.2 修复内容：新屏幕 = 图形系统重新运行

修复的落点在TurtleScreen.__init__的末尾（Lib/turtle.py#L1005-L1006）：

# A new screen means that turtle graphics is running again. TurtleScreen._RUNNING = True

每当一个新的_Screen实例完成初始化时，就把_RUNNING复位为True。由于Screen()在旧屏幕销毁后必定会走_Screen.__init__→TurtleScreen.__init__的创建路径，_RUNNING得以在新屏幕建成的同时恢复为运行状态，此后第一条 turtle 命令不再命中Terminator的抛出条件。

从源码结构看，_incrementudc与__func_body中"抛Terminator之前先把_RUNNING置回True"的设计也与此呼应：Terminator被设计为一次性中断信号，捕获后图形系统仍可恢复运行——新屏幕创建时显式复位该标志，正是这一设计哲学的完整落地。

5.3 修复后的行为验证

修复之后，下列交互模式可以正常工作：

import turtle # 第一次创建屏幕并绘制 screen = turtle.Screen() t = turtle.Turtle() t.forward(100) # 关闭窗口（等价于用户点击关闭按钮） screen.bye() # 再次创建新屏幕——此前会抛 turtle.Terminator screen2 = turtle.Screen() t2 = turtle.Turtle() # 第一条 turtle 命令，现在正常执行 t2.circle(50) turtle.done()

注意：turtle.done()会进入 Tk 主循环，适合在交互式脚本或带图形界面的环境中运行；在无显示环境的服务器上运行 turtle 需要配置 X11 转发或虚拟显示器（如xvfb），这是 turtle 基于 Tkinter 的固有限制。

六、测试与验证路径

turtle 模块的单元测试位于 Lib/test/test_turtle.py，其中TestTurtleScreen测试类（Lib/test/test_turtle.py#L497）覆盖了屏幕对象的核心行为。测试文件顶部（Lib/test/test_turtle.py#L58-L80）还包含专门用于无显示环境测试的_Screenmock 补丁——它通过替换turtle._Screen类本身来模拟屏幕，并委托真实TurtleScreen方法完成颜色校验等逻辑，这印证了 turtle 测试体系对"无 GUI 环境下测试屏幕行为"的既有支持。

验证本次修复的推荐做法：

1. 在具备图形界面的环境（或xvfb-run虚拟显示）中运行上文 5.3 节的复现脚本；
2. 修复前：screen.bye()之后的第一条 turtle 命令抛出turtle.Terminator；
3. 修复后：新屏幕正常创建，第一条命令正常执行；
4. 运行既有测试套件确认无回归：

# 在 CPython 源码根目录下（仓库为只读，请复制到可写目录后执行） python -m unittest test.test_turtle

七、总结与启示

本次 gh-issue-70758 修复虽只有一行核心代码（Lib/turtle.py#L1005-L1006），却完整展示了 CPython 标准库中一类典型的生命周期状态管理问题：

• Terminator是 turtle 的执行中断信号，服务于演示查看器等"窗口关闭即停脚本"的场景；
• TurtleScreen._RUNNING是贯穿全局的运行开关，与屏幕单例（_Screen._root/_canvas）、turtle 单例（Turtle._pen/_screen）共同组成屏幕生命周期状态机；
• 窗口销毁路径（bye()/WM_DELETE_WINDOW→_destroy）会同时清空单例引用并关闭运行标志，因此"重建屏幕"必须同步复位运行标志，否则就会在第一条命令处触发Terminator。

对于使用 turtle 编写多窗口、可循环运行图形的开发者，理解这套机制有助于规避"窗口关闭后状态残留"类问题；对于阅读 CPython 源码的开发者，Lib/turtle.py 中_incrementudc、__func_body与_destroy三处的联动，则是一个值得借鉴的"全局状态 + 惰性单例 + 协议回调"设计范例。

【免费下载链接】cpythonThe Python programming language项目地址: https://gitcode.com/GitHub_Trending/cp/cpython