易用性接口

迭代器

class oss2.BucketIterator(service, prefix='', marker='', max_keys=100, max_retries=None)[源代码]

遍历用户Bucket的迭代器。

每次迭代返回的是 SimplifiedBucketInfo 对象。

参数:
  • service – Service 对象。
  • prefix – 只列举匹配该前缀的Bucket。
  • marker – 分页符。只列举Bucket名字典序在此之后的Bucket。
  • max_keys – 每次调用 list_buckets 时的max_keys参数。注意迭代器返回的数目可能会大于该值。
class oss2.ObjectIterator(bucket, prefix='', delimiter='', marker='', max_keys=100, max_retries=None)[源代码]

遍历Bucket里文件的迭代器。

每次迭代返回的是 SimplifiedObjectInfo 对象。当 SimplifiedObjectInfo.is_prefix() 返回True时，表明是公共前缀（目录）。

参数:
  • bucket – Bucket 对象。
  • prefix – 只列举匹配该前缀的文件。
  • delimiter – 目录分隔符。
  • marker – 分页符。
  • max_keys – 每次调用 list_objects 时的max_keys参数。注意迭代器返回的数目可能会大于该值。
class oss2.MultipartUploadIterator(bucket, prefix='', delimiter='', key_marker='', upload_id_marker='', max_uploads=1000, max_retries=None)[源代码]

遍历Bucket里未完成的分片上传。

每次返回 MultipartUploadInfo 对象。当 MultipartUploadInfo.is_prefix() 返回True时，表明是公共前缀（目录）。

参数:
  • bucket – Bucket 对象。
  • prefix – 仅列举匹配该前缀的文件的分片上传。
  • delimiter – 目录分隔符。
  • key_marker – 分页符。
  • upload_id_marker – 文件名分页符。
  • max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。
class oss2.ObjectUploadIterator(bucket, key, max_uploads=1000, max_retries=None)[源代码]

遍历一个Object所有未完成的分片上传。

每次返回 MultipartUploadInfo 对象。当 MultipartUploadInfo.is_prefix() 返回True时，表明是公共前缀（目录）。

参数:
  • bucket – Bucket 对象。
  • key – 文件名
  • max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。
class oss2.PartIterator(bucket, key, upload_id, marker='0', max_parts=1000, max_retries=None)[源代码]

遍历一个分片上传会话中已经上传的分片。

每次返回 PartInfo 对象。

参数:
  • bucket – Bucket 对象。
  • key – 文件名
  • upload_id – 分片上传ID
  • marker – 分页符。
  • max_parts – 每次调用 list_parts 时的max_parts参数。注意迭代器返回的数目可能会大于该值。

断点续传（上传、下载）

oss2.resumable_upload(bucket, key, filename, store=None, headers=None, multipart_threshold=None, part_size=None, progress_callback=None, num_threads=None)[源代码]

断点上传本地文件。采用分片上传方式上传本地文件。

缺省的并发数是 oss2.defaults.multipart_num_threads ，并且在本地磁盘保存已经上传的分片信息。如果因为某种原因上传被中断，下次上传同样的文件，即源文件和目标文件路径都一样，就只会上传缺失的分片。缺省条件下，该函数会在用户 HOME 目录下保存断点续传的信息。当待上传的本地文件没有发生变化，且目标文件名没有变化时，会根据本地保存的信息，从断点开始上传。

注解

  1. 如果使用CryptoBucket，函数会退化为普通上传。
参数:
  • bucket – Bucket 对象。
  • key – 文件名
  • filename – 待上传本地文件名。
  • store – 用来保存断点信息的持久存储，参见 ResumableStore 的接口。如不指定，则使用 ResumableStore 。
  • headers – 传给 put_object 或 init_multipart_upload 的HTTP头部。
  • multipart_threshold – 文件长度大于该值时，则用分片上传。
  • part_size – 指定分片上传的每个分片的大小。如不指定，则自动计算。
  • progress_callback – 上传进度回调函数。参见 上传下载进度 。
  • num_threads – 并发上传的线程数，如不指定则使用 oss2.defaults.multipart_num_threads 。
oss2.resumable_download(bucket, key, filename, multiget_threshold=None, part_size=None, progress_callback=None, num_threads=None, store=None)[源代码]

断点下载。

实现的方法是 :
  1. 在本地创建一个临时文件，文件名由原始文件名加上一个随机的后缀组成。
  2. 通过指定请求的 Range 头按照范围并发读取OSS文件，并写入到临时文件里对应的位置。
  3. 全部完成之后，把临时文件重命名为目标文件 （即 filename ）

在上述过程中，断点信息，即已经完成的范围，会保存在磁盘上。

因为某种原因下载中断，后续如果下载同样的文件，也就是源文件和目标文件一样，就会先读取断点信息，然后只下载缺失的部分。

缺省设置下，断点信息保存在 HOME 目录的一个子目录下。可以通过 store 参数更改保存位置。

注解

  1. 对同样的源文件、目标文件，避免多个程序（线程）同时调用该函数。因为断点信息会在磁盘上互相覆盖，或临时文件名会冲突。
  2. 避免使用太小的范围（分片），即 part_size 不宜过小，建议大于或等于 oss2.defaults.multiget_part_size 。
  3. 如果目标文件已经存在，那么该函数会覆盖此文件。
  4. 如果使用CryptoBucket，函数会退化为普通下载。
参数:
  • bucket – Bucket 对象。
  • key (str) – 待下载的远程文件名。
  • filename (str) – 本地的目标文件名。
  • multiget_threshold (int) – 文件长度大于该值时，则使用断点下载。
  • part_size (int) – 指定期望的分片大小，即每个请求获得的字节数，实际的分片大小可能有所不同。
  • progress_callback – 上传进度回调函数。参见 上传下载进度 。
  • num_threads – 并发下载的线程数，如不指定则使用 oss2.defaults.multiget_num_threads 。
  • store (ResumableDownloadStore) – 用来保存断点信息的持久存储，可以指定断点信息所在的目录。
异常:

如果OSS文件不存在，则抛出 NotFound ；也有可能抛出其他因下载文件而产生的异常。

FileObject适配器

class oss2.SizedFileAdapter(file_object, size)[源代码]

通过这个适配器（Adapter），可以把原先的 file_object 的长度限制到等于 size 。