Boto3 从 Python 2 迁移到 Python 3：官方升级指南与源码级解读

后端云原生【免费下载链接】boto3AWS SDK for Python (Boto3)项目地址https://gitcode.com/gh_mirrors/bo/boto3点击查看免费下载本指南以 AWS SDK for PythonBoto3官方迁移文档docs/source/guide/migrationpy3.rst为主体完整讲解 Boto3 与 Botocore 停止支持 Python 2.7 的时间线、迁移到 Python 3 的标准操作步骤以及无法立即迁移时的版本锁定策略同时结合本仓库的 setup.py、boto3/compat.py、CHANGELOG.rst 等源码与变更记录从实现层面印证官方文档的每一个结论。读完本文你将掌握一套可直接执行的 Python 3 迁移流程并理解 SDK 在运行时如何对你发出弃用警告、在安装期如何通过元数据强制 Python 版本下限。为什么必须迁移Python 2.7 的官方弃用背景Python Software FoundationPSF经过多年的淘汰过渡后于2020 年 1 月 1 日正式弃用 Python 2.7。PSF 弃用意味着该版本不再获得官方维护包括安全修复在内的一切更新都会停止。AWS 随后跟进宣布弃用对 Python 2.7 的支持。这一点直接影响组成 AWS SDK for Python 的两个模块Botocore底层的低层low-level模块负责 HTTP 协议、签名、重试、凭证等基础能力Boto3在 Botocore 之上实现 API 功能与更高层特性如资源抽象、集合、分页器的模块。从源码结构看这一分层非常清晰本仓库 boto3/compat.py 中from s3transfer.manager import TransferConfig、SOCKET_ERROR ConnectionError等定义直接引用了 Botocore 生态s3transfer、collections.abc的 Python 3 化实现而 boto3/session.py、boto3/init.py 则是在此之上组装出的高层面 API。两个模块是一体化交付的因此迁移时必须一起升级。官方给出的关键结论是在弃用日期之后发布的 Boto3 版本将不再能在 Python 2.7 上运行。官方迁移时间线时间事件2020-01-01PSF 正式弃用 Python 2.72021-07-15Boto3 与 Botocore 结束对 Python 2.7 的支持结合仓库证据这条时间线在 CHANGELOG.rst 中有明确记录1.18.0版本的变更条目写有feature:Python: Drop support for Python 2.7与feature:Python: [botocore] Dropped support for Python 2.7。这意味着1.17.x 是最后一个兼容 Python 2.7 的 Boto3 发布系列而 1.18.0 起正式移除 Python 2.7 支持。因此官方文档给出的总原则是所有使用 Boto3 的项目都应尽快过渡到受支持的 Python 3 版本。迁移第一步安装或更新 Python 3在动手升级 SDK 之前需要先确保环境中已安装受支持的 Python 版本。按照官方快速上手文档docs/source/guide/quickstart.rst中「Install or update Python」一节的指引Boto3 要求 Python 3.10 或更高版本。获取 Python 3 的途径有两种从 Python 官方渠道下载安装使用本机系统自带的包管理器安装如apt、yum、brew、choco等。这一版本要求的硬性约束在本仓库 setup.py 中有直接的代码级印证python_requires 3.10, classifiers[ Programming Language :: Python :: 3 :: Only, Programming Language :: Python :: 3.10, Programming Language :: Python :: 3.11, Programming Language :: Python :: 3.12, Programming Language :: Python :: 3.13, Programming Language :: Python :: 3.14, ],python_requires 3.10是 setuptools 的安装期元数据声明当你在旧版 Python 环境执行pip install boto3时pip 会直接拒绝安装并给出版本不匹配错误从源头上杜绝「装上了却跑不起来」的问题。Programming Language :: Python :: 3 :: Only分类器则明确宣告该项目是纯 Python 3 项目。此外tox.ini 中的测试矩阵py310,py311,py312,py313,py314也说明当前 Boto3 的持续集成测试覆盖的是 Python 3.10 至 3.14 这几个版本。迁移第二步升级 AWS SDK for Python安装好 Python 3 之后即可升级 SDK。你可以选择全局升级也可以在项目的虚拟环境中升级若项目使用了虚拟环境推荐在虚拟环境中操作以避免污染系统级 Python 环境并防止与其他工具产生依赖冲突。官方给出的标准操作分三步1. 卸载当前已安装的 Boto3 与 Botocore$ python -m pip uninstall boto3 botocore这一步确保环境中不存在旧版本残留避免新旧版本文件混装导致的诡异行为。2. 安装新版本的 Boto3$ python3 -m pip install boto3安装 Boto3 会自动带上它所依赖的 Botocore无需手动分别安装。从本仓库 setup.py 的依赖声明可以看到这一依赖关系的具体形态requires [ botocore1.43.94,1.44.0, jmespath0.7.1,2.0.0, s3transfer0.19.0,0.20.0, ]即 Boto3 同时依赖 Botocore核心协议与签名、JMESPath查询表达式求值与 S3transferS3 传输管理三者会随pip install boto3一并解析安装。3.可选验证 SDK 使用的是正确的 Python 版本$ python3 -c import boto3, sys; print(f{sys.version} \nboto3: {boto3.__version__}) 3.x.y (default, Jan 7 2021, 17:11:21) [GCC 7.3.1 20180712 (Red Hat 7.3.1-11)] boto3: 1.16.15输出中的sys.version应显示 Python 3.x 的完整版本与编译信息boto3.__version__应显示已安装的 SDK 版本号上述示例输出是官方文档撰写时的旧版本 1.16.15当前仓库 boto3/init.py 中的版本为1.43.94。如果sys.version仍显示 2.7 之类说明当前 shell 的python3指向错误需要检查 PATH 与虚拟环境激活状态。迁移第三步可选处理 Python 3 语法与行为差异升级到 Python 3 后你的应用代码可能需要适配 Python 3 的语法与运行时差异典型包括print语句改为print()函数整数除法行为变化Python 3 中/为浮点除法//才是整除unicode/str/bytes的类型体系重构字典迭代方法iteritems()等改为items()异常链raise ... from ...、as语法等。这类差异可以通过2to3工具或futurize、modernize等辅助脚本半自动化转换再结合测试逐步修正。官方文档对此未展开属于 Python 3 迁移的通用范畴但作为从 Python 2 项目迁移的开发者这一步通常无法跳过。如果无法立即升级到 Python 3版本锁定策略现实中的大型项目可能因为以下原因暂时无法升级大量代码依赖 Python 2 独有语法或特性改造工作量巨大某些第三方依赖尚未提供 Python 3 兼容版本需要先完成业务代码的其他更新只能推迟 Python 迁移。在这种场景下官方给出的策略是将项目的 Boto3 安装锁定到最后一个支持你所用 Python 版本的发布之后不再继续更新 Boto3。需要明确的是这只是「临时维持可用」的手段已弃用的 Boto3 版本不会再获得任何新特性更新或安全修复继续使用需要自行承担风险并应尽快排期完成真正的迁移。针对不同安装方式官方给出了具体的锁定操作使用 pip 10.0 或更高版本安装如果你的 Boto3 是用pip 10.0 及以上版本安装的那么当最后一个兼容 Python 2 的 SDK 版本即 1.17.x 系列安装完成后pip 会自动停止推送后续更新。这是因为后续版本1.18.0 起通过python_requires等元数据声明不再兼容 Python 2.7pip 解析依赖时会自动跳过它们你无需额外操作。使用旧版 pip 安装如果你使用的是pip 10.0 之前的旧版本pip 无法识别 Python 版本约束元数据因此需要手动把 Boto3 固定到不晚于 1.17 的版本例如$ pip install boto31.17.112这样 pip 在后续执行安装/升级时就会停留在锁定版本不会误升级到不兼容的 1.18.0。其他安装方式源码或手动安装如果你是通过源码或任何其他方式安装 Boto3 和 Botocore请务必下载并安装在 Python 2.7 弃用日期之前发布的版本即 1.17.x 系列不要使用 1.18.0 及之后的版本。从源码看 SDK 的 Python 版本守卫机制除了安装期的python_requires元数据Boto3 在运行时也内置了针对 Python 版本弃用的告警机制这一点在官方迁移文档中没有展开但对理解 SDK 的版本策略很有帮助。在 boto3/init.py 中client()、resource()等入口都会经由_get_default_session()def _get_default_session(): if DEFAULT_SESSION is None: setup_default_session() _warn_deprecated_python() return DEFAULT_SESSION每次创建默认会话时都会调用_warn_deprecated_python()。该函数定义在 boto3/compat.pydef _warn_deprecated_python(): Use this template for future deprecation campaigns as needed. py_39_params { date: April 29, 2026, blog_link: ( https://aws.amazon.com/blogs/developer/ python-support-policy-updates-for-aws-sdks-and-tools/ ) } deprecated_versions { (3, 9): py_39_params, } py_version sys.version_info[:2] if py_version in deprecated_versions: ... warnings.warn(warning, PythonDeprecationWarning)可以看出这套弃用告警机制被设计成可扩展的模板官方通过往deprecated_versions字典中加入(主版本, 次版本)元组来登记新的弃用目标。当前仓库登记的告警是Python 3.9提示其支持将于2026 年 4 月 29 日结束并建议升级到 Python 3.10 或更高版本——这与 README.rst 中「On 2026-04-29, support for Python 3.9 ended for Boto3」的说明以及 setup.py 的python_requires 3.10完全一致。对应的告警类型PythonDeprecationWarning定义在 boto3/exceptions.py。如果你不希望看到这类弃用警告可以在代码中调用 boto3/compat.py 提供的filter_python_deprecation_warnings()主动屏蔽但官方注释明确指出屏蔽告警只是「承认你的运行时即将被弃用」届时你将停止收到针对该 Python 版本的所有客户端更新。迁移完成后的自检清单完成上述迁移后建议按以下清单逐项确认python3 --version输出为受支持的 Python 3.10当前 Boto3 的要求见 setup.pypython3 -m pip show boto3显示的版本为最新稳定版且未残留旧版 Botocore运行python3 -c import boto3; print(boto3.__version__)能正常输出版本号无PythonDeprecationWarning告警项目代码已通过 Python 3 语法检查与单元测试S3、DynamoDB 等核心路径完成冒烟验证若暂时无法迁移确认 Boto3 已锁定在 ≤1.17 的最后一个 Python 2 兼容版本并明确记录了后续迁移的排期。总结Python 2.7 的官方生命周期已于 2020 年 1 月 1 日结束Boto3 与 Botocore 也于 2021 年 7 月 15 日正式停止对 Python 2.7 的支持对应版本 1.18.0见 CHANGELOG.rst。迁移路径很清晰先安装 Python 3.10再执行python -m pip uninstall boto3 botocore与python3 -m pip install boto3最后用一条命令验证解释器与 SDK 版本。若暂时无法迁移则需把 Boto3 锁定在 1.17.x旧版 pip 需手动指定boto31.17。当前仓库通过python_requires 3.10在安装期把关、通过_warn_deprecated_python()在运行期提醒双保险机制确保开发者不会在不知不觉中停留在已弃用的 Python 版本上。赞分享后端云原生【免费下载链接】boto3AWS SDK for Python (Boto3)项目地址https://gitcode.com/gh_mirrors/bo/boto3点击查看免费下载相关推荐Boto3 迁移指南从 Boto 2.x 平滑升级到 AWS SDK for PythonBoto3 迁移指南从 Boto 2.x 平滑升级到 AWS SDK for Python 本篇技术指南以官方 Migrating from Boto 2.x后端云原生从 Yii 1.1 迁移到 Yii 2官方升级指南与源码级差异全解析从 Yii 1.1 迁移到 Yii 2官方升级指南与源码级差异全解析 本指南以 docs/guide es/intro upgrade from v1.md后端Web框架Coil 3 迁移指南从 Coil 2 升级到 Coil 3 的全部破坏性变更与源码级解读Coil 3 迁移指南从 Coil 2 升级到 Coil 3 的全部破坏性变更与源码级解读 Coil 3 是 Coil 的下一代大版本其核心变化在于全面支移动开发图像处理缓存抽象上一篇使用GitCode上的Win11DisableRoundedCorners项目恢复Windows 11的经典直角设计下一篇Supabase CLI终极指南10个提升全栈开发效率的技巧创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考