oss2 package

Submodules

oss2.api module

文件上传方法中的data参数。

诸如 put_object 这样的上传接口都会有 data 参数用于接收用户数据。data 可以是下述类型。

• unicode类型（对于Python3则是str类型）：内部会自动转换为UTF-8的bytes
• bytes类型：不做任何转换
• file-like object：对于可以seek和tell的file object，从当前位置读取直到结束。其他类型，请确保当前位置是文件开始。
• 可迭代类型：对于无法探知长度的数据，要求一定是可迭代的。此时会通过Chunked Encoding传输。

Bucket配置修改方法中的input参数。

诸如 put_bucket_cors 这样的Bucket配置修改接口都会有 input 参数接收用户提供的配置数据。

• Bucket配置信息相关的类，如 BucketCors。
• unicode类型（对于Python3则是str类型）。
• 经过UTF-8编码的bytes类型。
• file-like对象。
• 可迭代类型，会通过 Chunked Encoding 传输。

也就是说 input 参数可以比 data 参数多接受第一种类型的输入。

返回值

Service 和 Bucket 类的大多数方法都是返回 RequestResult 及其子类。 RequestResult 包含了HTTP响应的状态码、头部以及OSS Request ID，而它的子类则包含用户真正想要的结果。例如，ListBucketsResult.buckets 就是返回的Bucket信息列表；GetObjectResult 则是一个file-like object，可以调用 read() 来获取响应的HTTP包体。

加密接口 CryptoBucket ：

CryptoBucket仅提供上传下载加密数据的接口，诸如 get_object、 put_object，返回值与Bucket相应接口一致。

异常

一般来说Python SDK可能会抛出三种类型的异常，这些异常都继承于 OssError ：

• ClientError ：由于用户参数错误而引发的异常。
• ServerError 及其子类：OSS服务器返回非成功的状态码，如4xx或5xx。
• RequestError ：底层requests库抛出的异常，如DNS解析错误，超时等。

当然，Bucket.put_object_from_file 和 Bucket.get_object_to_file 这类函数还会抛出文件相关的异常。

指定下载范围

诸如 get_object 以及 upload_part_copy 这样的函数，可以接受 byte_range 参数，表明读取数据的范围。该参数是一个二元tuple：(start, last)。这些接口会把它转换为Range头部的值，如：

• byte_range 为 (0, 99) 转换为 ‘bytes=0-99’，表示读取前100个字节
• byte_range 为 (None, 99) 转换为 ‘bytes=-99’，表示读取最后99个字节
• byte_range 为 (100, None) 转换为 ‘bytes=100-‘，表示读取第101个字节到文件结尾的部分（包含第101个字节）

分页罗列

罗列各种资源的接口，如 list_buckets 、 list_objects 都支持分页查询。通过设定分页标记（如：marker 、 key_marker ）的方式可以指定查询某一页。首次调用将分页标记设为空（缺省值，可以不设），后续的调用使用返回值中的 next_marker 、 next_key_marker 等。每次调用后检查返回值中的 is_truncated ，其值为 False 说明已经到了最后一页。

上传下载进度

上传下载接口，诸如 get_object 、 put_object 、resumable_upload，都支持进度回调函数，可以用它实现进度条等功能。

progress_callback 的函数原型如下

>>> def progress_callback(bytes_consumed, total_bytes):
>>>     '''progress callback
>>> 
>>>     :param int bytes_consumed: Consumed bytes. For upload it's uploaded bytes. for download it is download bytes.
>>>     :param int total_bytes: Total bytes.
>>>     '''

其中 total_bytes 对于上传和下载有不同的含义：

• 上传：当输入是bytes或可以seek/tell的文件对象，那么它的值就是总的字节数；否则，其值为None
• 下载：当返回的HTTP相应中有Content-Length头部，那么它的值就是Content-Length的值；否则，其值为None

Unix Time

OSS Python SDK会把从服务器获得时间戳都转换为自1970年1月1日UTC零点以来的秒数，即Unix Time。参见 Unix Time https://en.wikipedia.org/wiki/Unix_time

OSS中常用的时间格式有：

• HTTP Date格式，形如 Sat, 05 Dec 2015 11:04:39 GMT 这样的GMT时间。用在If-Modified-Since、Last-Modified这些HTTP请求、响应头里。
• ISO8601格式，形如 2015-12-05T00:00:00.000Z。用在生命周期管理配置、列举Bucket结果中的创建时间、列举文件结果中的最后修改时间等处。

http_date 函数把Unix Time转换为HTTP Date；而 http_to_unixtime 则做相反的转换。如:

>>> import oss2, time
>>> unix_time = int(time.time())             # Current time in UNIX Time, Value is 1449313829
>>> date_str = oss2.http_date(unix_time)     # The date_str will be 'Sat, 05 Dec 2015 11:10:29 GMT'
>>> oss2.http_to_unixtime(date_str)          # The result is 1449313829

注解

生成HTTP协议所需的日期（即HTTP Date）时，请使用 http_date ， 不要使用 strftime 这样的函数。因为后者是和locale相关的。比如， strftime 结果中可能会出现中文，而这样的格式，OSS服务器是不能识别的。

iso8601_to_unixtime 把ISO8601格式转换为Unix Time；date_to_iso8601 和 iso8601_to_date 则在ISO8601格式的字符串和datetime.date之间相互转换。如:

>>> import oss2
>>> d = oss2.iso8601_to_date('2015-12-05T00:00:00.000Z')  # Get datetime.date(2015, 12, 5)
>>> date_str = oss2.date_to_iso8601(d)                    # Get '2015-12-05T00:00:00.000Z'
>>> oss2.iso8601_to_unixtime(date_str)                    # Get 1449273600

class oss2.api.Bucket(auth, endpoint, bucket_name, is_cname=False, session=None, connect_timeout=None, app_name='', enable_crc=True)

基类：oss2.api._Base

用于Bucket和Object操作的类，诸如创建、删除Bucket，上传、下载Object等。

用法（假设Bucket属于杭州区域）:

>>> import oss2
>>> auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
>>> bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'your-bucket')
>>> bucket.put_object('readme.txt', 'content of the object')
<oss2.models.PutObjectResult object at 0x029B9930>

参数:

• auth (oss2.Auth) – 包含了用户认证信息的Auth对象
• endpoint (str) – 访问域名或者CNAME
• bucket_name (str) – Bucket
• is_cname (bool) – 如果endpoint是CNAME则设为True；反之，则为False。
• session (oss2.Session) – 会话。如果是None表示新开会话，非None则复用传入的会话。
• connect_timeout (float) – 连接超时时间，以秒为单位。
• app_name (str) – 应用名。该参数不为空，则在User Agent中加入其值。注意到，最终这个字符串是要作为HTTP Header的值传输的，所以必须要遵循HTTP标准。

ACL = 'acl'

BUCKET_INFO = 'bucketInfo'

COMP = 'comp'

CORS = 'cors'

LIFECYCLE = 'lifecycle'

LIVE = 'live'

LOCATION = 'location'

LOGGING = 'logging'

REFERER = 'referer'

STAT = 'stat'

STATUS = 'status'

SYMLINK = 'symlink'

VOD = 'vod'

WEBSITE = 'website'

abort_multipart_upload(key, upload_id)

取消分片上传。

参数:

• key (str) – 待上传的文件名，这个文件名要和 init_multipart_upload() 的文件名一致。
• upload_id (str) – 分片上传ID

返回:

RequestResult

append_object(key, position, data, headers=None, progress_callback=None, init_crc=None)

追加上传一个文件。

参数:

• key (str) – 新的文件名，或已经存在的可追加文件名
• position (int) – 追加上传一个新的文件， position 设为0；追加一个已经存在的可追加文件， position 设为文件的当前长度。position 可以从上次追加的结果 AppendObjectResult.next_position 中获得。
• data (str,bytes,file-like object or iterator object.) – 用户数据
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 用户指定的HTTP头部。可以指定Content-Type、Content-MD5、x-oss-开头的头部等
• progress_callback – 用户指定的进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。

