SuperAPI AI 工具集

python-conventions-taudelta

编程与开发

查看项目

更新于 10-16 08:08

技能介绍

用途:在编写、评审或重构 Python 代码时,为若干常见设计选择提供统一的默认答案,避免不同会话或模型无理由地选到不同做法。仅适用于个人、由智能体维护的 Python 项目;若明确要求“评估替代方案”,则不适用。测试套件约定与 MCP 服务器相关规则已拆分为独立安装项。

主要能力: 一、数据建模。解析外部不可信数据(API 响应、MCP 工具参数)或配置时默认用 Pydantic v2 且 frozen=True;其余内部结构化数据、函数返回值、记录用 @dataclass(frozen=True)。需要验证器/转换器但不要 Pydantic 的验证加序列化捆绑时升级到 attrs;需位置元组兼容或字段不超过约 3 个的封闭记录用 NamedTuple;Pydantic 开销经测量成为瓶颈用 msgspec;值必须保持普通 dict 用 TypedDict。作者提醒:带比较前置条件的值类型用 NamedTuple 会继承元组排序,可能静默跨单位比较成功。另有一条项目级替代方案:项目某处用 Pydantic 就全部用 Pydantic。 二、Pydantic 陷阱(针对 2.13.5 实测)。model_copy(update=...) 不做验证,应改用可重新验证的辅助函数;宽松模式会把 float 强制转成 Decimal,需要 Annotated[Decimal, Strict()];配置应写在类声明处(class Q(BaseModel, frozen=True));验证器抛出的 ValueError 会被吞掉并改抛 pydantic.ValidationError,当项目异常层级以 ValueError 为根时会丢失具体类型。 三、日期时间与时区。只使用带时区的 datetime,并在每个边界规范化为 UTC;进入时拒绝 naive datetime,绝不强制转换;仅在展示时转本地时间;用 zoneinfo 而非 pytz。文中给出 Pydantic 下的规范写法 Utc = Annotated[datetime, AwareDatetime, AfterValidator(lambda v: v.astimezone(UTC))];无 Pydantic 时用 post_init 显式完成拒绝与转换两步。处理本地墙上时间需借助 PEP 495 的 fold,并通过比较偏移量而非 datetime 判断不存在或歧义的时间。不要用 datetime.utcnow()(3.12 起弃用),改用 datetime.now(UTC)。测试应使用真实时区转换点的已知答案测试。 四、配置与密钥管理。默认 pydantic-settings:基类带生产安全默认值,每个非生产环境一个子类只覆盖差异项,由 ENVIRONMENT 环境变量驱动选择器并在包 init.py 顶部装配,赋给模块级名称,全程 frozen=True。仅在仓库真的出现多环境部署矩阵时升级到 dynaconf。不要在非 FastAPI 应用中使用其 @lru_cache 包装的配置工厂。 五、提前返回与失败快。守卫子句用于“一条主路径加一条罕见提前退出”的非对称场景,不要用来拆分两个对等业务分支;assert 仅用于内部“不可能发生”的自检,绝不用于输入验证;失败时绝不返回 None、哨兵或 (success, result);每个包至少一个根异常,仅当调用方确实需要区分时才加深叶子节点。 六、模块化、可测试性、DRY、可读性与封装。倾向用重复换取避免过早抽象(Fowler 的 Rule of Three):第一次重复随意,第二次皱眉,第三次重构。

使用方式:作为写作代码时的参考依据,而非工具配置;本文不指定安装哪个类型检查器或 linter。部分主题附带代码片段文件路径(如 references/snippets/data-modeling.py、settings.py、guard-clauses.py、exceptions.py)。

限制:属于个人风格约定,偏离在确有理由时是允许的;不涉及工具链安装与配置;各条目的具体实现细节需查阅对应片段文件,资料未提供完整片段内容。