Python expert 是一份面向 Python 源码工作的编写规范约定。根据资料,它的加载时机是:当你读取、编辑或编写 Python 源文件时加载,用来统一代码风格与质量。
用途 主要用于约束在特定工作区中编写 Python 时的行为,使产出符合“干净、地道(idiomatic)的 Python”这一目标,减少不一致的风格与隐蔽的错误处理方式。
主要能力(约定条目)
- 全面类型标注:为参数、返回值、属性,以及类型不明显的局部变量添加类型提示。
- 数据容器:对简单的数据结构优先使用 dataclasses,而不是手写 init。
- 异常抛出:抛出具体异常(ValueError、KeyError、LookupError 等),并附带有信息量的消息;避免使用裸 Exception。
- 不吞错误:不要写 except Exception: pass,也不要吞掉错误,让意外错误继续向上传播。
- 匹配周围风格:如果文件使用单引号与 4 空格缩进,就保持一致;不要重新格式化无关的行。
- 注释解释原因:注释说明“为什么”而非“做了什么”,跳过类似 # loop over items 的叙述性注释,只对不明显意图进行注释。
- 小而聚焦的修改:修 bug 时只做必要改动,其余文件内容保持不变,使 diff 更易读。
使用方式 资料仅说明在读取、编辑或编写 Python 源文件时加载该技能,未提供安装命令、配置方法或调用示例,相关细节暂未提供。
适用场景 适用于任何需要阅读或修改 Python 代码的工作区,尤其是希望统一类型标注、异常处理与注释风格,并要求改动范围可控、diff 可读的协作或评审场景。
限制 该条目是一组编码约定,而非可执行工具或库;资料未说明其支持的具体 Python 版本、与哪些工具链集成、是否强制检查或可否自定义规则,这些内容暂未提供。