返回:

AppendObjectResult

Raises:

如果 position 和当前文件长度不一致，抛出 PositionNotEqualToLength ；如果当前文件不是可追加类型，抛出 ObjectNotAppendable ；还会抛出其他一些异常。

batch_delete_objects(key_list)

批量删除文件。待删除文件列表不能为空。

参数:key_list (list of str) – 文件名列表，不能为空。 返回:BatchDeleteObjectsResult

complete_multipart_upload(key, upload_id, parts, headers=None)

完成分片上传，创建文件。

参数:

• key (str) – 待上传的文件名，这个文件名要和 init_multipart_upload() 的文件名一致。
• upload_id (str) – 分片上传ID
• parts (list of PartInfo) – PartInfo列表。PartInfo中的part_number和etag是必填项。其中的etag可以从 upload_part() 的返回值中得到。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

PutObjectResult

copy_object(source_bucket_name, source_key, target_key, headers=None)

拷贝一个文件到当前Bucket。

参数:

• source_bucket_name (str) – 源Bucket名
• source_key (str) – 源文件名
• target_key (str) – 目标文件名
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

PutObjectResult

create_bucket(permission=None, input=None)

创建新的Bucket。

参数:

• permission (str) – 指定Bucket的ACL。可以是oss2.BUCKET_ACL_PRIVATE（推荐、缺省）、oss2.BUCKET_ACL_PUBLIC_READ或是oss2.BUCKET_ACL_PUBLIC_READ_WRITE。
• input – BucketCreateConfig object

create_live_channel(channel_name, input)

创建推流直播频道。

参数:

• channel_name (str) – 创建推流直播频道。
• input – LiveChannelInfo类型，包含了live channel中的描述信息。

返回:

CreateLiveChannelResult

delete_bucket()

删除一个Bucket。只有没有任何文件，也没有任何未完成的分片上传的Bucket才能被删除。

返回:RequestResult Raises:如果试图删除一个非空Bucket，则抛出 BucketNotEmpty

delete_bucket_cors()

删除Bucket的CORS配置。

delete_bucket_lifecycle()

删除生命周期管理配置。如果Lifecycle没有设置，也返回成功。

delete_bucket_logging()

关闭Bucket的访问日志功能。

delete_bucket_website()

关闭Bucket的静态网站托管功能。

delete_live_channel(channel_name)

删除推流直播频道

参数:channel_name (str) – 创建推流直播频道。

delete_object(key)

删除一个文件。

参数:key (str) – 待上传的文件名 返回:RequestResult

get_bucket_acl()

获取Bucket的ACL。

返回:GetBucketAclResult

get_bucket_cors()

获取Bucket的CORS配置

返回:GetBucketCorsResult

get_bucket_info()

获取bucket相关信息，如创建时间，访问Endpoint，Owner与ACL等。

返回:GetBucketInfoResult

get_bucket_lifecycle()

获取生命周期管理配置。

返回:GetBucketLifecycleResult Raises:如果没有设置Lifecycle，则抛出 NoSuchLifecycle

get_bucket_location()

获取Bucket的数据中心。

返回:GetBucketLocationResult

get_bucket_logging()

获取Bucket的访问日志功能配置。

返回:GetBucketLoggingResult

get_bucket_referer()

获取Bucket的防盗链配置。

返回:GetBucketRefererResult

get_bucket_stat()

查看Bucket的状态，目前包括bucket大小，bucket的object数量，bucket正在上传的Multipart Upload事件个数等。

返回:GetBucketStatResult

get_bucket_website()

获取Bucket的静态网站托管配置。

返回:GetBucketWebsiteResult Raises:如果没有设置静态网站托管，那么就抛出 NoSuchWebsite

get_live_channel(channel_name)

获取直播频道配置

参数:channel_name (str) – 创建推流直播频道。 返回:GetLiveChannelResult

get_live_channel_history(channel_name)

获取live channel中最近的最多十次的推流记录，记录中包含推流的起止时间和远端的地址。

参数:channel_name (str) – 创建推流直播频道。 返回:GetLiveChannelHistoryResult

get_live_channel_stat(channel_name)

获取live channel当前推流的状态。

参数:channel_name (str) – 创建推流直播频道。 返回:GetLiveChannelStatResult

get_object(key, byte_range=None, headers=None, progress_callback=None, process=None, params=None)

下载一个文件。

用法:

>>> result = bucket.get_object('readme.txt')
>>> print(result.read())
'hello world'

参数:

• key – 上传到OSS的文件名
• byte_range – 指定下载范围。参见 指定下载范围
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部
• progress_callback – 用户指定的进度回调函数。参考 上传下载进度
• process – OSS文件处理，如图像服务等。指定后process，返回的内容为处理后的文件
• params – 请求的查询字符串参数。

返回:

file-like对象

Raises:

如果文件不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

get_object_acl(key)

设置文件的ACL。

返回:GetObjectAclResult

get_object_meta(key)

获取文件基本元信息，包括该Object的ETag、Size（文件大小）、LastModified，并不返回其内容。

HTTP响应的头部包含了文件基本元信息，可以通过 GetObjectMetaResult 的 last_modified，content_length, etag 成员获得。

参数:key – 文件名 返回:GetObjectMetaResult Raises:如果文件不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

get_object_to_file(key, filename, byte_range=None, headers=None, progress_callback=None, process=None, params=None)

下载一个文件到本地文件。

参数:

• key – OSS侧的对象名。
• filename – 本地文件名。要求父目录已经存在，且有写权限。
• byte_range – 指定下载范围。参见 指定下载范围
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部
• progress_callback – 用户指定的进度回调函数。参考 上传下载进度
• process – OSS文件处理，如图像服务等。指定后process，返回的内容为处理后的文件

返回:

如果文件不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

get_symlink(symlink_key)

获取符号连接文件的目标文件。

参数:symlink_key (str) – 符号连接类文件。 返回:GetSymlinkResult Raises:如果文件的符号链接不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

head_object(key, headers=None)

获取文件元信息。

HTTP响应的头部包含了文件元信息，可以通过 RequestResult 的 headers 成员获得。

用法:

>>> result = bucket.head_object('readme.txt')
>>> print(result.content_type)
text/plain

参数:

• key – OSS侧的对象名。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

HeadObjectResult

Raises:

如果Bucket不存在或者Object不存在，则抛出 NotFound

init_multipart_upload(key, headers=None)

初始化分片上传。

返回值中的 upload_id 以及`Bucket名`和`Object名`三元组唯一对应了此次分片上传事件。

参数:

• key (str) – 待上传的文件名
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

InitMultipartUploadResult

list_live_channel(prefix='', marker='', max_keys=100)

列举出Bucket下所有符合条件的live channel。

参数:

• prefix (str) – list时channel_id的公共前缀
• marker (str) – list时指定的起始标记
• max_keys (int) – 本次list返回live channel的最大个数

返回:

ListLiveChannelResult

list_multipart_uploads(prefix='', delimiter='', key_marker='', upload_id_marker='', max_uploads=1000)

罗列正在进行中的分片上传。支持分页。

参数:

• prefix (str) – 只罗列匹配该前缀的文件的分片上传。
• delimiter (str) – 目录分割符
• key_marker (str) – 文件名分页符。第一次调用可以不传，后续设为返回值中的 next_key_marker 。
• upload_id_marker (str) – 分片ID分页符。第一次调用可以不传，后续设为返回值中的 next_upload_id_marker 。
• max_uploads (int) – 一次罗列最多能够返回的条目数。

返回:

ListMultipartUploadsResult

list_objects(prefix='', delimiter='', marker='', max_keys=100)

根据前缀罗列Bucket里的文件。

参数:

