Python 工程实践指南
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/alinaqi-maggy-python。
技能介绍
要解决什么问题
Python 项目一旦多人协作或进入 CI,常见问题不是「会不会写语法」,而是风格与结构不一致、运行时才发现类型错误、测试与钩子各玩各的,以及业务层到处 raise 导致边界难以推理。这份技能把 RealQ 侧沉淀的工程约定整理成可被 AI 助手执行的检查清单:从函数签名上的类型注解,到仓库里该有的目录与工具链,再到数据校验与错误表达模式。
技能如何约束你的代码
技能明确要求:所有函数签名带类型提示,复杂类型用 typing;在 CI 里跑 mypy --strict。测试侧以 Pytest 为主,并配合 GitHub Actions 与 Pre-Commit Hooks 把检查前移。在模式层面,推荐用 Pydantic 做数据校验、用依赖注入组织协作,核心逻辑采用 Result 模式(核心业务不显式抛异常)。同时列出应避免的 Python 反模式:如 from module import *、可变默认参数、bare except:、无说明的 type: ignore、用全局变量存状态、能用函数却硬上类等。
适用边界与注意点
文档中的 Project Structure、Tooling (Required)、Install and setup 等多为章节标题,具体目录树或工具版本需在你自己的仓库里落地,技能的作用是对齐决策方向而非替代 pyproject.toml / requirements 的填写。若团队已选定其他类型检查策略(例如仅 pyright、或 mypy 非 strict),需要在与技能对话时声明例外,以免助手过度纠偏。
使用场景
- 新服务要在 GitHub Actions 里加 mypy --strict,并让助手按技能审函数签名与 typing 用法
- 代码评审前要对照技能清单,扫一遍可变默认参数、裸 except 和 import *
- 要把接口入参校验迁到 Pydantic,同时让核心业务用 Result 而不是到处 raise
- 配置 pre-commit 时,让助手按技能补齐与 Pytest、类型检查一致的钩子项
适合人员
- 维护多个 Python 微仓库、要在 CI 里统一类型与测试门禁的 Tech Lead
- 负责拉齐新人 onboarding 文档、希望 AI 按同一套反模式清单做 code review 的资深工程师
- 从脚本仓库升级成可发布包、需要补齐 Pytest、Actions 与 pre-commit 的独立开发者
- 在数据管道服务里推行 Pydantic 校验与无异常核心层的后端工程师