简介《Rapid GUI Programming with Python and Qt》随书源文件面向想利用Python与Qt快速开发原生桌面应用的程序员适合已有Python语法基础、想通过PyQt/PySide进入GUI开发领域的读者。资源以zip压缩包提供整体大小约926KB文件总数标注为0内容以Python脚本等书内各章节示例源码为核心。源码主题涵盖Qt部件窗口、按钮、标签、文本框、菜单、对话框等、布局管理网格、垂直、水平布局、信号与槽对象通信、事件处理、MVC模型/视图架构、文件I/O、网络编程、多线程、数据库交互、国际化翻译机制以及资源打包等关键内容基本对应书中全部实验与重点小节。学习时可将这些源码作为对照案例逐段拆解界面构建与逻辑封装方式理解PyQt/Qt类库的调用层次并借助实际运行观察信号触发与槽函数回调过程从而提升GUI程序调试和排错能力。该压缩包已被184人学习适合结合原文按章节推进、动手复现书中示例的中级Python开发者使用。1. 反直觉结论这套源码的价值比正文高出一个量级很多开发者拿到《Rapid GUI Programming with Python and Qt》的源文件第一反应是“书都读完了代码没什么好看的”。我的看法正好相反这套 source code 的价值比正文高出一个量级。它不是一个 hello world 合集而是一组可运行的桌面程序覆盖了窗口生命周期、信号槽、数据库表格、QPainter 绘图、QThread 多线程这些 PyQt 开发中最常遇见的场景。对正在用 Python 写内部工具、想快速给脚本加界面的人来说这是最省事的临摹模板。接下来我按目录、运行、踩坑、改造的顺序把这套代码彻底拆开。2. 源码包解剖目录结构与技术栈选型2.1 目录结构按章节组织但真正要读的是 examples解压之后你会看到十几个 chapter 开头的文件夹从 chapter01 一直到 chapter13每一章对应书里的一个专题。文件夹内部没有额外的嵌套工程所有 .py 文件平铺一层这样找文件很方便不用翻目录。我一般先用find或tree快速扫一遍把每个文件夹里的文件名当成“功能索引”。RapidGUI_Python_Qt_sourcecode/ ├── chapter01/ │ ├── age.py │ ├── hello.py │ └── pad.py ├── chapter02/ │ ├── executor.py │ └── ... ├── chapter03/ │ ├── findcontacts.py │ └── ... ├── chapter06/ │ ├── texteditor.py │ └── ... ├── chapter08/ │ ├── dataplotter.py │ └── ... └── chapter13/ └── ...这个列表不是完整输出但能看到规律chapter01 以最简单的对话框为主chapter02 开始出现执行外部进程的窗口chapter03 里通常有一个联系人生成和查找工具chapter06 里是简易文本编辑器chapter08 里是数据绘图窗口chapter13 则涉及打包部署。实际运行时这些脚本绝大多数都可以独立执行入口都写在if __name__ __main__:下面。如果你想移植到别的项目优先从 chapter02、chapter03 和 chapter06 抽代码因为它们对依赖的耦合最少。这里的文件名是我根据常见版本补全的实际压缩包可能略有差异但不影响定位。找文件有个小技巧用grep -r class .*Window *.py快速看到每个文件定义了哪些窗口类比逐个打开快得多。还有一个习惯是先用python -m py_compile xxx.py做语法检查能提前暴露一批 Python 2 语法残留。2.2 技术栈选型PyQt 4 时代的写法为什么还值得看这套源码最初基于 PyQt 4 编写对应 Python 2 时代。看到QtGui、exec_、QString这些东西时别急着关掉因为 PyQt 4 和 PyQt 5/6 的核心架构是一脉相承的。我的经验是老代码更能暴露“Qt 真正在做什么”新版封装把这些细节藏掉了。比如老代码里频繁出现的QObject.connect和SIGNAL/SLOT宏能让你理解信号槽的字符串匹配机制理解了那套旧机制再看新式signal.connect(slot)就觉得理所当然。技术栈选型上如果你只是想把这套源码跑起来装一个绑定即可。主流选择是 PyQt5 或 PySide6两者 API 几乎相同只有导入前缀和少数工具命令不同。我一般会选 PySide6因为授权更宽松且对 Qt 官方功能覆盖齐全但如果要兼容书里的旧代码PyQt5 的pyuic5、pyrcc5工具链更顺手。Python 解释器请用 3.8 以上版本老代码里的print语句、xrange等 Python 2 语法需要顺手改掉这部分我在第 5 章会展开。从架构视角看这套源码里绝大多数脚本都在重复同一个模式创建一个QApplication创建一个继承QMainWindow或QDialog的窗口类构造函数里初始化子控件最后在main尾部调用app.exec_()。这个模式看起来像模板代码但它其实是 Qt 事件循环的核心——没有exec_()窗口会一闪而过。理解了这个模式你就能把任何脚本快速改造为自己的应用骨架。2.3 文件类型清单.py、.ui、.qrc、.png 各是什么角色源码包不只有 .py还有不少配套资源文件。我习惯用下面的表把它们分类后缀角色处理方式.py主程序逻辑包含窗口、业务、测试入口直接用 Python 运行.ui用 Qt Designer 绘制的界面 XMLpyuic5/pyside6-uic 编译为 .py.qrc资源清单声明图标、图片、翻译文件pyrcc5/pyside6-rcc 编译为 .py.png 等图标、插图由 .qrc 引用随资源模块编译.db 或 .sqliteSQLite 数据库用于数据库章节程序内用 SQL 读取.ui文件最容易造成困惑。它保存的是一段 XML不是 Python。常见做法是运行pyuic5 myform.ui -o ui_myform.py生成一个包含Ui_MyForm类的模块。接着在你的主窗口类里这样用from ui_myform import Ui_MyForm class MyWindow(QMainWindow): def __init__(self): super().__init__() self.ui Ui_MyForm() self.ui.setupUi(self)setupUi(self)会把 .ui 里的按钮、文本框全部绑定到 self.ui 上之后你可以在类里写self.ui.pushButton.clicked.connect(...)。.qrc资源文件同理运行pyrcc5 resources.qrc -o resources_rc.py后主程序只要import resources_rc就能在代码里用:/icons/open.png这样的路径引用图片。这里有个关键点每次修改 .qrc 后必须重新生成资源模块否则新资源不会生效。我见过很多人在这一步翻车因为资源模块已经是编译好的黑匣子忘记重编译时界面图标会异常消失且没有任何报错。3. 核心模块拆解从 QApplication 到信号槽的完整落地3.1 入口与主窗口QApplication 与 QMainWindow 的样板几乎每个示例文件都长着一个相似的骨架。先把最精简的版本贴出来import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QLabel class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(Rapid GUI Demo) self.resize(480, 320) self.label QLabel(Ready, self) self.setCentralWidget(self.label) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())逻辑上分三块。QApplication(sys.argv)是所有 Qt 程序的起点它创建应用对象并解析系统级参数比如-style、-stylesheet这些参数会通过sys.argv传进去。MainWindow继承QMainWindow好处是自带菜单栏、状态栏、停靠窗口的骨架setCentralWidget用来放置中心控件。app.exec_()启动事件循环程序在这里不断处理鼠标、键盘、定时器事件直到窗口关闭或调用quit。参数说明resize(480, 320)的宽高以像素为单位和普通窗口一样如果希望窗口内容自适应可以用layout加setMinimumSize。QLabel(self)的第二个参数是父对象Qt 的父子对象机制用来管理内存子对象在父对象销毁时一起销毁这也是为什么示例里大量使用parentself。如果省略父对象标签就变成顶级窗口会单独弹出来这是个很容易看走眼的点。老版本源码里这一段的差异主要在exec_()和QMainWindow的导入位置。如果从书里原样拷贝到 PySide6 会立刻报错因为 PySide6 的QApplication在PySide6.QtWidgets而且exec_已经改名为exec。迁移时我通常只改导入和这一行其他部分几乎原封不动。很多老示例会用QDialog而不是QMainWindow作为顶层窗口这时没有setCentralWidget而是直接layout.addWidget(...)两种骨架要分清楚。3.2 信号槽与事件循环按钮点击背后的调用链窗口骨架只是空壳真正让程序响应用户操作的是信号槽。源码里最典型的一段是按钮点击后更新界面from PyQt5.QtCore import pyqtSlot from PyQt5.QtWidgets import QPushButton, QVBoxLayout, QWidget class CounterWindow(QMainWindow): def __init__(self): super().__init__() self.count 0 self.button QPushButton(Click me) self.button.clicked.connect(self.on_click) container QWidget() layout QVBoxLayout(container) layout.addWidget(self.button) self.setCentralWidget(container) pyqtSlot() def on_click(self): self.count 1 self.button.setText(fClicked {self.count} times)这里的关键是clicked.connect(self.on_click)。当按钮被点击时Qt 发出clicked信号事件循环在下一轮把信号投递给已连接的槽函数。槽函数里的setText会触发重绘事件按钮显示立即变化。这个连接是单向的一个信号可以连接多个槽槽也可以由不同信号触发。老式写法是connect(button, SIGNAL(clicked()), self.on_click)问题在于信号名是字符串Qt 靠运行时解析字符串匹配一旦槽函数参数数量写错连接会静默失败。新版用方法引用编译阶段就能发现一部分问题。pyqtSlot()装饰器不是必需的但建议加上。它有两个实际作用一是让信号重载时能更高效地分发二是让inspect.signature能正确显示槽类型。在 PyQt5 里不装饰也能工作但在 PySide6 里某些跨线程队列连接需要它来明确槽的参数类型。源码里有些示例写了这个装饰器有些没写这正好用来观察两种写法的差异。参数说明QVBoxLayout把子控件垂直排列layout.addWidget加入控件后布局会接管其几何尺寸。注意container QWidget()是必需的中间层因为setCentralWidget只能接收一个控件而布局必须挂到某个容器上。如果你直接把布局设成窗口的布局按钮会缩在角落。另一个需要注意的参数是clicked信号本身带一个bool参数表示按钮是否处于选中状态如果槽函数定义成无参连接符会忽略这个参数规则比较宽松但反过来槽函数带参而信号无参就会报错。3.3 资源与配置QSettings 与 .qrc 的加载逻辑桌面程序必不可少的两件事持久化配置和引用资源。源码里有一组示例专门演示这两点。from PyQt5.QtCore import QSettings settings QSettings(TestCompany, TestApp) last_file settings.value(lastFile, ) settings.setValue(windowWidth, self.width())QSettings的构造参数是组织名和应用名它决定配置存储在用户目录下的哪个 key。在 Windows 上写入注册表在 Linux 上写~/.config/TestCompany/TestApp.conf在 macOS 上写 plist。读取时value(lastFile, )的第二个参数是默认值如果 key 不存在就返回默认值。这个用法在源码里大量出现用来记住窗口位置、最近打开的文件列表。要注意value返回的可能是QString老版本或 Pythonstr新版本推荐先强制转成str()否则后续拼接路径容易出类型错误。.qrc 资源的加载稍微绕一点。假设resources.qrc声明了一个 open.pngicon QIcon(:/icons/open.png)以:/开头的路径是 Qt 资源系统的虚拟路径。为了让:/路径可用必须先运行编译工具pyrcc5 resources.qrc -o resources_rc.py然后在入口文件里写一句import resources_rc。这个 import 的作用是执行资源注册模块把图标的数据编译进 Python 字节码中之后程序不用带单独的图片文件。注意如果在窗口类里 importresources_rc顺序要在创建QApplication之前否则某些平台在初始化资源时会报错。我一般把import resources_rc放在import sys之后。还有一个容易被忽略的点如果图片文件路径里有中文编译出来的资源名也会包含中文在代码里写路径时编码要一致否则找不到资源。用纯英文路径命名图片是最省心的方案。4. 运行方法把这套源码从磁盘变成可点击的窗口4.1 环境准备Python 版本与 Qt 绑定选择在运行任意一个示例前先把环境装好。我的推荐组合是 Python 3.10 PyQt5原因有两条一是 PyQt5 的pyuic5和pyrcc5工具命令最接近书中的说明二是 PyQt5 在 Windows 和 Linux 上二进制安装包最全。如果你更偏好 PySide6API 兼容性也没问题但工具命令是pyside6-uic和pyside6-rcc导入前缀是PySide6。两者不要混装混装同一个QMainWindow来自不同绑定会导致类型混乱运行时可能出现QWidget: Cannot create a QWidget without QApplication这类玄学报错实际上是导入错位。创建虚拟环境是必须的除非你只想要一台测试机。用 venv 隔离后再折腾也不怕弄脏系统 Pythonpython -m venv pyqt_env source pyqt_env/bin/activate pip install pyqt5 pyqt5-tools在 Windows 上第二行换成pyqt_env\Scripts\activate。pyqt5-tools不是核心库但它包含了 Qt Designer 和几个辅助工具调试 .ui 文件时用得上。如果你只想跑源码装pyqt5就够。安装过程中如果遇到编译超时多半是 pip 在尝试从源码编译换用国内镜像源可以大幅提速这不是代码问题。安装完成后验证一行命令python -c from PyQt5.QtWidgets import QApplication; print(QApplication.instance())能打印出 None 或 application 对象说明导入正常。这一步是为了提前排除 32/64 位 Python 和 Qt 库不匹配的问题。如果报 DLL 加载失败先检查 Python 位数再检查是不是装了两个版本的 PyQt卸载干净重装一次。这些环境问题最消耗时间所以我把验证命令单独列出来能省五分钟就是五分钟。4.2 从命令行跑起第一个示例环境就绪后进入源码目录cd chapter01 python age.pyage.py 是一个年龄输入对话框跑起来后会出现一个小窗口输入年龄点击按钮后会弹出一条结果消息。如果一切正常你会看到窗口正常显示如果控制台输出异常先别急99% 是下面三类问题之一导入QtGui失败、exec_()不存在、字符串编码错误。这三类的具体解法放第 5 章。跑示例时建议先跑 chapter01 和 chapter02这两个文件夹的脚本依赖最少能快速验证绑定环境是否正常。如果你在一个示例上成功了可以批量验证其他章节。我常用的方式是写一个循环脚本for f in chapter*/main*.py chapter*/*.py; do timeout 3 python $f /dev/null 21 echo OK $f || echo FAIL $f done注意很多 GUI 脚本运行后不会主动退出python main.py会一直停留在事件循环里所以上面的循环对每个文件最多能看到它启动不启动无法自动关闭。timeout 3表示三秒后强制结束判断退出码。如果某个文件在 3 秒内因为语法错误崩溃退出码非 0循环会标成 FAIL。这样能快速筛出需要改造的文件。Linux 和 macOS 自带 timeoutWindows 没有可以用powershell的Start-Process加-TimeoutSec或者干脆手动跑。4.3 把 .ui 文件编译成 Python 可导入的模块有些示例的界面是用 Qt Designer 画的运行时需要.ui文件编译出来的模块。手动编译一次pyuic5 myform.ui -o ui_myform.pypyuic5在pyqt5-tools或 PyQt5 安装目录的 Scripts 下。执行后生成ui_myform.py它定义了一个Ui_MyForm类里面有一个setupUi(self, target)方法。使用方法我已经在第 2 章写过这里补充一个常见姿势把界面和逻辑分离不直接改ui_myform.py而是新建main.py导入它这样重新生成界面模块时你的业务代码不会丢失。除了 .ui还有.qrc资源文件需要编译pyrcc5 resources.qrc -o resources_rc.py编译出来的resources_rc.py体积可能很大因为图片的 base64 数据都在里面。运行主程序前确保它被 import否则:/icons/open.png路径会返回空图标。检查一个资源是否注册成功可以用QDir列出资源系统from PyQt5.QtCore import QDir print(QDir(:/icons).entryList())能列出文件就说明编译成功。如果列表为空多半是编译出的 .py 没有被导入或者 .qrc 的路径写错了。这里的陷阱是.qrc文件里的路径是相对.qrc文件所在目录的如果你把.qrc移动了图片路径失效编译不会报错只是运行时图标为空。我习惯把.qrc和图片放在同一目录路径尽量不用..回退。5. 避坑手册PyQt 老代码迁移时最容易翻车的 5 个点下面这五条全是我实际迁移这份源码时踩过的每一条都对应一个具体的运行期报错或界面异常。按“现象、原因、解决”的顺序写方便你直接对照。5.1 现象一exec_()提示对象没有此属性现象运行python age.py立即抛出AttributeError: QApplication object has no attribute exec_。原因书里的源码写于 PyQt 4 时代为了避开 Python 2 的exec关键字QApplication 提供了exec_()别名。PyQt5 仍保留了这个别名但 PySide6 去掉了它如果你把源码移植到 PySide6就会看到这个错误。即便不用 PySide6也建议改成exec()因为新项目里看到exec_()总让人怀疑是不是老古董。解决全局替换。在项目目录下执行grep -rl exec_() chapter* | xargs sed -i s/exec_()/exec()/g如果你没有 sed 习惯直接编辑器里全局替换即可。替换后重新运行问题消失。注意替换时别把普通方法里的exec_也替换了比如某个槽函数叫execute_这里只匹配exec_()所以安全。另一个附带问题QDialog的exec_()也要改格式相同。这条的附带教训老源码的 API 别名非常多除了exec_还有QString、QImage等类型在新版本中被移除了。所以迁移前先做一个全局 grep 扫描所有带下划线的 Qt 方法列出所有xxx_()调用一个一个过。5.2 现象二from PyQt4.QtGui import QMainWindow找不到模块现象导入行直接报ModuleNotFoundError: No module named PyQt4或者ImportError: cannot import name QMainWindow from PyQt4.QtGui。原因PyQt5 把 PyQt4 的QtGui拆成QtWidgets和QtGui两个模块。控件类比如 QMainWindow、QPushButton、QLabel、QTextEdit这些在QtWidgets绘图类比如 QPainter、QColor、QPen这些留在QtGui核心类比如 QObject、QSettings这些在QtCore。PyQt6 进一步把 QAction 挪到QtGuiQShortcut 挪到QtGui。所以单纯把PyQt4改成PyQt5仍然会缺类。解决先写一个兼容导入层集中处理差异。我给你一个 shim 文件# compat.py try: from PyQt5.QtWidgets import * from PyQt5.QtGui import QPainter, QColor, QPen from PyQt5.QtCore import * except ImportError: from PySide6.QtWidgets import * from PySide6.QtGui import QPainter, QColor, QPen from PySide6.QtCore import *然后把你源码里所有from PyQt4.QtGui import ...改成from compat import *。这种集中导入的方式比逐文件改QtWidgets快得多但要注意名称冲突和模块内部的相互引用。实际工程中我一般不会长期依赖 shim而是用它把项目跑通后再逐步把from compat import *改成显式导入。5.3 现象三中文字符在按钮上显示成乱码现象界面上的中文变成????或方块英文正常。原因老代码基于 Python 2字符串默认是 bytes代码文件头部没有# -*- coding: utf-8 -*-传给 Qt 的字符串按系统默认编码解释中文就乱了。Python 3 默认 str 是 Unicode同样代码在迁移到 Python 3 后多数情况会自愈但 Windows 控制台代码页是 GBK 时从配置文件读出的中文仍需转换。解决分两步。第一步在每个.py文件头部补编码声明Python 3 不必须但建议保留。第二步在创建QApplication前设置 locale最稳妥的方式是import sys from PyQt5.QtCore import QTextCodec QTextCodec.setCodecForLocale(QTextCodec.codecForName(UTF-8)) app QApplication(sys.argv)注意setCodecForLocale只影响本地编码相关接口不影响源码里字符串本身。如果还是乱码就去看窗口标题的来源是不是从.ui文件读的.ui文件头部的 XML 声明encodingUTF-8必须与实际保存一致。遇到.ui文件乱码用 Qt Designer 打开另存一次一般能修。5.4 现象四.ui文件编译后生成的类没办法直接布局现象把Ui_MyForm通过setupUi放到主窗口后所有控件挤在窗口左上角拉伸窗口也不会铺开。原因Qt Designer 里的窗体如果没有给 center widget 设置布局setupUi就只生成控件而不生成 layout。源码里的部分.ui是早期保存的可能没保存布局或者布局类型是 AbsoluteLayout绝对定位。绝对定位在窗口 resize 后不会自动伸缩所以看起来像“没有布局”。解决在 Qt Designer 中打开该 .ui 文件选中中央窗体在工具栏点击“水平布局”或“栅格布局”保存后重新编译。不想打开 Designer 的话也可以手动改 XML在widget元素下补一条layout但手写容易出错我一般还是用 Designer。编译后重新运行按钮就会跟随窗口伸展。这个问题的隐蔽之处在于不报错界面也能打开视觉上只是丑很多新手以为是窗口样式问题去调样式表。排查时先看setupUi生成的代码末尾有没有retranslateUi和布局设置如果没有布局对象就一定是 .ui 的布局层缺失。5.5 现象五SIGNAL/SLOT宏连接不生效现象按钮点击后槽函数没被调用控制台没有任何报错界面也不反应。原因老式写法self.connect(self.button, SIGNAL(clicked()), self.on_click)依赖字符串匹配。Qt 把信号名当成字符串处理槽函数参数个数、类型的差异会导致匹配失败且失败是静默的。比如SIGNAL(clicked())连接一个带参数的槽或者槽写成int而信号不带参数都会失效。解决全部改成新式信号槽语法self.button.clicked.connect(self.on_click)如果槽函数的参数需要精确匹配使用pyqtSlot()显式声明pyqtSlot(bool) def on_checked(self, checked: bool): ...改完后如果在运行时仍然不触发就去确认信号名称有没有拼错比如clicked和click是两回事。还有一个冷门原因如果窗口类没有继承QObject或QWidget新式连接会抛出 TypeError但源码里所有窗口都继承 QMainWindow这个问题在迁移到自己写的类时要额外注意。6. 二次开发思路把示例改造成自己的生产力工具如果只让我保留一个改造示范我会选“给文本编辑器加实时字数统计”。源码里的文本编辑器示例很好地演示了菜单、状态栏、快捷键但没有实时统计。改造的核心不是加文本框而是选对信号。from PyQt5.QtWidgets import QApplication, QMainWindow, QPlainTextEdit, QStatusBar class WordCountEditor(QMainWindow): def __init__(self): super().__init__() self.editor QPlainTextEdit(self) self.setCentralWidget(self.editor) self.status QStatusBar(self) self.setStatusBar(self.status) self.editor.textChanged.connect(self.update_count) self.update_count() def update_count(self): text self.editor.toPlainText() chars len(text) words len(text.split()) self.status.showMessage(fchars: {chars} words: {words}) if __name__ __main__: app QApplication([]) window WordCountEditor() window.show() app.exec_()逻辑说明QPlainTextEdit比QTextEdit更轻量适合纯文本textChanged信号会在每次编辑时发出槽函数里读取全文并统计然后写入QStatusBar。QMainWindow的setStatusBar会创建底部状态栏不需要布局。如果改成QTextEdittoPlainText()同样适用。参数说明len(text.split())对中文分词不准确中文应改用len([c for c in text if not c.isspace()])统计非空白字符数这是对于中文文本更实际的“字数”。这样一套代码就能直接挂在菜单栏“统计”动作上。从那以后我每次拿到类似的 sample code都会先跑一遍再读代码而不是先读代码再跑。遇到 API 差异直接全局替换然后观察信号槽有没有接上窗口显示但按钮无动静首要怀疑信号连接而不是业务逻辑。这个习惯帮我省掉了大量的排错时间。希望帮到你。本文还有配套的精品资源点击获取
简介《Rapid GUI Programming with Python and Qt》随书源文件面向想利用Python与Qt快速开发原生桌面应用的程序员适合已有Python语法基础、想通过PyQt/PySide进入GUI开发领域的读者。资源以zip压缩包提供整体大小约926KB文件总数标注为0内容以Python脚本等书内各章节示例源码为核心。源码主题涵盖Qt部件窗口、按钮、标签、文本框、菜单、对话框等、布局管理网格、垂直、水平布局、信号与槽对象通信、事件处理、MVC模型/视图架构、文件I/O、网络编程、多线程、数据库交互、国际化翻译机制以及资源打包等关键内容基本对应书中全部实验与重点小节。学习时可将这些源码作为对照案例逐段拆解界面构建与逻辑封装方式理解PyQt/Qt类库的调用层次并借助实际运行观察信号触发与槽函数回调过程从而提升GUI程序调试和排错能力。该压缩包已被184人学习适合结合原文按章节推进、动手复现书中示例的中级Python开发者使用。1. 反直觉结论这套源码的价值比正文高出一个量级很多开发者拿到《Rapid GUI Programming with Python and Qt》的源文件第一反应是“书都读完了代码没什么好看的”。我的看法正好相反这套 source code 的价值比正文高出一个量级。它不是一个 hello world 合集而是一组可运行的桌面程序覆盖了窗口生命周期、信号槽、数据库表格、QPainter 绘图、QThread 多线程这些 PyQt 开发中最常遇见的场景。对正在用 Python 写内部工具、想快速给脚本加界面的人来说这是最省事的临摹模板。接下来我按目录、运行、踩坑、改造的顺序把这套代码彻底拆开。2. 源码包解剖目录结构与技术栈选型2.1 目录结构按章节组织但真正要读的是 examples解压之后你会看到十几个 chapter 开头的文件夹从 chapter01 一直到 chapter13每一章对应书里的一个专题。文件夹内部没有额外的嵌套工程所有 .py 文件平铺一层这样找文件很方便不用翻目录。我一般先用find或tree快速扫一遍把每个文件夹里的文件名当成“功能索引”。RapidGUI_Python_Qt_sourcecode/ ├── chapter01/ │ ├── age.py │ ├── hello.py │ └── pad.py ├── chapter02/ │ ├── executor.py │ └── ... ├── chapter03/ │ ├── findcontacts.py │ └── ... ├── chapter06/ │ ├── texteditor.py │ └── ... ├── chapter08/ │ ├── dataplotter.py │ └── ... └── chapter13/ └── ...这个列表不是完整输出但能看到规律chapter01 以最简单的对话框为主chapter02 开始出现执行外部进程的窗口chapter03 里通常有一个联系人生成和查找工具chapter06 里是简易文本编辑器chapter08 里是数据绘图窗口chapter13 则涉及打包部署。实际运行时这些脚本绝大多数都可以独立执行入口都写在if __name__ __main__:下面。如果你想移植到别的项目优先从 chapter02、chapter03 和 chapter06 抽代码因为它们对依赖的耦合最少。这里的文件名是我根据常见版本补全的实际压缩包可能略有差异但不影响定位。找文件有个小技巧用grep -r class .*Window *.py快速看到每个文件定义了哪些窗口类比逐个打开快得多。还有一个习惯是先用python -m py_compile xxx.py做语法检查能提前暴露一批 Python 2 语法残留。2.2 技术栈选型PyQt 4 时代的写法为什么还值得看这套源码最初基于 PyQt 4 编写对应 Python 2 时代。看到QtGui、exec_、QString这些东西时别急着关掉因为 PyQt 4 和 PyQt 5/6 的核心架构是一脉相承的。我的经验是老代码更能暴露“Qt 真正在做什么”新版封装把这些细节藏掉了。比如老代码里频繁出现的QObject.connect和SIGNAL/SLOT宏能让你理解信号槽的字符串匹配机制理解了那套旧机制再看新式signal.connect(slot)就觉得理所当然。技术栈选型上如果你只是想把这套源码跑起来装一个绑定即可。主流选择是 PyQt5 或 PySide6两者 API 几乎相同只有导入前缀和少数工具命令不同。我一般会选 PySide6因为授权更宽松且对 Qt 官方功能覆盖齐全但如果要兼容书里的旧代码PyQt5 的pyuic5、pyrcc5工具链更顺手。Python 解释器请用 3.8 以上版本老代码里的print语句、xrange等 Python 2 语法需要顺手改掉这部分我在第 5 章会展开。从架构视角看这套源码里绝大多数脚本都在重复同一个模式创建一个QApplication创建一个继承QMainWindow或QDialog的窗口类构造函数里初始化子控件最后在main尾部调用app.exec_()。这个模式看起来像模板代码但它其实是 Qt 事件循环的核心——没有exec_()窗口会一闪而过。理解了这个模式你就能把任何脚本快速改造为自己的应用骨架。2.3 文件类型清单.py、.ui、.qrc、.png 各是什么角色源码包不只有 .py还有不少配套资源文件。我习惯用下面的表把它们分类后缀角色处理方式.py主程序逻辑包含窗口、业务、测试入口直接用 Python 运行.ui用 Qt Designer 绘制的界面 XMLpyuic5/pyside6-uic 编译为 .py.qrc资源清单声明图标、图片、翻译文件pyrcc5/pyside6-rcc 编译为 .py.png 等图标、插图由 .qrc 引用随资源模块编译.db 或 .sqliteSQLite 数据库用于数据库章节程序内用 SQL 读取.ui文件最容易造成困惑。它保存的是一段 XML不是 Python。常见做法是运行pyuic5 myform.ui -o ui_myform.py生成一个包含Ui_MyForm类的模块。接着在你的主窗口类里这样用from ui_myform import Ui_MyForm class MyWindow(QMainWindow): def __init__(self): super().__init__() self.ui Ui_MyForm() self.ui.setupUi(self)setupUi(self)会把 .ui 里的按钮、文本框全部绑定到 self.ui 上之后你可以在类里写self.ui.pushButton.clicked.connect(...)。.qrc资源文件同理运行pyrcc5 resources.qrc -o resources_rc.py后主程序只要import resources_rc就能在代码里用:/icons/open.png这样的路径引用图片。这里有个关键点每次修改 .qrc 后必须重新生成资源模块否则新资源不会生效。我见过很多人在这一步翻车因为资源模块已经是编译好的黑匣子忘记重编译时界面图标会异常消失且没有任何报错。3. 核心模块拆解从 QApplication 到信号槽的完整落地3.1 入口与主窗口QApplication 与 QMainWindow 的样板几乎每个示例文件都长着一个相似的骨架。先把最精简的版本贴出来import sys from PyQt5.QtWidgets import QApplication, QMainWindow, QLabel class MainWindow(QMainWindow): def __init__(self): super().__init__() self.setWindowTitle(Rapid GUI Demo) self.resize(480, 320) self.label QLabel(Ready, self) self.setCentralWidget(self.label) if __name__ __main__: app QApplication(sys.argv) window MainWindow() window.show() sys.exit(app.exec_())逻辑上分三块。QApplication(sys.argv)是所有 Qt 程序的起点它创建应用对象并解析系统级参数比如-style、-stylesheet这些参数会通过sys.argv传进去。MainWindow继承QMainWindow好处是自带菜单栏、状态栏、停靠窗口的骨架setCentralWidget用来放置中心控件。app.exec_()启动事件循环程序在这里不断处理鼠标、键盘、定时器事件直到窗口关闭或调用quit。参数说明resize(480, 320)的宽高以像素为单位和普通窗口一样如果希望窗口内容自适应可以用layout加setMinimumSize。QLabel(self)的第二个参数是父对象Qt 的父子对象机制用来管理内存子对象在父对象销毁时一起销毁这也是为什么示例里大量使用parentself。如果省略父对象标签就变成顶级窗口会单独弹出来这是个很容易看走眼的点。老版本源码里这一段的差异主要在exec_()和QMainWindow的导入位置。如果从书里原样拷贝到 PySide6 会立刻报错因为 PySide6 的QApplication在PySide6.QtWidgets而且exec_已经改名为exec。迁移时我通常只改导入和这一行其他部分几乎原封不动。很多老示例会用QDialog而不是QMainWindow作为顶层窗口这时没有setCentralWidget而是直接layout.addWidget(...)两种骨架要分清楚。3.2 信号槽与事件循环按钮点击背后的调用链窗口骨架只是空壳真正让程序响应用户操作的是信号槽。源码里最典型的一段是按钮点击后更新界面from PyQt5.QtCore import pyqtSlot from PyQt5.QtWidgets import QPushButton, QVBoxLayout, QWidget class CounterWindow(QMainWindow): def __init__(self): super().__init__() self.count 0 self.button QPushButton(Click me) self.button.clicked.connect(self.on_click) container QWidget() layout QVBoxLayout(container) layout.addWidget(self.button) self.setCentralWidget(container) pyqtSlot() def on_click(self): self.count 1 self.button.setText(fClicked {self.count} times)这里的关键是clicked.connect(self.on_click)。当按钮被点击时Qt 发出clicked信号事件循环在下一轮把信号投递给已连接的槽函数。槽函数里的setText会触发重绘事件按钮显示立即变化。这个连接是单向的一个信号可以连接多个槽槽也可以由不同信号触发。老式写法是connect(button, SIGNAL(clicked()), self.on_click)问题在于信号名是字符串Qt 靠运行时解析字符串匹配一旦槽函数参数数量写错连接会静默失败。新版用方法引用编译阶段就能发现一部分问题。pyqtSlot()装饰器不是必需的但建议加上。它有两个实际作用一是让信号重载时能更高效地分发二是让inspect.signature能正确显示槽类型。在 PyQt5 里不装饰也能工作但在 PySide6 里某些跨线程队列连接需要它来明确槽的参数类型。源码里有些示例写了这个装饰器有些没写这正好用来观察两种写法的差异。参数说明QVBoxLayout把子控件垂直排列layout.addWidget加入控件后布局会接管其几何尺寸。注意container QWidget()是必需的中间层因为setCentralWidget只能接收一个控件而布局必须挂到某个容器上。如果你直接把布局设成窗口的布局按钮会缩在角落。另一个需要注意的参数是clicked信号本身带一个bool参数表示按钮是否处于选中状态如果槽函数定义成无参连接符会忽略这个参数规则比较宽松但反过来槽函数带参而信号无参就会报错。3.3 资源与配置QSettings 与 .qrc 的加载逻辑桌面程序必不可少的两件事持久化配置和引用资源。源码里有一组示例专门演示这两点。from PyQt5.QtCore import QSettings settings QSettings(TestCompany, TestApp) last_file settings.value(lastFile, ) settings.setValue(windowWidth, self.width())QSettings的构造参数是组织名和应用名它决定配置存储在用户目录下的哪个 key。在 Windows 上写入注册表在 Linux 上写~/.config/TestCompany/TestApp.conf在 macOS 上写 plist。读取时value(lastFile, )的第二个参数是默认值如果 key 不存在就返回默认值。这个用法在源码里大量出现用来记住窗口位置、最近打开的文件列表。要注意value返回的可能是QString老版本或 Pythonstr新版本推荐先强制转成str()否则后续拼接路径容易出类型错误。.qrc 资源的加载稍微绕一点。假设resources.qrc声明了一个 open.pngicon QIcon(:/icons/open.png)以:/开头的路径是 Qt 资源系统的虚拟路径。为了让:/路径可用必须先运行编译工具pyrcc5 resources.qrc -o resources_rc.py然后在入口文件里写一句import resources_rc。这个 import 的作用是执行资源注册模块把图标的数据编译进 Python 字节码中之后程序不用带单独的图片文件。注意如果在窗口类里 importresources_rc顺序要在创建QApplication之前否则某些平台在初始化资源时会报错。我一般把import resources_rc放在import sys之后。还有一个容易被忽略的点如果图片文件路径里有中文编译出来的资源名也会包含中文在代码里写路径时编码要一致否则找不到资源。用纯英文路径命名图片是最省心的方案。4. 运行方法把这套源码从磁盘变成可点击的窗口4.1 环境准备Python 版本与 Qt 绑定选择在运行任意一个示例前先把环境装好。我的推荐组合是 Python 3.10 PyQt5原因有两条一是 PyQt5 的pyuic5和pyrcc5工具命令最接近书中的说明二是 PyQt5 在 Windows 和 Linux 上二进制安装包最全。如果你更偏好 PySide6API 兼容性也没问题但工具命令是pyside6-uic和pyside6-rcc导入前缀是PySide6。两者不要混装混装同一个QMainWindow来自不同绑定会导致类型混乱运行时可能出现QWidget: Cannot create a QWidget without QApplication这类玄学报错实际上是导入错位。创建虚拟环境是必须的除非你只想要一台测试机。用 venv 隔离后再折腾也不怕弄脏系统 Pythonpython -m venv pyqt_env source pyqt_env/bin/activate pip install pyqt5 pyqt5-tools在 Windows 上第二行换成pyqt_env\Scripts\activate。pyqt5-tools不是核心库但它包含了 Qt Designer 和几个辅助工具调试 .ui 文件时用得上。如果你只想跑源码装pyqt5就够。安装过程中如果遇到编译超时多半是 pip 在尝试从源码编译换用国内镜像源可以大幅提速这不是代码问题。安装完成后验证一行命令python -c from PyQt5.QtWidgets import QApplication; print(QApplication.instance())能打印出 None 或 application 对象说明导入正常。这一步是为了提前排除 32/64 位 Python 和 Qt 库不匹配的问题。如果报 DLL 加载失败先检查 Python 位数再检查是不是装了两个版本的 PyQt卸载干净重装一次。这些环境问题最消耗时间所以我把验证命令单独列出来能省五分钟就是五分钟。4.2 从命令行跑起第一个示例环境就绪后进入源码目录cd chapter01 python age.pyage.py 是一个年龄输入对话框跑起来后会出现一个小窗口输入年龄点击按钮后会弹出一条结果消息。如果一切正常你会看到窗口正常显示如果控制台输出异常先别急99% 是下面三类问题之一导入QtGui失败、exec_()不存在、字符串编码错误。这三类的具体解法放第 5 章。跑示例时建议先跑 chapter01 和 chapter02这两个文件夹的脚本依赖最少能快速验证绑定环境是否正常。如果你在一个示例上成功了可以批量验证其他章节。我常用的方式是写一个循环脚本for f in chapter*/main*.py chapter*/*.py; do timeout 3 python $f /dev/null 21 echo OK $f || echo FAIL $f done注意很多 GUI 脚本运行后不会主动退出python main.py会一直停留在事件循环里所以上面的循环对每个文件最多能看到它启动不启动无法自动关闭。timeout 3表示三秒后强制结束判断退出码。如果某个文件在 3 秒内因为语法错误崩溃退出码非 0循环会标成 FAIL。这样能快速筛出需要改造的文件。Linux 和 macOS 自带 timeoutWindows 没有可以用powershell的Start-Process加-TimeoutSec或者干脆手动跑。4.3 把 .ui 文件编译成 Python 可导入的模块有些示例的界面是用 Qt Designer 画的运行时需要.ui文件编译出来的模块。手动编译一次pyuic5 myform.ui -o ui_myform.pypyuic5在pyqt5-tools或 PyQt5 安装目录的 Scripts 下。执行后生成ui_myform.py它定义了一个Ui_MyForm类里面有一个setupUi(self, target)方法。使用方法我已经在第 2 章写过这里补充一个常见姿势把界面和逻辑分离不直接改ui_myform.py而是新建main.py导入它这样重新生成界面模块时你的业务代码不会丢失。除了 .ui还有.qrc资源文件需要编译pyrcc5 resources.qrc -o resources_rc.py编译出来的resources_rc.py体积可能很大因为图片的 base64 数据都在里面。运行主程序前确保它被 import否则:/icons/open.png路径会返回空图标。检查一个资源是否注册成功可以用QDir列出资源系统from PyQt5.QtCore import QDir print(QDir(:/icons).entryList())能列出文件就说明编译成功。如果列表为空多半是编译出的 .py 没有被导入或者 .qrc 的路径写错了。这里的陷阱是.qrc文件里的路径是相对.qrc文件所在目录的如果你把.qrc移动了图片路径失效编译不会报错只是运行时图标为空。我习惯把.qrc和图片放在同一目录路径尽量不用..回退。5. 避坑手册PyQt 老代码迁移时最容易翻车的 5 个点下面这五条全是我实际迁移这份源码时踩过的每一条都对应一个具体的运行期报错或界面异常。按“现象、原因、解决”的顺序写方便你直接对照。5.1 现象一exec_()提示对象没有此属性现象运行python age.py立即抛出AttributeError: QApplication object has no attribute exec_。原因书里的源码写于 PyQt 4 时代为了避开 Python 2 的exec关键字QApplication 提供了exec_()别名。PyQt5 仍保留了这个别名但 PySide6 去掉了它如果你把源码移植到 PySide6就会看到这个错误。即便不用 PySide6也建议改成exec()因为新项目里看到exec_()总让人怀疑是不是老古董。解决全局替换。在项目目录下执行grep -rl exec_() chapter* | xargs sed -i s/exec_()/exec()/g如果你没有 sed 习惯直接编辑器里全局替换即可。替换后重新运行问题消失。注意替换时别把普通方法里的exec_也替换了比如某个槽函数叫execute_这里只匹配exec_()所以安全。另一个附带问题QDialog的exec_()也要改格式相同。这条的附带教训老源码的 API 别名非常多除了exec_还有QString、QImage等类型在新版本中被移除了。所以迁移前先做一个全局 grep 扫描所有带下划线的 Qt 方法列出所有xxx_()调用一个一个过。5.2 现象二from PyQt4.QtGui import QMainWindow找不到模块现象导入行直接报ModuleNotFoundError: No module named PyQt4或者ImportError: cannot import name QMainWindow from PyQt4.QtGui。原因PyQt5 把 PyQt4 的QtGui拆成QtWidgets和QtGui两个模块。控件类比如 QMainWindow、QPushButton、QLabel、QTextEdit这些在QtWidgets绘图类比如 QPainter、QColor、QPen这些留在QtGui核心类比如 QObject、QSettings这些在QtCore。PyQt6 进一步把 QAction 挪到QtGuiQShortcut 挪到QtGui。所以单纯把PyQt4改成PyQt5仍然会缺类。解决先写一个兼容导入层集中处理差异。我给你一个 shim 文件# compat.py try: from PyQt5.QtWidgets import * from PyQt5.QtGui import QPainter, QColor, QPen from PyQt5.QtCore import * except ImportError: from PySide6.QtWidgets import * from PySide6.QtGui import QPainter, QColor, QPen from PySide6.QtCore import *然后把你源码里所有from PyQt4.QtGui import ...改成from compat import *。这种集中导入的方式比逐文件改QtWidgets快得多但要注意名称冲突和模块内部的相互引用。实际工程中我一般不会长期依赖 shim而是用它把项目跑通后再逐步把from compat import *改成显式导入。5.3 现象三中文字符在按钮上显示成乱码现象界面上的中文变成????或方块英文正常。原因老代码基于 Python 2字符串默认是 bytes代码文件头部没有# -*- coding: utf-8 -*-传给 Qt 的字符串按系统默认编码解释中文就乱了。Python 3 默认 str 是 Unicode同样代码在迁移到 Python 3 后多数情况会自愈但 Windows 控制台代码页是 GBK 时从配置文件读出的中文仍需转换。解决分两步。第一步在每个.py文件头部补编码声明Python 3 不必须但建议保留。第二步在创建QApplication前设置 locale最稳妥的方式是import sys from PyQt5.QtCore import QTextCodec QTextCodec.setCodecForLocale(QTextCodec.codecForName(UTF-8)) app QApplication(sys.argv)注意setCodecForLocale只影响本地编码相关接口不影响源码里字符串本身。如果还是乱码就去看窗口标题的来源是不是从.ui文件读的.ui文件头部的 XML 声明encodingUTF-8必须与实际保存一致。遇到.ui文件乱码用 Qt Designer 打开另存一次一般能修。5.4 现象四.ui文件编译后生成的类没办法直接布局现象把Ui_MyForm通过setupUi放到主窗口后所有控件挤在窗口左上角拉伸窗口也不会铺开。原因Qt Designer 里的窗体如果没有给 center widget 设置布局setupUi就只生成控件而不生成 layout。源码里的部分.ui是早期保存的可能没保存布局或者布局类型是 AbsoluteLayout绝对定位。绝对定位在窗口 resize 后不会自动伸缩所以看起来像“没有布局”。解决在 Qt Designer 中打开该 .ui 文件选中中央窗体在工具栏点击“水平布局”或“栅格布局”保存后重新编译。不想打开 Designer 的话也可以手动改 XML在widget元素下补一条layout但手写容易出错我一般还是用 Designer。编译后重新运行按钮就会跟随窗口伸展。这个问题的隐蔽之处在于不报错界面也能打开视觉上只是丑很多新手以为是窗口样式问题去调样式表。排查时先看setupUi生成的代码末尾有没有retranslateUi和布局设置如果没有布局对象就一定是 .ui 的布局层缺失。5.5 现象五SIGNAL/SLOT宏连接不生效现象按钮点击后槽函数没被调用控制台没有任何报错界面也不反应。原因老式写法self.connect(self.button, SIGNAL(clicked()), self.on_click)依赖字符串匹配。Qt 把信号名当成字符串处理槽函数参数个数、类型的差异会导致匹配失败且失败是静默的。比如SIGNAL(clicked())连接一个带参数的槽或者槽写成int而信号不带参数都会失效。解决全部改成新式信号槽语法self.button.clicked.connect(self.on_click)如果槽函数的参数需要精确匹配使用pyqtSlot()显式声明pyqtSlot(bool) def on_checked(self, checked: bool): ...改完后如果在运行时仍然不触发就去确认信号名称有没有拼错比如clicked和click是两回事。还有一个冷门原因如果窗口类没有继承QObject或QWidget新式连接会抛出 TypeError但源码里所有窗口都继承 QMainWindow这个问题在迁移到自己写的类时要额外注意。6. 二次开发思路把示例改造成自己的生产力工具如果只让我保留一个改造示范我会选“给文本编辑器加实时字数统计”。源码里的文本编辑器示例很好地演示了菜单、状态栏、快捷键但没有实时统计。改造的核心不是加文本框而是选对信号。from PyQt5.QtWidgets import QApplication, QMainWindow, QPlainTextEdit, QStatusBar class WordCountEditor(QMainWindow): def __init__(self): super().__init__() self.editor QPlainTextEdit(self) self.setCentralWidget(self.editor) self.status QStatusBar(self) self.setStatusBar(self.status) self.editor.textChanged.connect(self.update_count) self.update_count() def update_count(self): text self.editor.toPlainText() chars len(text) words len(text.split()) self.status.showMessage(fchars: {chars} words: {words}) if __name__ __main__: app QApplication([]) window WordCountEditor() window.show() app.exec_()逻辑说明QPlainTextEdit比QTextEdit更轻量适合纯文本textChanged信号会在每次编辑时发出槽函数里读取全文并统计然后写入QStatusBar。QMainWindow的setStatusBar会创建底部状态栏不需要布局。如果改成QTextEdittoPlainText()同样适用。参数说明len(text.split())对中文分词不准确中文应改用len([c for c in text if not c.isspace()])统计非空白字符数这是对于中文文本更实际的“字数”。这样一套代码就能直接挂在菜单栏“统计”动作上。从那以后我每次拿到类似的 sample code都会先跑一遍再读代码而不是先读代码再跑。遇到 API 差异直接全局替换然后观察信号槽有没有接上窗口显示但按钮无动静首要怀疑信号连接而不是业务逻辑。这个习惯帮我省掉了大量的排错时间。希望帮到你。本文还有配套的精品资源点击获取