• prefix (str) – 只罗列文件名为该前缀的文件。
• delimiter (str) – 分隔符。可以用来模拟目录。
• marker (str) – 分页标志。首次调用传空串，后续使用返回值的next_marker。
• max_keys (int) – 最多返回文件的个数，文件和目录的和不能超过该值。

返回:

ListObjectsResult

list_parts(key, upload_id, marker='', max_parts=1000)

列举已经上传的分片。支持分页。

参数:

• key (str) – 待上传的文件名
• upload_id (str) – 分片上传ID
• marker (str) – 一次最多罗列多少分片
• max_parts (int) – 一次罗列最多能够返回的条目数。

返回:

ListPartsResult

object_exists(key)

如果文件存在就返回True，否则返回False。如果Bucket不存在，或是发生其他错误，则抛出异常。

post_vod_playlist(channel_name, playlist_name, start_time=0, end_time=0)

根据指定的playlist name以及startTime和endTime生成一个点播的播放列表。

参数:

• channel_name (str) – 创建推流直播频道。
• playlist_name (str) – 要生成点播列表m3u8文件的名称。
• start_time (int) – 点播的起始时间，Unix Time格式，可以使用int(time.time())获取
• end_time (int) – 点播的结束时间，Unix Time格式，可以使用int(time.time())获取

put_bucket_acl(permission)

设置Bucket的ACL。

参数:permission (str) – 新的ACL，可以是oss2.BUCKET_ACL_PRIVATE、oss2.BUCKET_ACL_PUBLIC_READ或oss2.BUCKET_ACL_PUBLIC_READ_WRITE

put_bucket_cors(input)

设置Bucket的CORS。

参数:input – BucketCors 对象或其他。

put_bucket_lifecycle(input)

设置生命周期管理的配置。

参数:input – BucketLifecycle 对象或其他。

put_bucket_logging(input)

设置Bucket的访问日志功能。

参数:input – BucketLogging 对象或其他。

put_bucket_referer(input)

为Bucket设置防盗链。

参数:input – BucketReferer 对象或其他。

put_bucket_website(input)

为Bucket配置静态网站托管功能。

参数:input – BucketWebsite

put_live_channel_status(channel_name, status)

更改live channel的status，仅能在’enabled’和’disabled’两种状态中更改。

参数:

• channel_name (str) – 创建推流直播频道。
• status (str) – live channel的目标状态。

put_object(key, data, headers=None, progress_callback=None)

上传一个普通文件。

用法:

>>> bucket.put_object('readme.txt', 'content of readme.txt')
>>> with open(u'local_file.txt', 'rb') as f:
>>>     bucket.put_object('remote_file.txt', f)

上传文件夹。

>>> bucket.enable_crc = False # this is needed as by default crc is enabled and it will not work when creating folder.
>>> bucket.put_object('testfolder/', None)

参数:

• key – OSS侧的对象名。
• data (bytes, str or file-like object.) – 待上传的内容。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 用户指定的HTTP头部。可以指定Content-Type、Content-MD5、x-oss-开头的头部等。
• progress_callback – 用户指定的进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。

返回:

PutObjectResult

put_object_acl(key, permission)

设置文件的ACL。

参数:

• key (str) – 文件名
• permission (str) – 可以是oss2.OBJECT_ACL_DEFAULT,oss2.OBJECT_ACL_PRIVATE,oss2.OBJECT_ACL_PUBLIC_READ或oss2.OBJECT_ACL_PUBLIC_READ_WRITE.

返回:

RequestResult

put_object_from_file(key, filename, headers=None, progress_callback=None)

上传一个本地文件到OSS的普通文件。

参数:

• key (str) – 上传到OSS的文件名
• filename (str) – 本地文件名，需要有可读权限
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 用户指定的HTTP头部。可以指定Content-Type、Content-MD5、x-oss-meta-开头的头部等。
• progress_callback – 用户指定的进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。

返回:

PutObjectResult

put_symlink(target_key, symlink_key, headers=None)

创建Symlink。

参数:

• target_key (str) – 目标文件，目标文件不能为符号连接。
• symlink_key (str) – 符号连接类文件，其实质是一个特殊的文件，数据指向目标文件。

返回:

RequestResult

restore_object(key)

恢复一个对象。

如果是第一次针对该object调用接口，返回RequestResult.status = 202。如果已经成功调用过restore接口，且服务端仍处于解冻中，抛异常RestoreAlreadyInProgress(status=409)如果已经成功调用过restore接口，且服务端解冻已经完成，再次调用时返回RequestResult.status = 200，且会将object的可下载时间延长一天，最多延长7天。如果object不存在，则抛异常NoSuchKey(status=404)。对非Archive类型的Object提交restore，则抛异常OperationNotSupported(status=400)也可以通过调用head_object接口来获取meta信息来判断是否可以restore与restore的状态。

用法:

>>> meta = bucket.head_object(key)
>>> if meta.resp.headers['x-oss-storage-class'] == oss2.BUCKET_STORAGE_CLASS_ARCHIVE:
>>>     bucket.restore_object(key)
>>>         while True:
>>>             meta = bucket.head_object(key)
>>>             if meta.resp.headers['x-oss-restore'] == 'ongoing-request="true"':
>>>                 time.sleep(5)
>>>             else:
>>>                 break

参数:key (str) – 文件名 返回:RequestResult

sign_rtmp_url(channel_name, playlist_name, expires)

直播频道中的推流记录信息。

生成RTMP推流的签名URL。常见的用法是生成加签的URL以供授信用户向OSS推RTMP流。

参数:

• channel_name – 直播频道的名称。
• expires – 过期时间（单位：秒），链接在当前时间再过expires秒后过期。
• playlist_name – 播放列表名称，注意与创建live channel时一致。
• params – 需要签名的HTTP查询参数。

返回:

签名URL。

sign_url(method, key, expires, headers=None, params=None)

生成签名URL。

常见的用法是生成加签的URL以供授信用户下载，如为log.jpg生成一个5分钟后过期的下载链接:

>>> bucket.sign_url('GET', 'log.jpg', 5 * 60)
'http://your-bucket.oss-cn-hangzhou.aliyuncs.com/logo.jpg?OSSAccessKeyId=YourAccessKeyId\&Expires=1447178011&Signature=UJfeJgvcypWq6Q%2Bm3IJcSHbvSak%3D'

参数:

• method (str) – HTTP方法，如’GET’、’PUT’、’DELETE’等。
• key – 待上传的文件名
• expires – 过期时间（单位：秒），链接在当前时间再过expires秒后过期。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 需要签名的HTTP头部，如名称以x-oss-meta-开头的头部（作为用户自定义元数据）、Content-Type头部等。对于下载，不需要填。
• params – 需要签名的HTTP查询参数。

返回:

签名URL。

update_object_meta(key, headers)

更改Object的元数据信息，包括Content-Type这类标准的HTTP头部，以及以x-oss-meta-开头的自定义元数据。

用户可以通过 head_object() 获得元数据信息。

参数:

• key (str) – 文件名
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

RequestResult

upload_part(key, upload_id, part_number, data, progress_callback=None, headers=None)

上传一个分片。

参数:

• key (str) – 待上传文件名，这个文件名要和 init_multipart_upload() 的文件名一致。
• upload_id (str) – 分片上传ID
• part_number (int) – 分片号，最小值是1。
• data – 待上传数据。
• progress_callback – 用户指定进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 用户指定的HTTP头部。可以指定Content-MD5头部等。

返回:

PutObjectResult

upload_part_copy(source_bucket_name, source_key, byte_range, target_key, target_upload_id, target_part_number, headers=None)

分片拷贝。把一个已有文件的一部分或整体拷贝成目标文件的一个分片。

参数:

• byte_range – 指定待拷贝内容在源文件里的范围。参见 指定下载范围
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部

返回:

PutObjectResult

class oss2.api.CryptoBucket(auth, endpoint, bucket_name, crypto_provider, is_cname=False, session=None, connect_timeout=None, app_name='', enable_crc=True)

