python-development

Python 开发技能

Developer Hub、Python Specialist 和 wxPython Specialist Agent 的参考数据。

Python 版本快速参考

版本	主要特性	EOL
3.10	match/case、X | Y 联合类型、ParamSpec	2026 年 10 月
3.11	异常组、Self 类型、tomllib、更快的 CPython	2027 年 10 月
3.12	类型参数语法 def f[T]()、@override、f-string 嵌套	2028 年 10 月
3.13	实验性自由线程模式、改进的错误消息	2029 年 10 月
3.14	async pdb.set_trace_async()、模板字符串（PEP 750）	2030 年 10 月

pyproject.toml 骨架

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-app"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = []

[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11"]

[project.scripts]
myapp = "my_app.__main__:main"

[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-ra --strict-markers"

[tool.ruff]
target-version = "py310"
line-length = 100

[tool.ruff.lint]
select = ["E", "F", "W", "I", "N", "UP", "B", "SIM", "TCH"]

[tool.mypy]
python_version = "3.10"
strict = true

PyInstaller 快速参考

单文件模式

exe = EXE(pyz, a.scripts, a.binaries, a.zipfiles, a.datas,
          name='MyApp', console=False, icon='icon.ico')

单文件夹模式

exe = EXE(pyz, a.scripts, exclude_binaries=True,
          name='MyApp', console=False, icon='icon.ico')
coll = COLLECT(exe, a.binaries, a.zipfiles, a.datas, name='MyApp')

常见隐藏导入

• pkg_resources.extern
• accessible_output2（用于无障碍桌面应用）
• keyring.backends（用于凭据存储）
• platformdirs
• httpx._transports / httpcore._backends
• encodings（始终需要）

wxPython 快速参考

Sizer 速查表

Sizer	使用场景
wx.BoxSizer(wx.VERTICAL)	从上到下排列项目
wx.BoxSizer(wx.HORIZONTAL)	从左到右排列项目
wx.GridBagSizer(vgap, hgap)	带标签和控件的表单布局
wx.FlexGridSizer(rows, cols, vgap, hgap)	均匀网格布局
wx.WrapSizer	可换行的流式布局
wx.StaticBoxSizer(wx.VERTICAL, parent, "Label")	为控件分组并添加边框

线程安全的 GUI 更新

# From worker thread:
wx.CallAfter(self.update_status, "Done")
wx.PostEvent(self, CustomEvent(data=result))

# NEVER do this from a worker thread:
self.status_bar.SetStatusText("Done")  # CRASH or CORRUPTION

标准 ID

ID	用途
wx.ID_OK	确定按钮
wx.ID_CANCEL	取消按钮
wx.ID_SAVE	保存操作
wx.ID_OPEN	打开操作
wx.ID_EXIT	退出
wx.ID_HELP	帮助操作
wx.ID_NEW	新建文档
wx.ID_UNDO / wx.ID_REDO	撤销 / 重做

事件类型

事件	触发条件
wx.EVT_BUTTON	按钮单击
wx.EVT_MENU	选择菜单项
wx.EVT_CLOSE	请求关闭窗口
wx.EVT_SIZE	窗口大小发生变化
wx.EVT_TIMER	计时器触发
wx.EVT_TEXT	文本控件内容发生变化
wx.EVT_LIST_ITEM_SELECTED	选择列表项
wx.EVT_TREE_SEL_CHANGED	树形控件的选择发生变化
wx.EVT_UPDATE_UI	检查 UI 状态更新

常见问题

Python

• 可变默认参数： def f(items=[]) 会在多次调用之间共享该列表。使用 None，并在函数内部创建列表。
• 闭包延迟绑定： 循环中的 lambda: x 捕获的是变量，而非其值。使用 lambda x=x: x。
• 循环导入： 将导入移至函数内，使用 TYPE_CHECKING 代码块，或重构模块。
• 在 dataclass 外使用 field()： field() 仅适用于 @dataclass 类内部。其他位置请使用普通类型注解。
• is 与 ==： is 检查对象标识，== 检查相等性。仅对 None、True、False 使用 is。
• 循环中拼接字符串： 改用 "".join() 或 io.StringIO。

wxPython

• 在工作线程中操作 GUI： 始终使用 wx.CallAfter() 或 wx.PostEvent()。
• 缺少 event.Skip()： 其他处理器将不会触发。除非有意处理并拦截事件，否则请调用 event.Skip()。
• 未停止计时器： 在 EVT_CLOSE 处理器中停止计时器，以避免对象销毁后仍触发回调。
• 未取消初始化 AUI： 在关闭处理器中调用 _mgr.UnInit()。
• 未销毁对话框： 使用上下文管理器（with MyDialog(...) as dlg:）自动清理。
• Sizer 项目的父对象错误： Sizer 中的所有控件必须拥有相同的父面板。
• 绝对定位： 布局时切勿使用 SetPosition() 或 SetSize()。始终使用 sizer。

跨平台路径

from platformdirs import user_config_dir, user_data_dir, user_cache_dir

config = user_config_dir("MyApp", "MyCompany")  # %APPDATA% / ~/Library/... / ~/.config/
data = user_data_dir("MyApp", "MyCompany")
cache = user_cache_dir("MyApp", "MyCompany")

测试快速参考

# Run all tests
pytest

# Run specific test file
pytest tests/test_queue.py

# Run specific test
pytest tests/test_queue.py::test_submit_job -v

# With coverage
pytest --cov=mypackage --cov-report=term-missing

# Stop on first failure
pytest -x

# Show locals on failure
pytest -l

日志设置模板

import logging

def setup_logging(level: int = logging.INFO) -> None:
    logging.basicConfig(
        level=level,
        format="%(asctime)s %(name)s %(levelname)s %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
    )
    # Quiet noisy libraries
    logging.getLogger("httpx").setLevel(logging.WARNING)
    logging.getLogger("httpcore").setLevel(logging.WARNING)

桌面无障碍快速参考

平台 API 概述

平台	API	Python 绑定	用途
Windows	UI Automation (UIA)	comtypes、pywinauto	现代应用、NVDA/Narrator
Windows	MSAA / IAccessible2	comtypes、pywinauto	旧版应用、JAWS
macOS	NSAccessibility	pyobjc	VoiceOver

wxPython 无障碍基础知识

# Name every control that lacks a visible label
# CORRECT: use StaticText immediately before the control in the sizer
label = wx.StaticText(panel, label="Scan progress:")
# ctrl = wx.Gauge(panel)  -- add label to sizer right before ctrl
# WRONG: SetName() is ignored by screen readers
# ctrl.SetName("Scan progress")  -- only affects FindWindowByName()

# Tab order follows sizer insertion order; override with:
ctrl2.MoveAfterInTabOrder(ctrl1)

# Keyboard shortcuts via accelerator table
accel = wx.AcceleratorTable([
    (wx.ACCEL_CTRL, ord('S'), wx.ID_SAVE),
    (wx.ACCEL_CTRL, ord('Q'), wx.ID_EXIT),
])
frame.SetAcceleratorTable(accel)

# Platform-correct button order in dialogs
sizer.Add(dialog.CreateStdDialogButtonSizer(wx.OK | wx.CANCEL))

屏幕阅读器交互模型

屏幕阅读器会将控件呈现为：名称 + 角色 + 值 + 状态

属性	wxPython 来源	示例
名称	前置的 wx.StaticText、label= 参数或 SetToolTip()	“扫描进度”
角色	控件类型（自动确定）	按钮、文本字段、列表
值	控件内容	“75%”、“Hello world”
状态	控件标志	已聚焦、已禁用、已选中

桌面无障碍检查清单

1. 每个控件都有有意义的名称（输入控件使用前置的 wx.StaticText，按钮使用 label=，仅含图像的控件使用 SetToolTip()）
2. 支持仅使用键盘操作——每项操作都可通过 Tab/Enter/Space/方向键访问
3. 焦点清晰可见——切勿隐藏焦点指示器
4. Tab 顺序符合逻辑（通常从上到下、从左到右）
5. 颜色不是传达信息的唯一方式
6. 支持高对比度模式（使用系统颜色，而非硬编码颜色）
7. 对话框使用 CreateStdDialogButtonSizer()，确保按钮顺序符合平台惯例
8. AUI 窗格可通过键盘导航

结构化审计规则集

激活审计模式后，Agent 会使用以下结构化检测规则集：

规则前缀	Agent	范围	数量
WX-A11Y-001..012	wxpython-specialist	wxPython 特定模式（StaticText 标签、AcceleratorTable、仅限鼠标的事件、对话框）	12 条规则
DTK-A11Y-001..012	desktop-a11y-specialist	平台级 API 模式（名称/角色/状态/值、焦点、UIA/NSAccessibility）	12 条规则
TST-A11Y-001..010	desktop-a11y-testing-coach	测试覆盖缺口（自动化测试、屏幕阅读器测试、键盘测试计划、CI 集成）	10 条规则

规则集之间没有重叠——WX 涵盖 wxPython 控件模式，DTK 涵盖平台 API，TST 涵盖测试流程缺口。

Agent 路由

如需更深入的专业知识，该技能会将任务路由给以下专家：

• desktop-a11y-specialist —— 平台 API 实现、wx.Accessible、自定义控件模式（DTK-A11Y-* 审计规则）
• desktop-a11y-testing-coach —— NVDA/JAWS/Narrator 测试、Accessibility Insights、自动化 UIA 测试（TST-A11Y-* 审计规则）
• a11y-tool-builder —— 规则引擎架构、文档解析器、严重性评分、报告生成器