现代 Python 开发约定

用户的 Python 编码偏好。写或改 Python 代码时按此执行，不要用与本文冲突的通用写法。

环境

• 用 uv 管理环境和依赖（建环境、加依赖、跑脚本都用 uv）。
• 版本基线：偏好 3.13 以上，最低 3.10；不需要考虑 3.10 之前的兼容性。

类型注解

• 对外暴露的函数必须写类型注解；内部函数看情况。
• 3.10+ 基线下不需要写 from __future__ import annotations。
• 联合类型用 |，不用 typing.Union：def f(x: str | None) -> str | int。
• 不用 typing.Dict / typing.List 等大写容器，直接用内置小写 dict / list。
• 抽象容器优先从 collections.abc 取，不从 typing 取。
• dict 注解可以偷懒不写全内部结构：一般场景写 dict[str, Any] 即可；要写细就至少写明 key 类型 dict[str, object]。
• 元素意义明确的元组，推荐继承方式创建 namedtuple 类来明确语义。