用于加密Bucket和Object操作的类，诸如上传、下载Object等。创建、删除bucket的操作需使用Bucket类接口。

用法（假设Bucket属于杭州区域）

>>> import oss2
>>> auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
>>> bucket = oss2.CryptoBucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', 'your-bucket', oss2.LocalRsaProvider())
>>> bucket.put_object('readme.txt', 'content of the object')
<oss2.models.PutObjectResult object at 0x029B9930>

参数:

• auth (oss2.Auth) – 包含了用户认证信息的Auth对象
• endpoint (str) – 访问域名或者CNAME
• bucket_name (str) – Bucket名
• crypto_provider (oss2.crypto.LocalRsaProvider) – 客户端加密类。该参数默认为空。
• is_cname (bool) – 如果endpoint是CNAME则设为True；反之，则为False。
• session (oss2.Session) – 会话。如果是None表示新开会话，非None则复用传入的会话。
• connect_timeout (float) – 连接超时时间，以秒为单位。
• app_name (str) – 应用名。该参数不为空，则在User Agent中加入其值。注意到，最终这个字符串是要作为HTTP Header的值传输的，所以必须要遵循HTTP标准。
• enable_crc (bool) – 如果开启crc校验则设为True；反之，则为False。

get_object(key, headers=None, progress_callback=None, params=None)

下载一个文件。

用法:

>>> result = bucket.get_object('readme.txt')
>>> print(result.read())
'hello world'

参数:

• key – OSS侧的对象名。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部
• progress_callback – 上传进度回调函数。参见 上传下载进度 。

返回:

file-like对象。

Raises:

如果文件不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

get_object_to_file(key, filename, headers=None, progress_callback=None, params=None)

下载一个文件到本地文件。

参数:

• key – OSS侧的对象名。
• filename – 本地文件名。要求父目录已经存在，且有写权限。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP头部
• progress_callback – 上传进度回调函数。参见 上传下载进度 。
• process – OSS文件处理，如图像服务等。指定后process，返回的内容为处理后的文件。

返回:

如果文件不存在，则抛出 NoSuchKey ；还可能抛出其他异常。

put_object(key, data, headers=None, progress_callback=None)

上传一个普通文件。

用法:

>>> bucket.put_object('readme.txt', 'content of readme.txt')
>>> with open(u'local_file.txt', 'rb') as f:
>>>     bucket.put_object('remote_file.txt', f)

参数:

• key – OSS侧的对象名。
• data (bytes, str or file-like object) – 待上传的内容。
• headers (dict or oss2.CaseInsensitiveDict(recommended)) – 用户指定的HTTP头部。可以指定Content-Type、Content-MD5、x-oss-开头的头部等
• progress_callback – 用户指定的进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。

返回:

PutObjectResult

put_object_from_file(key, filename, headers=None, progress_callback=None)

上传一个本地文件到OSS的普通文件。

参数:

• key (str) – OSS侧的对象名。
• filename (str) – 本地文件名，需要有可读权限。
• headers (dict, but recommendation is oss2.CaseInsensitiveDict) – 用户指定的HTTP头部。可以指定Content-Type、Content-MD5、x-oss-开头的头部等。
• progress_callback – 用户指定的进度回调函数。可以用来实现进度条等功能。参考 上传下载进度 。

返回:

PutObjectResult

class oss2.api.Service(auth, endpoint, session=None, connect_timeout=None, app_name='')

基类：oss2.api._Base

用于Service操作的类，如罗列用户所有的Bucket。

用法:

>>> import oss2
>>> auth = oss2.Auth('your-access-key-id', 'your-access-key-secret')
>>> service = oss2.Service(auth, 'oss-cn-hangzhou.aliyuncs.com')
>>> service.list_buckets()
<oss2.models.ListBucketsResult object at 0x0299FAB0>

参数:

• auth (oss2.Auth) – 包含了用户认证信息的Auth对象。
• endpoint (str) – 访问域名，如杭州区域的域名为’oss-cn-hangzhou.aliyuncs.com’。
• session (oss2.Session) – 会话。如果是None表示新开会话，非None则复用传入的会话。
• connect_timeout (float) – 连接超时时间，以秒为单位。
• app_name (str) – 应用名。该参数不为空，则在User Agent中加入其值。注意到，最终这个字符串是要作为HTTP Header的值传输的，所以必须要遵循HTTP标准。

list_buckets(prefix='', marker='', max_keys=100)

根据前缀罗列用户的Bucket。

参数:

• prefix (str) – 只罗列Bucket名为该前缀的Bucket，空串表示罗列所有的Bucket。
• marker (str) – 分页标志。首次调用传空串，后续使用返回值中的next_marker。
• max_keys (int) – 每次调用最多返回的Bucket数目。

返回:

罗列的结果

返回类型:

ListBucketsResult

oss2.auth module

class oss2.auth.AnonymousAuth

基类：object

用于匿名访问。

注解

匿名用户只能读取public-read的Bucket，或只能读取、写入public-read-write的Bucket。不能进行Service、Bucket相关的操作，也不能罗列文件等。

class oss2.auth.Auth(access_key_id, access_key_secret)

基类：oss2.auth.AuthBase

签名版本1，用于保存用户AccessKeyId、AccessKeySecret，以及计算签名的对象。

class oss2.auth.AuthBase(access_key_id, access_key_secret)

基类：object

用于保存用户AccessKeyId、AccessKeySecret，以及计算签名的对象。

class oss2.auth.AuthV2(access_key_id, access_key_secret)

基类：oss2.auth.AuthBase

签名版本2，与版本1的区别在：1. 使用SHA256算法，具有更高的安全性2. 参数计算包含所有的HTTP查询参数

class oss2.auth.StsAuth(access_key_id, access_key_secret, security_token, auth_version='v1')

基类：object

用于STS临时凭证访问。可以通过官方STS客户端获得临时密钥（AccessKeyId、AccessKeySecret）以及临时安全令牌（SecurityToken）。

注解

临时凭证会在一段时间后过期，在此之前需要重新获取临时凭证，并更新 Bucket 的 auth 成员变量为新的 StsAuth 实例。

参数:

• access_key_id (str) – 临时AccessKeyId
• access_key_secret (str) – 临时AccessKeySecret
• security_token (str) – 临时安全令牌(SecurityToken)
• auth_version (str) – 需要生成auth的版本，默认为AUTH_VERSION_1(v1)

oss2.auth.make_auth(access_key_id, access_key_secret, auth_version='v1')

oss2.auth.v2_uri_encode(raw_text)

oss2.compat module

兼容Python版本

oss2.compat.stringify(input)

oss2.compat.to_bytes(data)

若输入为unicode， 则转为utf-8编码的bytes；其他则原样返回。

oss2.compat.to_string(data)

把输入转换为str对象

oss2.compat.to_unicode(data)

把输入转换为unicode，要求输入是unicode或者utf-8编码的bytes。

oss2.crypto module

oss2.encryption

该模块包含了客户端加解密相关的函数和类。

class oss2.crypto.AliKMSProvider(access_key_id, access_key_secret, region, cmkey, sts_token=None, passphrase=None, cipher=<class oss2.utils.AESCipher>)

基类：oss2.crypto.BaseCryptoProvider

使用aliyun kms服务加密数据密钥。kms的详细说明参见 https://help.aliyun.com/product/28933.html?spm=a2c4g.11186623.3.1.jlYT4v

此接口在py3.3下暂时不可用，详见 https://github.com/aliyun/aliyun-openapi-python-sdk/issues/61

参数:

• access_key_id (str) – 可以访问kms密钥服务的access_key_id
• access_key_secret (str) – 可以访问kms密钥服务的access_key_secret
• region (str) – kms密钥服务地区
• cmkey (str) – 用户主密钥
• sts_token (str) – security token，如果使用的是临时AK需提供。
• passphrase (str) – kms密钥服务密码
• cipher (class) – 数据加密，默认aes256，当前仅支持默认实现

