用途
这是一套 Python 编码规范与最佳实践集合，定位是供 AI 智能体与 LLM 使用，帮助其生成高质量、性能良好且易于维护的 Python 代码。规范以规则清单和代码示例的形式呈现，便于在生成或审查 Python 代码时逐条对照。
主要能力（按类别）
错误处理（CRITICAL 级别）
目标是防止失败被隐藏或被当作成功结果上报。包含规则 error-no-silent-exceptions：绝不吞掉异常。示例中用 raise ... from exc 保留异常链，在进程边界显式返回非成功状态码（如返回 1），并通过 raise SystemExit(main()) 表达退出码。
性能优化（CRITICAL 级别）
套用 Python 优化模式以提升处理速度与内存效率。规则包括：
- perf-list-comprehension：优先用列表推导式而非循环（资料称快 1.5–2 倍）；
- perf-generator-expression：大数据集用生成器表达式（O(1) 内存）；
- perf-dict-get：使用 dict.get() 处理默认值；
- perf-set-lookup：用 set 做快速查找（O(1) 对比 O(n)）；
- perf-str-join：字符串拼接用 join（O(n) 对比 O(n²)）。
异步处理（HIGH 级别）
使用 asyncio 的高效异步编程模式，规则包括 async-gather（独立任务用 asyncio.gather）、async-create-task（正确创建后台任务）、async-context-manager（用 async with 管理资源）、async-semaphore（用信号量限制并发）。示例展示并发执行、异步会话资源管理以及 asyncio.Semaphore(10) 限流。
设计原则（HIGH 级别）
面向可维护性与可扩展性的软件设计原则，包括：design-philosophy（DRY、YAGNI、KISS）、design-single-responsibility（单一职责原则）、design-dependency-injection（依赖注入实现松耦合）、design-no-global-singleton（避免全局单例与模块级共享实例）、solid-ocp（开闭原则）、solid-lsp（里氏替换原则）、solid-isp（接口隔离原则）、design-pure-functions（优先无副作用的纯函数）、design-early-return（用提前返回减少嵌套）。示例展示通过构造函数注入依赖、在组合根一次性构建对象图、以新增类型而非修改既有代码来扩展，以及用小型 Protocol 满足接口隔离。
文档（HIGH 级别）
面向公共 API 清晰性与可机器校验契约的文档规范，规则为 doc-docstring（公共 API 使用 Google 风格 docstring）和 doc-type-hints（公共 API 必须有类型标注）。示例给出带 Args、Returns 段的 docstring 写法。
数据验证（HIGH 级别）
针对跨越信任边界的数据的验证模式，规则 validation-pydantic 建议使用 Pydantic 进行边界数据验证，示例展示 BaseModel 配合 EmailStr 与 Field(ge=0, le=150) 的范围约束。
面向对象编程（MEDIUM 级别）
Pythonic 的 OOP 最佳实践：oop-composition-over-inheritance（优先组合而非继承）、oop-dataclass（数据容器用 dataclass）、oop-protocol（优先 Protocol 而非抽象基类）、oop-property（用 property 替代 getter）。
使用方式
规范以分类规则表加代码片段的形式提供，可直接作为代码生成或代码评审时的对照清单。资料在最后列出“推荐工具”（ruff、mypy、pytest、pyscn、uv），用于自动执行这些规范，但未提供具体配置方式、命令或安装步骤。
适用场景
适合需要让 AI 智能体或 LLM 按统一 Python 规范产出代码的场景，也适合作为个人或团队审阅 Python 代码时的高层检查清单，覆盖异常处理、性能、异步、设计、文档、校验与 OOP 等多个方面。
限制
资料未说明该规范的许可证、版本、维护状态与更新频率；未提供各规则的完整反例、禁用写法细节与阈值依据来源；推荐工具部分仅有名称，缺少安装命令与配置示例；未说明是否包含示例项目或测试用例。以上未提供的内容本文不做补充。