理解 PySimpleGUI 与线程安全问题
pysimplegui 库底层基于 tkinter，而 tkinter 作为一个传统的 gui 框架，其所有 gui 相关的操作都必须在主线程中执行。这意味着，任何尝试从非主线程（例如，由 logging.handler 在后台任务中触发）直接修改 gui 元素（如 sg.multiline 文本框）的行为，都将违反这一原则，从而抛出 runtimeerror: main thread is not in main loop 异常。
当一个长时间运行的操作（如 GitPython 方法调用）在后台线程中执行，并尝试通过自定义的 logging.Handler 将其输出实时显示到 PySimpleGUI 的多行文本框时，如果 emit 方法中直接调用了 self.window["-OUTPUT-"].print() 或 self.window.refresh() 等 GUI 更新函数，就会触发上述错误。这是因为日志记录器可能在后台线程中处理日志消息，而这些线程并非 GUI 的主线程。
解决方案：利用事件队列进行跨线程通信
为了安全地从后台线程或 logging.Handler 更新 PySimpleGUI 界面，我们必须遵循“所有 GUI 更新都在主线程中进行”的原则。PySimpleGUI 提供了一个优雅的解决方案：window.write_event_value()。这个方法允许任何线程向主事件循环发送一个自定义事件和相关值。主事件循环在 window.read() 期间会捕获这些事件，并在主线程中安全地执行相应的 GUI 更新操作。
步骤一：修改 logging.Handler 以发送事件
不再直接在 emit 方法中更新 GUI，而是使用 window.write_event_value() 将日志消息作为事件数据发送出去。
import PySimpleGUI as sg
import logging
import threading
import time
# 定义一个自定义的日志处理器，用于将日志消息发送到 PySimpleGUI 事件队列
class OutputHandler(logging.Handler):
def __init__(self, window: sg.Window, level=logging.INFO):
super().__init__(level)
self.window = window
# 定义一个唯一的事件键，用于在主事件循环中识别此消息
self.event_key = "LOG_MESSAGE_EVENT"
def emit(self, record):
try:
msg = self.format(record) # 格式化日志消息
# 不直接更新 GUI，而是将消息作为事件值发送到主事件循环
self.window.write_event_value(self.event_key, msg)
except Exception:
self.handleError(record)
# 示例：一个模拟长时间运行的任务，它会产生日志输出
def long_running_task(logger: logging.Logger):
logger.info("任务开始...")
for i in range(1, 6):
time.sleep(1) # 模拟耗时操作
logger.info(f"处理进度：{i * 20}%")
logger.info("任务完成！")
在上述代码中，OutputHandler 的 emit 方法不再直接操作 self.window["-OUTPUT-"].print(record.msg)。取而代之的是，它调用 self.window.write_event_value(self.event_key, msg)。这里的 self.event_key 是一个自定义的字符串，用于标识这个事件，msg 则是我们想要显示在 GUI 上的日志消息。
步骤二：在主事件循环中处理事件并更新 GUI
在 PySimpleGUI 的主事件循环中，我们需要监听 OutputHandler 发送的自定义事件。当捕获到该事件时，我们从 values 字典中获取日志消息，并在主线程中安全地将其打印到 sg.Multiline 元素。
# GUI 布局
layout = [
[sg.Multiline(size=(80, 20), key="-OUTPUT-", autoscroll=True, auto_refresh=True, enable_events=True)],
[sg.Button("启动任务", key="-START_TASK-"), sg.Button("退出")]
]
# 创建窗口
window = sg.Window("PySimpleGUI 日志实时显示示例", layout, finalize=True)
# 配置日志记录器
logger = logging.getLogger(__name__)
logger.setLevel(logging.INFO)
# 创建并添加自定义处理器
output_handler = OutputHandler(window)
logger.addHandler(output_handler)
# 主事件循环
while True:
event, values = window.read()
if event == sg.WIN_CLOSED or event == "退出":
break
elif event == "-START_TASK-":
# 启动长时间运行的任务，将其放入一个单独的线程以避免阻塞 GUI
# 也可以使用 sg.Window.perform_long_operation()
threading.Thread(target=long_running_task, args=(logger,), daemon=True).start()
window["-START_TASK-"].update(disabled=True) # 禁用按钮，防止重复点击
elif event == output_handler.event_key: # 捕获自定义日志事件
# 在主线程中安全地更新 Multiline 元素
window["-OUTPUT-"].print(values[output_handler.event_key])
window.close()
在 while True: 循环中，window.read() 会等待事件。当 OutputHandler 通过 write_event_value 发送事件时，window.read() 会返回 output_handler.event_key 作为 event，并将日志消息作为 values[output_handler.event_key]。此时，我们就可以安全地调用 window["-OUTPUT-"].print() 来更新界面。
处理长时间运行的操作
如果触发日志输出的后台操作本身就是长时间运行的，并且会阻塞 GUI 事件循环，那么这个操作也应该被放到一个单独的线程中执行。在上面的示例中，我们使用 threading.Thread 来启动 long_running_task。PySimpleGUI 也提供了 window.perform_long_operation() 或 window.start_thread() 等便捷方法来处理这类场景，它们本质上也是在后台启动一个线程。
注意事项与最佳实践
- GUI 更新必须在主线程： 这是核心原则，也是避免 RuntimeError 的关键。window.write_event_value() 是实现这一点的推荐方式。
- 事件键的唯一性： 确保用于 write_event_value 的事件键是唯一的，以避免与其他 PySimpleGUI 元素的事件或自定义事件冲突。
- 日志格式化： 在 OutputHandler 的 emit 方法中，使用 self.format(record) 可以确保日志消息按照配置的格式器进行格式化，然后再发送到 GUI。
- 线程管理： 对于长时间运行的任务，务必将其放在单独的线程中执行，以保持 GUI 的响应性。如果任务结束后需要更新 GUI 状态（如重新启用按钮），同样可以通过 write_event_value 发送一个完成事件。
- 错误处理： 在 emit 方法中添加 try-except 块，可以捕获日志处理过程中可能发生的异常，防止日志系统崩溃。
总结
通过将 logging.Handler 的 GUI 更新逻辑从直接操作 GUI 元素改为通过 window.write_event_value() 发送自定义事件，我们成功地解决了 PySimpleGUI 中跨线程更新 GUI 导致的 RuntimeError 问题。这种模式确保了所有 GUI 操作都在主线程中安全执行，同时允许后台任务实时地向用户界面提供反馈，从而构建出响应更佳、更稳定的 PySimpleGUI 应用程序。
