后端云原生【免费下载链接】boto3AWS SDK for Python (Boto3)项目地址https://gitcode.com/gh_mirrors/bo/boto3点击查看免费下载本篇技术指南以 docs/source/guide/s3-example-download-file.rst 为核心系统讲解 AWS SDK for PythonBoto3从 S3 下载对象的两种托管方法download_file下载到本地文件与download_fileobj下载到文件类对象。读完本文你将掌握三种调用入口Client、Bucket、Object的完整用法、ExtraArgs与Callback参数的实战配置以及底层S3Transfer传输管理器在多部分下载、并发与重试方面的实现原理能够直接编写可复用的下载代码。下载与上传方法对称的设计Boto3 提供的下载文件方法与上传方法在设计上完全对称。download_file和download_fileobj分别对应上传侧的upload_file与upload_fileobj参数语义、可选参数、底层传输机制均保持一致。这种对称性意味着如果你已经熟悉上传流程下载流程几乎可以零成本迁移。从源码结构看这一对称性体现在注入机制上。boto3/s3/inject.py 中的三个注入函数inject_s3_transfer_methods、inject_bucket_methods、inject_object_methods分别把download_file/download_fileobj挂载到 S3 的Client、Bucket与Object类上与上传方法走的是同一条注入路径def inject_s3_transfer_methods(class_attributes, **kwargs): utils.inject_attribute(class_attributes, upload_file, upload_file) utils.inject_attribute(class_attributes, download_file, download_file) utils.inject_attribute(class_attributes, copy, copy) utils.inject_attribute(class_attributes, upload_fileobj, upload_fileobj) utils.inject_attribute( class_attributes, download_fileobj, download_fileobj )boto3/s3/inject.py 同时注入上传与下载方法保证了两类接口在每一层调用入口上都成对出现。方法一download_file 下载到本地文件download_file方法接收三个位置参数桶名Bucket、对象键Key与本地保存文件名Filename。这是最直接、最常用的下载方式适用于把 S3 对象落盘为本地文件的场景。import boto3 s3 boto3.client(s3) s3.download_file(amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME)其中OBJECT_NAME是 S3 对象的完整键名支持folder/object.txt形式的路径前缀FILE_NAME是本地目标路径。执行完毕后S3 对象内容会被完整写入FILE_NAME指定的文件中。从 boto3/s3/inject.py 的download_file实现可以看到这个方法内部创建了一个S3Transfer传输器并调用其download_file方法with_current_context(partial(register_feature_id, S3_TRANSFER)) def download_file( self, Bucket, Key, Filename, ExtraArgsNone, CallbackNone, ConfigNone ): with S3Transfer(self, Config) as transfer: return transfer.download_file( bucketBucket, keyKey, filenameFilename, extra_argsExtraArgs, callbackCallback, )该方法还接受三个可选参数ExtraArgs、Callback与Config具体用法见下文各小节。方法二download_fileobj 下载到文件类对象download_fileobj方法接受的第二个参数是可写的文件类对象writeable file-like object。与download_file不同它不关心目标路径而是把 S3 对象内容直接写入你提供的流对象非常适合与BytesIO、内存缓冲、网络流等配合使用。s3 boto3.client(s3) with open(FILE_NAME, wb) as f: s3.download_fileobj(amzn-s3-demo-bucket, OBJECT_NAME, f)关键约束文件对象必须以二进制模式wb打开而不是文本模式w。这是因为 S3 传输的是字节流文本模式会进行编码转换并破坏二进制数据。这一点在 boto3/s3/inject.py 的download_fileobj实现中得到印证——源码首先校验文件对象必须实现write方法否则抛出ValueErrordef download_fileobj( self, Bucket, Key, Fileobj, ExtraArgsNone, CallbackNone, ConfigNone ): if not hasattr(Fileobj, write): raise ValueError(Fileobj must implement write) ...除了本地文件download_fileobj也可以配合io.BytesIO()把对象读入内存import boto3 import io s3 boto3.client(s3) buf io.BytesIO() s3.download_fileobj(amzn-s3-demo-bucket, OBJECT_NAME, buf) buf.seek(0) data buf.read() # 对象的完整字节内容一个值得注意的实现细节在 boto3/s3/inject.py 中disable_threading_if_append_mode会检查传入的文件对象是否以追加模式a打开如果是会自动把use_threads置为False退化为单线程顺序写入避免多线程乱序追加破坏文件内容。判定逻辑定义在 boto3/compat.py 的is_append_mode中。因此download_fileobj并非只能写本地文件任何实现write方法的对象自定义流、网络响应体等都可使用。三种等价调用入口Client、Bucket、Object与上传方法一致下载方法由 S3 的Client、Bucket和Object三个类共同提供且三个入口的功能完全一致——它们最终都委托给同一个客户端底层实现。你可以根据当前代码的上下文选择最方便的一种这不会影响行为与性能。Client 入口低层 APIs3 boto3.client(s3) s3.download_file(amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME)Bucket 资源入口s3 boto3.resource(s3) s3.Bucket(amzn-s3-demo-bucket).download_file(OBJECT_NAME, FILE_NAME)Object 资源入口s3 boto3.resource(s3) s3.Object(amzn-s3-demo-bucket, OBJECT_NAME).download_file(FILE_NAME)从源码看Bucket与Object的入口本质上都是对客户端方法的薄封装。boto3/s3/inject.py 中bucket_download_file直接转发给self.meta.client.download_file并自动注入桶名boto3/s3/inject.py 中object_download_file则自动注入桶名与对象键。同理Bucket和Object也各自拥有download_fileobj变体boto3/s3/inject.py参数中无需重复传入Bucket/Key。单元测试 tests/unit/s3/test_inject.py 验证了这些代理转发逻辑资源层方法确实把调用转发到meta.client对应的下载方法。ExtraArgs为下载请求附加额外参数与上传方法一样下载方法支持可选的ExtraArgs参数用于向底层的 S3get_object请求附加额外选项。ExtraArgs是一个字典其合法的键集合被严格限定。合法取值由S3Transfer.ALLOWED_DOWNLOAD_ARGS定义。原文档明确指出该列表位于S3Transfer对象的ALLOWED_DOWNLOAD_ARGS属性中。在 boto3/s3/transfer.py 可以看到该属性直接取自s3transfer库的TransferManagerclass S3Transfer: ALLOWED_DOWNLOAD_ARGS TransferManager.ALLOWED_DOWNLOAD_ARGS ALLOWED_UPLOAD_ARGS TransferManager.ALLOWED_UPLOAD_ARGS ALLOWED_COPY_ARGS TransferManager.ALLOWED_COPY_ARGS常见的ExtraArgs取值包括完整列表以ALLOWED_DOWNLOAD_ARGS为准VersionId下载指定版本的对象需桶开启版本控制SSECustomerAlgorithm/SSECustomerKey/SSECustomerKeyMD5使用 SSE-C 客户托管密钥解密下载RequestPayer请求者付费桶场景下置为requesterExpectedBucketOwner指定期望的桶所有者账号 ID示例下载指定版本的对象import boto3 s3 boto3.client(s3) s3.download_file( amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME, ExtraArgs{VersionId: VERSION_ID}, )使用未列入白名单的键时s3transfer会拒绝该参数并抛出错误这保证了底层请求参数始终在 S3 服务支持的范围内。ExtraArgs同样适用于download_fileobj两者签名一致。Callback实时进度回调下载方法的Callback参数与上传方法用途完全相同一个可调用对象在传输过程中被周期性调用接收一个表示已传输字节数的参数。由于语义一致你可以为上传和下载复用同一个回调类。Callback需要实现__call__(self, bytes_amount)方法。以下示例展示一个线程安全的进度百分比回调可直接用于下载场景import os import sys import threading class ProgressPercentage(object): def __init__(self, filename): self._filename filename self._size float(os.path.getsize(filename)) self._seen_so_far 0 self._lock threading.Lock() def __call__(self, bytes_amount): with self._lock: self._seen_so_far bytes_amount percentage (self._seen_so_far / self._size) * 100 sys.stdout.write( \r%s %s / %s (%.2f%%) % ( self._filename, self._seen_so_far, self._size, percentage)) sys.stdout.flush()使用方式import boto3 s3 boto3.client(s3) s3.download_file( amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME, CallbackProgressPercentage(FILE_NAME), )需要注意下载场景下回调初始化时往往还不知道对象总大小只有本地文件上传时可直接os.path.getsize。更稳妥的做法是先用head_object获取ContentLength作为总大小基准或在首次回调时惰性获取。从实现层面看boto3/s3/transfer.py 的ProgressCallbackInvoker是回调的桥接层它继承s3transfer的BaseSubscriber把下载事件中的bytes_transferred转发给用户的回调函数class ProgressCallbackInvoker(BaseSubscriber): def __init__(self, callback): self._callback callback def on_progress(self, bytes_transferred, **kwargs): self._callback(bytes_transferred)由于回调可能被多线程并发调用多部分下载时回调内部使用锁保护累计字节数是一个值得坚持的实践。Config用 TransferConfig 调控下载行为除了ExtraArgs与Callback下载方法还接受第三个可选参数Config用于传入 boto3/s3/transfer.py 中定义的TransferConfig对象对传输过程进行精细调控。TransferConfig继承自s3transfer的配置基类其默认值定义在DEFAULTS中boto3/s3/transfer.py配置项默认值作用multipart_threshold8 MB超过该大小自动切换为多部分传输max_concurrency10传输时并发请求的最大线程数multipart_chunksize8 MB多部分传输中每个分片的大小num_download_attempts5下载流式数据传输失败后的重试次数io_chunksize256 KB下载 IO 队列中每个块的最大大小max_io_queue100下载时内存中排队等待写入的最大块数use_threadsTrue是否使用多线程执行传输max_bandwidthNone每秒最大带宽字节限制preferred_transfer_clientauto传输客户端偏好auto/classic/crt典型场景一降低下载并发以节约带宽。当下载会占用大量下行带宽时可调低max_concurrencyfrom boto3.s3.transfer import TransferConfig config TransferConfig(max_concurrency5) s3 boto3.client(s3) s3.download_file( amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME, Configconfig )典型场景二禁用线程串行下载。将use_threads置为False后传输全部在当前线程执行max_concurrency被忽略config TransferConfig(use_threadsFalse) s3 boto3.client(s3) s3.download_file( amzn-s3-demo-bucket, OBJECT_NAME, FILE_NAME, Configconfig )典型场景三针对大文件提高下载重试韧性。num_download_attempts控制的是开始流式接收数据之后发生的错误如连接中断、读取超时的重试次数而节流错误与 5xx 服务端错误已由 botocore 自动重试两者相互独立config TransferConfig(num_download_attempts10)关于preferred_transfer_client其合法值定义在 boto3/s3/constants.py 中分别为classic仅用经典 Python 传输管理器、crt仅用 CRT 高性能客户端与auto默认自动选择。当使用 CRT 传输管理器时上述部分配置项如num_download_attempts、max_io_queue、max_bandwidth会被忽略这一点在 boto3/s3/transfer.py 的注释中已明确说明。源码级原理多部分下载、并发与重试download_file/download_fileobj之所以被称为托管传输managed transfer是因为底层 boto3/s3/transfer.py 模块替用户自动处理了三件事自动切换多部分传输当对象大小超过multipart_threshold默认 8 MB时自动改用 Range 分片并行下载multipart_chunksize决定每个分片大小。并行下载通过max_concurrency控制的线程池并发拉取多个分片io_chunksize与max_io_queue共同约束内存中等待落盘的数据量。重试流式下载一旦开始botocore 无法自行重试响应流可能已被部分消费因此由s3transfer在模块层实现重试num_download_attempts控制重试次数。模块顶部注释boto3/s3/transfer.py明确概括了这几点自动多部分切换、并行传输、进度回调、以及botocore 无法为流式下载做重试本模块同时为上传与下载处理重试。异常处理细节在 boto3/s3/transfer.py 的S3Transfer.download_file中当s3transfer的重试次数耗尽抛出S3TransferRetriesExceededError时boto3 会将其转换为自身的RetriesExceededError重新抛出——这是为了保持向后兼容让长期依赖 boto3 异常的用户代码无需改动。传输客户端选择boto3/s3/transfer.py 的create_transfer_manager会根据preferred_transfer_client、是否安装awscrt及其版本要求不低于 0.19.18、以及实例是否针对 CRT 优化awscrt.s3.is_optimized_for_system()来决定使用 CRT 传输管理器还是经典TransferManager。_create_default_transfer_manager在use_threadsFalse时使用NonThreadedExecutor彻底关闭多线程。验证与测试仓库中的下载行为测试仓库的功能测试为上述行为提供了直接验证。在 tests/functional/test_s3.py 中测试桩stubber模拟了两种下载路径stub_single_part_download先模拟head_object获取对象大小再模拟一次get_object返回完整内容——对应小对象的单部分下载stub_multipart_download模拟head_object后连续多次携带Range头的get_object——对应大对象的多部分分片下载且每个分片返回带ContentRange的响应。对应的测试用例覆盖了三个入口与两种传输形态test_client_download、test_bucket_download、test_object_downloadtests/functional/test_s3.py验证Client、Bucket、Object三个入口调用download_fileobj后写入BytesIO的内容与源对象完全一致test_multipart_downloadtests/functional/test_s3.py用 55 字节内容、每片 5 字节、共 11 片来验证多部分分片下载的组装正确性test_download_progresstests/functional/test_s3.py验证下载过程中进度回调被正确触发test_raises_value_error_on_invalid_fileobjtests/functional/test_s3.py验证向download_fileobj传入未实现write的对象会抛出ValueError。单元测试 tests/unit/s3/test_inject.py 则验证了inject.download_file会创建S3Transfer上下文管理器并把bucket、key、filename等参数正确透传同时确认download_file/download_fileobj被注入到Client类属性中tests/unit/s3/test_inject.py。常见错误排查ValueError: Fileobj must implement write向download_fileobj传入了没有write方法的对象或误用了download_file的签名顺序。文件乱码或内容缺失以文本模式w打开目标文件而非二进制模式wb。InvalidExtraArgsErrorExtraArgs中使用了不在ALLOWED_DOWNLOAD_ARGS白名单内的键请核对键名拼写。RetriesExceededError流式下载过程中持续出现连接中断或读取超时重试达到num_download_attempts上限。可增大该值或检查网络与 S3 服务状态。无权限错误下载需要s3:GetObject权限下载指定版本时还需s3:GetObjectVersion请检查 IAM 策略。总结download_file适合把 S3 对象落盘为本地文件参数为(Bucket, Key, Filename)download_fileobj适合写入任何可写的二进制文件类对象参数为(Bucket, Key, Fileobj)Client、Bucket、Object三个入口功能等价可按上下文任选ExtraArgs的合法键由S3Transfer.ALLOWED_DOWNLOAD_ARGS限定支持版本下载、SSE-C 解密等高级场景Callback与上传方法完全兼容可在多部分下载的并发环境中安全地报告进度ConfigTransferConfig允许你调控多部分阈值、并发数、重试次数与带宽默认值已适配大多数场景。下载方法背后是一整套自动化的托管传输机制超过阈值自动分片、多线程并行拉取、模块层流式重试。理解这些底层行为详见 boto3/s3/transfer.py能帮助你在面对大文件、弱网或高并发下载需求时做出正确的配置决策。赞分享后端云原生【免费下载链接】boto3AWS SDK for Python (Boto3)项目地址https://gitcode.com/gh_mirrors/bo/boto3点击查看免费下载相关推荐【免费下载】 使用boto3实现高效安全的S3文件上传指南使用boto3实现高效安全的S3文件上传指南 前言 在云计算时代Amazon S3已成为存储和分发数据的标准服务之一。作为Python开发者我们可以通过bo后端云原生使用Python(boto3)实现Amazon S3条件请求的完整指南使用Python boto3 实现Amazon S3条件请求的完整指南 前言 在现代云存储应用中条件请求是一种强大的机制它允许开发者在执行S3操作前设置特定示例工程教程后端ToolJet 实战构建 AWS S3 文件上传与下载界面Dropdown Table File Picker 完整指南ToolJet 实战构建 AWS S3 文件上传与下载界面Dropdown Table File Picker 完整指南 本篇指南将带你使用 To低代码后端前端AI 应用MCP 服务上一篇KISS-Matcher参数调优完全指南voxel_size、robin_noise_bound等10个关键参数如何选下一篇Android应用换肤终极指南5分钟实现无侵入主题切换创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
