用途:为 Python 类型标注风格设定硬性规则,适用于智能体生成、重构或审查的所有 Python 代码,除非用户对特定文件明确覆盖该风格。详细示例与设计理由见随附参考文件 references/python-module-design-without-type-checking.md。
主要规则:不得导入 TYPE_CHECKING,不得写 from typing import TYPE_CHECKING,不得依赖 typing.TYPE_CHECKING 或其别名,不得引入 TYPE_CHECKING = False 等影子变量;不得用 if TYPE_CHECKING: 包裹导入,即使其他风格指南推荐;不得仅为打破循环导入或加速导入而把导入移入该守卫。导入应放在模块顶层,仅在不可避免的运行时问题(如可选的重型依赖)时才移入函数或方法内部,且不得为类型标注便利而这样做。生成代码在解释器与静态类型检查器下行为应一致,避免仅为对类型检查器隐藏导入的模式。
避免循环导入的替代模式:一、把共享类型(dataclass、Protocol、TypedDict、枚举等)抽取到独立模块(如 models.py、types.py、domain.py),使依赖图无环;二、依赖 Protocol 或抽象基类而非具体类,在 interfaces.py / ports.py 中定义接口,通过依赖倒置打破循环;三、使用前向引用,如字符串注解 "MyClass" 或 from future import annotations,而非为注解把符号导入守卫块;四、函数内局部导入仅用于真实运行时问题,绝不只为类型提示,并需说明原因。
已有 TYPE_CHECKING 代码的处理:最小改动时保留现有守卫,不新增受守卫导入,不把该模式扩散到新模块;重构清理时先弄清每个守卫存在的原因,再用上述模式逐步移除,每次移除后重新运行类型检查与测试。
限制:资料未提供安装命令、平台支持、收费方式或具体代码示例,相关细节暂未提供。