build_header(headers=None)

decrypt_oss_meta_data(headers, key, conv=<function <lambda>>)

get_key()

get_start()

class oss2.crypto.BaseCryptoProvider(cipher)

基类：object

CryptoProvider 基类，提供基础的数据加密解密adapter

make_decrypt_adapter(stream, key, start)

make_encrypt_adapter(stream, key, start)

class oss2.crypto.LocalRsaProvider(dir=None, key='', passphrase=None, cipher=<class oss2.utils.AESCipher>)

基类：oss2.crypto.BaseCryptoProvider

使用本地RSA加密数据密钥。

参数:

• dir (str) – 本地RSA公钥私钥存储路径
• key (str) – 本地RSA公钥私钥名称前缀
• passphrase (str) – 本地RSA公钥私钥密码
• cipher (class) – 数据加密，默认aes256，用户可自行实现对称加密算法，需符合AESCipher注释规则。

PRIV_KEY_FILE = '.private_key.pem'

PUB_KEY_FILE = '.public_key.pem'

build_header(headers=None)

decrypt_oss_meta_data(headers, key, conv=<function <lambda>>)

get_key()

get_start()

oss2.defaults module

oss2.defaults

全局缺省变量

oss2.defaults.connect_timeout = 60

连接超时时间

oss2.defaults.connection_pool_size = 10

每个Session连接池大小

oss2.defaults.get(value, default_value)

oss2.defaults.get_logger()

oss2.defaults.logger = <logging.RootLogger object>

缺省Logger

oss2.defaults.multiget_num_threads = 4

并行下载（multiget）缺省线程数

oss2.defaults.multiget_part_size = 10485760

并行下载（multiget）的缺省分片大小

oss2.defaults.multiget_threshold = 104857600

对于断点下载，如果OSS文件大小大于该值就进行并行下载（multiget）

oss2.defaults.multipart_num_threads = 1

分片上传缺省线程数

oss2.defaults.multipart_threshold = 10485760

对于某些接口，上传数据长度大于或等于该值时，就采用分片上传。

oss2.defaults.part_size = 10485760

缺省分片大小

oss2.defaults.request_retries = 3

缺省重试次数

oss2.exceptions module

oss2.exceptions

异常类。

