Python工程兼容性需明确支持范围、控制变更影响、提供平滑过渡；在pyproject.toml中声明python_requires，用==锁定发布依赖，通过optional-dependencies分组场景依赖，并文档化强耦合库的测试版本区间。
Python工程代码演进过程中，兼容性不是“能跑就行”，而是要明确支持范围、控制变更影响、提供平滑过渡路径。核心是让升级对用户（下游模块、业务方、CLI使用者）尽可能无感。
明确Python版本支持边界
在pyproject.toml或setup.py中显式声明python_requires，例如>=3.8,。不写等于默认兼容所有版本，极易因隐式依赖（如typing模块变动、asyncio行为调整）导致运行时异常。新项目建议从3.9+起步，避免为旧版本做过多适配；存量项目升级前，先用pyenv验证各目标版本下的单元测试通过率。
API演进遵循语义化版本（SemVer）约束
函数/类/模块的删除、签名变更、行为修改必须对应主版本号升级（如v1.x → v2.0），并同步提供：
• DeprecationWarning（非UserWarning）提示旧用法，且在警告消息中给出替代方案和预计移除版本
• 保留旧接口至少一个大版本周期（如v1.5中标记废弃，v2.0中移除）
• 在CHANGES.md中按版本分组记录所有不兼容变更，标注影响范围（如“影响所有调用utils.parse_config()的代码”）
类型与语法兼容需主动隔离
使用高版本Python特性（如match-case、TypeVarTuple）时，避免直接引入导致低版本解释器启动失败。推荐方式：
• 用sys.version_info做运行时分支（仅适用于极少数关键路径）
• 更稳妥的是通过typing.TYPE_CHECKING配合if False:块做类型提示隔离
• 语法级不兼容（如f-string嵌套表达式增强）应推迟到最低支持版本满足后再启用，并在CI中用多版本tox验证
第三方依赖版本需锁定+兼容声明
requirements.txt或pyproject.toml[project.dependencies]中避免宽泛版本（如requests>=2.0）。应：
• 使用==锁定已验证兼容的版本（发布包）
• 在pyproject.toml中补充[project.optional-dependencies]定义不同场景的依赖组合（如dev、test、legacy）
• 对强耦合库（如numpy、pandas）在文档中标明经测试的版本区间，并在CI中覆盖区间两端版本
