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 参数多接受第一种类型的输入。

返回值

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

加密接口 CryptoBucket

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

异常

一般来说Python SDK可能会抛出三种类型的异常,这些异常都继承于 OssError
  • ClientError :由于用户参数错误而引发的异常。
  • ServerError 及其子类:OSS服务器返回非成功的状态码,如4xx或5xx。
  • RequestError :底层requests库抛出的异常,如DNS解析错误,超时等。

当然,Bucket.put_object_from_fileBucket.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_bucketslist_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_iso8601iso8601_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'
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。
  • inputBucketCreateConfig 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响应的头部包含了文件基本元信息,可以通过 GetObjectMetaResultlast_modifiedcontent_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 ;还可能抛出其他异常。

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

参数:symlink_key (str) – 符号连接类文件。
返回:GetSymlinkResult
Raises:如果文件的符号链接不存在,则抛出 NoSuchKey ;还可能抛出其他异常。
head_object(key, headers=None)[源代码]

获取文件元信息。

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

用法:
>>> 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。

参数:inputBucketCors 对象或其他。
put_bucket_lifecycle(input)[源代码]

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

参数:inputBucketLifecycle 对象或其他。
put_bucket_logging(input)[源代码]

设置Bucket的访问日志功能。

参数:inputBucketLogging 对象或其他。
put_bucket_referer(input)[源代码]

为Bucket设置防盗链。

参数:inputBucketReferer 对象或其他。
put_bucket_website(input)[源代码]

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

参数:inputBucketWebsite
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

创建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)。

注解

临时凭证会在一段时间后过期,在此之前需要重新获取临时凭证,并更新 Bucketauth 成员变量为新的 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通信,但是对使用者是透明的。该模块中的 SessionRequestResponse 对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 对象。

参数:
  • serviceService 对象
  • 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 对象。

参数:
  • bucketBucket 对象
  • 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时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象
  • 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时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象
  • 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时,表明是公共前缀(目录)。

参数:
  • bucketBucket 对象
  • 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 对象。

参数:
  • bucketBucket 对象
  • 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_PRIVATEBUCKET_ACL_PUBLIC_READBUCKET_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_DEFAULTOBJECT_ACL_PRIVATEOBJECT_ACL_PUBLIC_READOBJECT_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.ENABLEDLifecycleRule.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_bucketsmarker 参数。

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_objectsmarker 参数。

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,函数会退化为普通下载。
参数:
  • bucketBucket 对象
  • 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,函数会退化为普通上传。
参数:
  • bucketBucket 对象
  • key – 待上传的文件名。
  • filename – 文件上传后,OSS上文件的CRC64值。
  • store – Upload progress information storage. ResumableStore is used if not specified. See ResumableStore for more information.
  • headers – 传给 put_objectinit_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