exception oss2.exceptions.AccessDenied(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'AccessDenied'

status = 403

exception oss2.exceptions.BucketNotEmpty(status, headers, body, details)

基类：oss2.exceptions.Conflict

code = 'BucketNotEmpty'

status = 409

exception oss2.exceptions.ChannelStillLive(status, headers, body, details)

基类：oss2.exceptions.Conflict

code = 'ChannelStillLive'

status = 409

exception oss2.exceptions.ClientError(message)

基类：oss2.exceptions.OssError

exception oss2.exceptions.Conflict(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = ''

status = 409

exception oss2.exceptions.InconsistentError(message, request_id='')

基类：oss2.exceptions.OssError

exception oss2.exceptions.InvalidArgument(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'InvalidArgument'

status = 400

exception oss2.exceptions.InvalidDigest(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'InvalidDigest'

status = 400

exception oss2.exceptions.InvalidObjectName(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'InvalidObjectName'

status = 400

exception oss2.exceptions.InvalidRequest(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'InvalidRequest'

status = 400

exception oss2.exceptions.LiveChannelDisabled(status, headers, body, details)

基类：oss2.exceptions.Conflict

code = 'LiveChannelDisabled'

status = 409

exception oss2.exceptions.MalformedXml(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'MalformedXML'

status = 400

exception oss2.exceptions.NoSuchBucket(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchBucket'

status = 404

exception oss2.exceptions.NoSuchCors(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchCORSConfiguration'

status = 404

exception oss2.exceptions.NoSuchKey(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchKey'

status = 404

exception oss2.exceptions.NoSuchLifecycle(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchLifecycle'

status = 404

exception oss2.exceptions.NoSuchLiveChannel(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchLiveChannel'

status = 404

exception oss2.exceptions.NoSuchUpload(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchUpload'

status = 404

exception oss2.exceptions.NoSuchWebsite(status, headers, body, details)

基类：oss2.exceptions.NotFound

code = 'NoSuchWebsiteConfiguration'

status = 404

exception oss2.exceptions.NotFound(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = ''

status = 404

exception oss2.exceptions.NotModified(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = ''

status = 304

exception oss2.exceptions.ObjectNotAppendable(status, headers, body, details)

基类：oss2.exceptions.Conflict

code = 'ObjectNotAppendable'

status = 409

exception oss2.exceptions.OpenApiFormatError(message)

基类：oss2.exceptions.OssError

exception oss2.exceptions.OpenApiServerError(status, request_id, message, error_code)

基类：oss2.exceptions.OssError

exception oss2.exceptions.OperationNotSupported(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'OperationNotSupported'

status = 400

exception oss2.exceptions.OssError(status, headers, body, details)

基类：exceptions.Exception

body = None

HTTP响应体（部分）

code = None

OSS错误码

details = None

详细错误信息，是一个string到string的dict。

request_id = None

请求ID，用于跟踪一个OSS请求。提交工单时，最好能够提供请求ID。

status = None

HTTP 状态码（比如200）

exception oss2.exceptions.PositionNotEqualToLength(status, headers, body, details)

基类：oss2.exceptions.Conflict

code = 'PositionNotEqualToLength'

status = 409

exception oss2.exceptions.PreconditionFailed(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'PreconditionFailed'

status = 412

exception oss2.exceptions.RequestError(e)

基类：oss2.exceptions.OssError

exception oss2.exceptions.RestoreAlreadyInProgress(status, headers, body, details)

基类：oss2.exceptions.ServerError

code = 'RestoreAlreadyInProgress'

status = 409

exception oss2.exceptions.ServerError(status, headers, body, details)

基类：oss2.exceptions.OssError

oss2.exceptions.klass

oss2.exceptions.AccessDenied 的别名

oss2.exceptions.make_exception(resp)

oss2.http module

oss2.http

这个模块包含了HTTP Adapters。尽管OSS Python SDK内部使用requests库进行HTTP通信，但是对使用者是透明的。该模块中的 Session、 Request、 Response 对requests的对应的类做了简单的封装。

class oss2.http.Request(method, url, data=None, params=None, headers=None, app_name='')

基类：object

class oss2.http.Response(response)

基类：object

read(amt=None)

class oss2.http.Session

基类：object

属于同一个Session的请求共享一组连接池，如有可能也会重用HTTP连接。

do_request(req, timeout)

oss2.iterators module

oss2.iterators

该模块包含了一些易于使用的迭代器，可以用来遍历Bucket、文件、分片上传等。

class oss2.iterators.BucketIterator(service, prefix='', marker='', max_keys=100, max_retries=None)

基类：oss2.iterators._BaseIterator

遍历用户Bucket的迭代器。

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

参数:

• service – Service 对象
• prefix – 只列举匹配该前缀的Bucket。
• marker – 分页符。只列举Bucket名字典序在此之后的Bucket。
• max_keys – 每次调用 list_objects 时的max_keys参数。注意迭代器返回的数目可能会大于该值。

class oss2.iterators.LiveChannelIterator(bucket, prefix='', marker='', max_keys=100, max_retries=None)

基类：oss2.iterators._BaseIterator

遍历Bucket里文件的迭代器。

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

参数:

• bucket – Bucket 对象
• prefix – 只列举匹配该前缀的文件
• marker – 分页符
• max_keys – 每次调用 list_live_channel 时的max_keys参数。注意迭代器返回的数目可能会大于该值。

class oss2.iterators.MultipartUploadIterator(bucket, prefix='', delimiter='', key_marker='', upload_id_marker='', max_uploads=1000, max_retries=None)

基类：oss2.iterators._BaseIterator

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

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

参数:

• bucket – Bucket 对象
• prefix – 仅列举匹配该前缀的文件的分片上传。
• delimiter – 目录分隔符
• key_marker – 分页符
• upload_id_marker – 分片上传ID分页符
• max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。

class oss2.iterators.ObjectIterator(bucket, prefix='', delimiter='', marker='', max_keys=100, max_retries=None)

基类：oss2.iterators._BaseIterator

遍历Bucket里文件的迭代器。

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

参数:

• bucket – Bucket 对象
• prefix – 只列举匹配该前缀的文件
• delimiter – 目录分隔符
• marker – 分页符
• max_keys – 每次调用 list_objects 时的max_keys参数。注意迭代器返回的数目可能会大于该值。

class oss2.iterators.ObjectUploadIterator(bucket, key, max_uploads=1000, max_retries=None)

基类：oss2.iterators._BaseIterator

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

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

参数:

• bucket – Bucket 对象
• key – 待上传的文件名
• max_uploads – 每次调用 list_multipart_uploads 时的max_uploads参数。注意迭代器返回的数目可能会大于该值。

class oss2.iterators.PartIterator(bucket, key, upload_id, marker='0', max_parts=1000, max_retries=None)

基类：oss2.iterators._BaseIterator

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

每次返回 PartInfo 对象。

参数:

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

oss2.models module

oss2.models

该模块包含Python SDK API接口所需要的输入参数以及返回值类型。

class oss2.models.AbortMultipartUpload(days=None, created_before_date=None)

基类：object

删除parts

参数:

• days – 删除相对最后修改时间days天之后的parts。
• created_before_date – 删除最后修改时间早于created_before_date的parts。

class oss2.models.AccessControlList(grant)

基类：object

class oss2.models.AppendObjectResult(resp)

基类：oss2.models.RequestResult

crc = None

本次追加写完成后，OSS上文件的CRC64值

etag = None

HTTP ETag

next_position = None

下次追加写的偏移

class oss2.models.BatchDeleteObjectsResult(resp)

基类：oss2.models.RequestResult

deleted_keys = None

已经删除的文件名列表

class oss2.models.BucketCors(rules=None)

基类：object

class oss2.models.BucketCreateConfig(storage_class)

基类：object

class oss2.models.BucketInfo(name=None, owner=None, location=None, storage_class=None, intranet_endpoint=None, extranet_endpoint=None, creation_date=None, acl=None)

基类：object

class oss2.models.BucketLifecycle(rules=None)

基类：object

Bucket的生命周期配置。

参数:rules (list of LifecycleRule) – 规则列表。

class oss2.models.BucketLogging(target_bucket, target_prefix)

基类：object

Bucket日志配置信息。

参数:

• target_bucket (str) – 存储日志到这个Bucket。
• target_prefix (str) – 生成的日志文件名加上该前缀。

class oss2.models.BucketReferer(allow_empty_referer, referers)

基类：object

Bucket防盗链设置。

参数:

• allow_empty_referer (bool) – 是否允许空的Referer。
• referers – Referer列表，每个元素是一个str。

class oss2.models.BucketStat(storage_size_in_bytes, object_count, multi_part_upload_count)

基类：object

class oss2.models.BucketWebsite(index_file, error_file)

基类：object

静态网站托管配置。

参数:

• index_file (str) – 索引页面文件
• error_file (str) – 404页面文件

class oss2.models.CorsRule(allowed_origins=None, allowed_methods=None, allowed_headers=None, expose_headers=None, max_age_seconds=None)

基类：object

CORS（跨域资源共享）规则。

参数:

• allowed_origins (list of str) – 允许跨域访问的域。
• allowed_methods (list of str) – 允许跨域访问的HTTP方法，如’GET’等。
• allowed_headers (list of str) – 允许跨域访问的HTTP头部。

class oss2.models.CreateLiveChannelResult(resp)

基类：oss2.models.RequestResult, oss2.models.LiveChannelInfo

class oss2.models.GetBucketAclResult(resp)

基类：oss2.models.RequestResult

acl = None

Bucket的ACL，其值可以是 BUCKET_ACL_PRIVATE、 BUCKET_ACL_PUBLIC_READ 或 BUCKET_ACL_PUBLIC_READ_WRITE 。

class oss2.models.GetBucketCorsResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketCors

class oss2.models.GetBucketInfoResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketInfo

class oss2.models.GetBucketLifecycleResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketLifecycle

class oss2.models.GetBucketLocationResult(resp)

基类：oss2.models.RequestResult

location = None

Bucket所在的数据中心

class oss2.models.GetBucketLoggingResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketLogging

class oss2.models.GetBucketRefererResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketReferer

class oss2.models.GetBucketStatResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketStat

class oss2.models.GetBucketWebsiteResult(resp)

基类：oss2.models.RequestResult, oss2.models.BucketWebsite

class oss2.models.GetLiveChannelHistoryResult(resp)

基类：oss2.models.RequestResult, oss2.models.LiveChannelHistory

class oss2.models.GetLiveChannelResult(resp)

基类：oss2.models.RequestResult, oss2.models.LiveChannelInfo

class oss2.models.GetLiveChannelStatResult(resp)

基类：oss2.models.RequestResult, oss2.models.LiveChannelStat

class oss2.models.GetObjectAclResult(resp)

基类：oss2.models.RequestResult

acl = None

对象的ACL，其值可以是 OBJECT_ACL_DEFAULT、 OBJECT_ACL_PRIVATE、 OBJECT_ACL_PUBLIC_READ 或 OBJECT_ACL_PUBLIC_READ_WRITE

class oss2.models.GetObjectMetaResult(resp)

基类：oss2.models.RequestResult

content_length = None

Content-Length，文件大小，类型为int。

etag = None

HTTP ETag

last_modified = None

文件最后修改时间，类型为int。参考 Unix Time 。

class oss2.models.GetObjectResult(resp, progress_callback=None, crc_enabled=False, crypto_provider=None)

基类：oss2.models.HeadObjectResult

client_crc

read(amt=None)

server_crc

class oss2.models.GetSymlinkResult(resp)

基类：oss2.models.RequestResult

target_key = None

符号连接的目标文件

class oss2.models.HeadObjectResult(resp)

基类：oss2.models.RequestResult

content_length = None

Content-Length，可能是None。

content_type = None

文件的MIME类型

etag = None

HTTP ETag

object_type = None

文件类型，可以是’Normal’、’Multipart’、’Appendable’等

class oss2.models.InitMultipartUploadResult(resp)

基类：oss2.models.RequestResult

upload_id = None

新生成的Upload ID

class oss2.models.LifecycleExpiration(days=None, date=None, created_before_date=None)

基类：object

过期删除操作。

参数:

• days – 表示在文件修改后过了这么多天，就会匹配规则，从而被删除
• date (datetime.date) – 表示在该日期之后，规则就一直生效。即每天都会对符合前缀的文件执行删除操作（如，删除），而不管文件是什么时候生成的。（不建议使用）
• created_before_date – 将最后修改时间早于created_before_date的对象转储。

class oss2.models.LifecycleRule(id, prefix, status='Enabled', expiration=None, abort_multipart_upload=None, storage_transitions=None)

基类：object

生命周期规则。

参数:

• id – 规则名
• prefix – 只有文件名匹配该前缀的文件才适用本规则
• expiration (LifecycleExpiration) – 过期删除操作。
• status – 启用还是禁止该规则。可选值为 LifecycleRule.ENABLED 或 LifecycleRule.DISABLED

DISABLED = 'Disabled'

ENABLED = 'Enabled'

class oss2.models.ListBucketsResult(resp)

基类：oss2.models.RequestResult

buckets = None

得到的Bucket列表，类型为 SimplifiedBucketInfo 。

is_truncated = None

True表示还有更多的Bucket可以罗列；False表示已经列举完毕。

next_marker = None

下一次罗列的分页标记符，即，可以作为 list_buckets 的 marker 参数。

class oss2.models.ListLiveChannelResult(resp)

基类：oss2.models.RequestResult, oss2.models.LiveChannelList

class oss2.models.ListMultipartUploadsResult(resp)

基类：oss2.models.RequestResult

is_truncated = None

True表示还有更多的为完成分片上传可以罗列；False表示已经列举完毕。

next_key_marker = None

文件名分页符

next_upload_id_marker = None

分片上传ID分页符

prefix_list = None

公共前缀列表。类型为str列表。

upload_list = None

分片上传列表。类型为 MultipartUploadInfo 列表。

class oss2.models.ListObjectsResult(resp)

基类：oss2.models.RequestResult

is_truncated = None

True表示还有更多的文件可以罗列；False表示已经列举完毕。

next_marker = None

下一次罗列的分页标记符，即，可以作为 list_objects 的 marker 参数。

object_list = None

本次罗列得到的文件列表。其中元素的类型为 SimplifiedObjectInfo 。

prefix_list = None

本次罗列得到的公共前缀列表，类型为str列表。

class oss2.models.ListPartsResult(resp)

基类：oss2.models.RequestResult

class oss2.models.LiveChannelAudioStat(codec='', sample_rate=0, bandwidth=0)

基类：object

LiveStat中的Audio节点。

参数:

• codec (str) – 编码方式。
• sample_rate (int) – 采样率。
• bandwidth (int) – 码率。

class oss2.models.LiveChannelHistory

基类：object

直播频道下的推流记录。

class oss2.models.LiveChannelInfo(status='enabled', description='', last_modified=None, name=None, play_url=None, publish_url=None)

基类：object

Live channel（直播频道）配置。

参数:

• status (str) – 直播频道的状态，合法的值为’enabled’和’disabled’ 。
• description (str) – 直播频道的描述信息，最长为128字节。
• target (LiveChannelInfoTarget) – 直播频道的推流目标节点，包含目标协议相关的参数。
• last_modified (Last modified time in unix time (int type), See Unix Time.) – 直播频道的最后修改时间，这个字段仅在 ListLiveChannel 时使用。
• name (str) – 创建推流直播频道。
• play_url (str) – 播放地址。
• publish_url (str) – 推流地址。

class oss2.models.LiveChannelInfoTarget(type='HLS', frag_duration=5, frag_count=3, playlist_name='')

基类：object

Live channel中的Target节点，包含目标协议的一些参数。

参数:

• type (str) – 协议，目前仅支持HLS。
• frag_duration (int) – HLS协议下生成的ts文件的期望时长，单位为秒。
• frag_count (int) – HLS协议下m3u8文件里ts文件的数量。

class oss2.models.LiveChannelList(prefix='', marker='', max_keys=100, is_truncated=False, next_marker='')

基类：object

List直播频道的结果。

参数:

• prefix (str) – List直播频道使用的前缀。
• marker (str) – List直播频道使用的marker。
• max_keys (int) – 一次罗列最多能够返回的条目数。
• is_truncated (bool) – 本次List是否列举完所有的直播频道
• next_marker – 下一次List直播频道使用的marker。
• channels (list of LiveChannelInfo) – List返回的直播频道列表

class oss2.models.LiveChannelStat(status='', remote_addr='', connected_time='', video=None, audio=None)

基类：object

LiveStat结果。

参数:

• status – 直播状态。
• remote_addr (str) – 客户端的地址。
• connected_time (int, unix time) – 本次推流开始时间。
• video (LiveChannelVideoStat) – 视频描述信息。
• audio (LiveChannelAudioStat) – 音频描述信息。

class oss2.models.LiveChannelVideoStat(width=0, height=0, frame_rate=0, codec='', bandwidth=0)

基类：object

LiveStat中的Video节点。

参数:

• width (int) – 视频的宽度。
• height (int) – 视频的高度。
• frame_rate (int) – 帧率。
• codec (str) – 编码方式。
• bandwidth (int) – 码率。

class oss2.models.LiveRecord(start_time='', end_time='', remote_addr='')

基类：object

直播频道中的推流记录信息

参数:

• start_time (int, see Unix Time.) – 本次推流开始时间。
• end_time (int, see Unix Time for more information.) – 本次推流结束时间。
• remote_addr (str) – 推流时客户端的地址。

class oss2.models.MultipartUploadInfo(key, upload_id, initiation_date)

基类：object

initiation_date = None

分片上传初始化的时间，类型为int。参考 Unix Time

is_prefix()

如果是公共前缀则返回True

key = None

文件名

upload_id = None

分片上传ID

class oss2.models.Owner(display_name, owner_id)

基类：object

class oss2.models.PartInfo(part_number, etag, size=None, last_modified=None)

基类：object

表示分片信息的文件。

该文件既用于 list_parts 的输出，也用于 complete_multipart_upload 的输入。

参数:

• part_number (int) – 分片号
• etag (str) – 分片的ETag
• size (int) – 分片的大小。仅用在 list_parts 的结果里。
• last_modified (int) – 该分片最后修改的时间戳，类型为int。参考 Unix Time 。

class oss2.models.PutObjectResult(resp)

基类：oss2.models.RequestResult

crc = None

文件上传后，OSS上文件的CRC64值。

etag = None

HTTP ETag

class oss2.models.RequestResult(resp)

基类：object

headers = None

HTTP头部

request_id = None

请求ID，用于跟踪一个OSS请求。提交工单时，最后能够提供请求ID。

resp = None

HTTP响应

status = None

HTTP状态码

class oss2.models.SimplifiedBucketInfo(name, location, creation_date)

基类：object

list_buckets 结果中的单个元素类型。

creation_date = None

Bucket的创建时间，类型为int。参考 Unix Time。

location = None

Bucket的区域

name = None

Bucket

class oss2.models.SimplifiedObjectInfo(key, last_modified, etag, type, size, storage_class)

基类：object

etag = None

HTTP ETag

is_prefix()

It returns True if it is a common prefix(folder). Otherwise it returns False.

key = None

文件名，或公共前缀名。

last_modified = None

文件的最后修改时间

size = None

文件大小

storage_class = None

文件的存储类别，是一个字符串。

type = None

文件类型

class oss2.models.StorageTransition(days=None, created_before_date=None, storage_class=None)

基类：object

转储对象

参数:

• days – 将相对最后修改时间days天之后的Object转储。
• created_before_date – 将最后修改时间早于created_before_date的对象转储
• storage_class – 对象转储到OSS的目标存储类型

oss2.resumable module

oss2.resumable

该模块包含了断点续传相关的函数和类。

class oss2.resumable.ResumableDownloadStore(root=None, dir=None)

基类：oss2.resumable._ResumableStoreBase

保存断点下载断点信息的类。

每次下载的断点信息会保存在 root/dir/ 下面的某个文件里。

参数:

• root (str) – 父目录，缺省为 HOME 。
• dir (str) – 子目录，缺省为 _DOWNLOAD_TEMP_DIR

static make_store_key(bucket_name, key, filename)

class oss2.resumable.ResumableStore(root=None, dir=None)

基类：oss2.resumable._ResumableStoreBase

保存断点上传断点信息的类。

每次上传的信息会保存在 root/dir/ 下面的某个文件里。

参数:

• root (str) – 父目录，缺省为 HOME 。
• dir (str) – 子目录，缺省为 _UPLOAD_TEMP_DIR

static make_store_key(bucket_name, key, filename)

oss2.resumable.determine_part_size(total_size, preferred_size=None)

确定分片上传是分片的大小。

参数:

• total_size (int) – 总共需要上传的长度
• preferred_size (int) – 用户期望的分片大小。 如果不指定则采用defaults.part_size 。

返回:

分片大小

oss2.resumable.make_download_store(root=None, dir=None)

oss2.resumable.make_upload_store(root=None, dir=None)

oss2.resumable.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 ）。

During a download, the checkpoint information (finished range) is stored in the disk as a checkpoint file.

在上述过程中，断点信息，即已经完成的范围，会保存在磁盘上。因为某种原因下载中断，后续如果下载同样的文件，也就是源文件和目标文件一样，就会先读取断点信息，然后只下载缺失的部分。

缺省设置下，断点信息保存在 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) – 用来保存断点信息的持久存储，比如可以指定断点信息所在的目录。

Raises:

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

oss2.resumable.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 – 文件上传后，OSS上文件的CRC64值。
• store – Upload progress information storage. ResumableStore is used if not specified. See ResumableStore for more information.
• headers – 传给 put_object 或 init_multipart_upload 的HTTP头部。
• multipart_threshold – 确定分片上传是分片的大小。
• part_size – 指定分片上传的每个分片的大小。如不指定，则自动计算。
• progress_callback – 上传进度回调函数。参见 上传下载进度 。
• num_threads – 并发上传的线程数，如不指定则使用 oss2.defaults.multipart_num_threads 。

oss2.task_queue module

class oss2.task_queue.TaskQueue(producer, consumers)

基类：object

get()

ok()

put(data)

run()

oss2.utils module

oss2.utils

工具函数模块。

class oss2.utils.AESCipher(key=None, start=None)

AES256 加密实现。

参数:

• key (str) – 对称加密数据密钥
• start (str) – 对称加密初始随机值

注解

用户可自行实现对称加密算法，需服务如下规则：1、提供对称加密算法名，ALGORITHM ；2、提供静态方法，返回加密密钥和初始随机值（若算法不需要初始随机值，也需要提供）； 3、提供加密解密方法。

ALGORITHM = 'AES/GCM/NoPadding'

decrypt(enc)

encrypt(raw)

static get_key()

static get_start()

class oss2.utils.Crc64(init_crc=0)

基类：object

crc

update(data)

class oss2.utils.SizedFileAdapter(file_object, size)

基类：object

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

len

read(amt=None)

oss2.utils.b64decode_from_string(data)

oss2.utils.b64encode_as_string(data)

oss2.utils.check_crc(operation, client_crc, oss_crc, request_id)

oss2.utils.content_md5(data)

计算data的MD5值，经过Base64编码并返回str类型。

返回值可以直接作为HTTP Content-Type头部的值。

oss2.utils.content_type_by_name(name)

根据文件名，返回Content-Type。

oss2.utils.copyfileobj_and_verify(fsrc, fdst, expected_len, chunk_size=16384, request_id='')

从file-like对象fsrc拷贝数据到file-like对象fdst， 并且验证长度。

oss2.utils.date_to_iso8601(d)

oss2.utils.file_object_remaining_bytes(fileobj)

oss2.utils.force_rename(src, dst)

oss2.utils.how_many(m, n)

oss2.utils.http_date(timeval=None)

返回符合HTTP标准的GMT时间字符串，用strftime的格式表示就是’%a, %d %b %Y %H:%M:%S GMT’ 。但不能使用strftime，因为strftime的结果是和locale相关的。

oss2.utils.http_to_unixtime(time_string)

把HTTP Date格式的字符串转换为UNIX时间（自1970年1月1日UTC零点的秒数）。

HTTP Date形如 Sat, 05 Dec 2015 11:10:29 GMT 。

oss2.utils.is_ip_or_localhost(netloc)

判断网络地址是否为IP或localhost。

oss2.utils.is_valid_bucket_name(name)

判断是否为合法的Bucket名

oss2.utils.iso8601_to_date(time_string)

oss2.utils.iso8601_to_unixtime(time_string)

把ISO8601时间字符串（形如，2012-02-24T06:07:48.000Z）转换为UNIX时间，精确到秒。

oss2.utils.make_cipher_adapter(data, cipher_callback)

返回一个适配器，从而在读取 data ，即调用read或者对其进行迭代的时候，能够进行加解密操作。

参数:

• data – 可以是bytes、file object或iterable。
• operation – 进行加密或解密操作。
• key – 对称加密中的密码，长度必须为16/24/32 bytes。
• start – 计数器初始值。

返回:

能够客户端加密函数的适配器。

oss2.utils.make_crc_adapter(data, init_crc=0)

返回一个适配器，从而在读取 data ，即调用read或者对其进行迭代的时候，能够计算CRC。

参数:

• data – 可以是bytes、file object或iterable。
• init_crc – 初始CRC值，可选。

返回:

能够调用计算CRC函数的适配器。

oss2.utils.make_progress_adapter(data, progress_callback, size=None)

返回一个适配器，从而在读取 data ，即调用read或者对其进行迭代的时候，能够调用进度回调函数。

当 size 没有指定，且无法确定时，上传回调函数返回的总字节数为None。

参数:

• data – 可以是bytes、file object或iterable。
• progress_callback – 上传进度回调函数。参见 上传下载进度 。
• size – 指定 data 的大小，可选

返回:

能够调用进度回调函数的适配器

oss2.utils.makedir_p(dirpath)

oss2.utils.md5_string(data)

返回 data 的MD5值，以十六进制可读字符串（32个小写字符）的方式。

oss2.utils.random_aes256_key()

oss2.utils.random_counter(begin=1, end=10)

oss2.utils.set_content_type(headers, name)

根据文件名在headers里设置Content-Type。如果headers中已经存在Content-Type，则直接返回。

oss2.utils.silently_remove(filename)

删除文件，如果文件不存在也不报错。

oss2.utils.to_unixtime(time_string, format_string)

oss2.xml_utils module

oss2.xml_utils

XML处理相关。

主要包括两类接口：

• parse_开头的函数：用来解析服务器端返回的XML
• to_开头的函数：用来生成发往服务器端的XML

oss2.xml_utils.parse_batch_delete_objects(result, body)

oss2.xml_utils.parse_create_live_channel(result, body)

oss2.xml_utils.parse_get_bucket_acl(result, body)

oss2.xml_utils.parse_get_bucket_cors(result, body)

oss2.xml_utils.parse_get_bucket_info(result, body)

oss2.xml_utils.parse_get_bucket_lifecycle(result, body)

oss2.xml_utils.parse_get_bucket_location(result, body)

oss2.xml_utils.parse_get_bucket_logging(result, body)

oss2.xml_utils.parse_get_bucket_referer(result, body)

oss2.xml_utils.parse_get_bucket_stat(result, body)

oss2.xml_utils.parse_get_bucket_websiste(result, body)

oss2.xml_utils.parse_get_live_channel(result, body)

oss2.xml_utils.parse_get_object_acl(result, body)

oss2.xml_utils.parse_init_multipart_upload(result, body)

oss2.xml_utils.parse_lifecycle_abort_multipart_upload(abort_multipart_upload_node)

oss2.xml_utils.parse_lifecycle_expiration(expiration_node)

oss2.xml_utils.parse_lifecycle_storage_transitions(storage_transition_nodes)

oss2.xml_utils.parse_list_buckets(result, body)

oss2.xml_utils.parse_list_live_channel(result, body)

oss2.xml_utils.parse_list_multipart_uploads(result, body)

oss2.xml_utils.parse_list_objects(result, body)

oss2.xml_utils.parse_list_parts(result, body)

oss2.xml_utils.parse_live_channel_history(result, body)

oss2.xml_utils.parse_live_channel_stat(result, body)

oss2.xml_utils.parse_stat_audio(audio_node, audio)

oss2.xml_utils.parse_stat_video(video_node, video)

oss2.xml_utils.to_batch_delete_objects_request(keys, quiet)

oss2.xml_utils.to_complete_upload_request(parts)

oss2.xml_utils.to_create_live_channel(live_channel)

oss2.xml_utils.to_put_bucket_config(bucket_config)

oss2.xml_utils.to_put_bucket_cors(bucket_cors)

oss2.xml_utils.to_put_bucket_lifecycle(bucket_lifecycle)

oss2.xml_utils.to_put_bucket_logging(bucket_logging)

oss2.xml_utils.to_put_bucket_referer(bucket_referer)

oss2.xml_utils.to_put_bucket_website(bucket_websiste)

Module contents