oss2 package ¶

put_object_acl(key, permission)[source]¶

Set the object ACL.

Parameters:	key (str) – The object name permission (str) – The valid values are oss2.OBJECT_ACL_DEFAULT,oss2.OBJECT_ACL_PRIVATE,oss2.OBJECT_ACL_PUBLIC_READ or oss2.OBJECT_ACL_PUBLIC_READ_WRITE.
Returns:	`RequestResult`

put_object_from_file(key, filename, headers=None, progress_callback=None)[source]¶

Upload a normal local file to OSS.

Parameters:

key (str) – The object name in oss.
filename (str) – The local file path with the read permission.
headers (dict or oss2.CaseInsensitiveDict(recommended)) – The HTTP headers. It could be content-type, Content-MD5 or x-oss-meta- prefixed headers.
progress_callback – The user’s callback. Typical usage is progress bar. See Upload or Download Progress for more information.

Returns:

put_symlink(target_key, symlink_key, headers=None)[source]¶

Create a symbolic file.

Parameters:	target_key (str) – Target file, which cannot be another symbolic file. symlink_key (str) – The symbolic file name. It is a special file whose content points to the target key.
Returns:	`RequestResult`

restore_object(key)[source]¶

Restore an object:

If the interface is invoked for the first time for the object, it returns RequestResult.status = 202 . If the restore interface has been successfully invoked and the service-side is still unfrozen, the exception RestoreAlreadyInProgress(status=409) will be thrown. If the restore interface has been successfully invoked and the server-side thawing has been completed, it returns RequestResult.status = 200 when the interface is invoked again, and the object can be downloaded If object does not exist, the exception NoSuchKey (status=404) is thrown. If you invoke the restore interface for non Archive type Object, the exception OperationNotSupported (status=400) is thrown. You can also get the meta data by calling the head_object interface to determine whether you can restore, or to check the status of a restore.
Usage:
>>> 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

Parameters:	key (str) – The object name
Returns:	`RequestResult`

sign_rtmp_url(channel_name, playlist_name, expires)[source]¶

Sign RTMP pushed streaming URL.

It is used to push the RTMP streaming to OSS for trusted user who has the URL.

Parameters:	channel_name – The live channel name expires – Expiration time in seconds.The URL is invalid after it expires. playlist_name – Playlist name. It should be the one created in live channel creation time. params – HTTP query parameters to sign.
Returns:	Signed URL.

sign_url(method, key, expires, headers=None, params=None)[source]¶

Generate the presigned URL.

The signed URL can be used to access the object by any user who has the URL. For example, in the code below, it generates the signed URL with 5 minutes TTL for log.jpg file:

>>> 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'

Parameters:

method (str) – HTTP method such as ‘GET’, ‘PUT’, ‘DELETE’, and so on.
key – The object key.
expires – Expiration time in seconds. The URL is invalid after it expires.
headers (dict or oss2.CaseInsensitiveDict(recommended)) – The HTTP headers to sign. For example, the headers starting with x-oss-meta- (user’s custom metadata), Content-Type, and so on. There is no need to download them.
params – HTTP query parameters to sign

Returns:

Signed URL.

update_object_meta(key, headers)[source]¶

Update Object’s metadata information, including HTTP standard headers such as Content-Type or x-oss-meta- prefixed custom metadata. If user specifies invalid headers, for example non-standard headers or non x-oss-meta- headers, the call would still succeed but no operation is done on the server side.

User could call head_object() to get the updated information. Note that get_object_meta does return all metadata, but head_object does.

Parameters:	key (str) – object key headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers
Returns:	`RequestResult`

upload_part(key, upload_id, part_number, data, progress_callback=None, headers=None)[source]¶

Upload a part.

Parameters:

key (str) – The object key to upload. It must be the same as the one in init_multipart_upload().
upload_id (str) – The multipart upload ID
part_number (int) – The part number, starting with 1.
data – Data to upload
progress_callback – The the progress callback function specified by the user. Can be used to implement progress bars and other functions. See Upload or Download Progress for more information.
headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers, such as Content-MD5 .

Returns:

upload_part_copy(source_bucket_name, source_key, byte_range, target_key, target_upload_id, target_part_number, headers=None)[source]¶

Uploads a part from another object. Copy part or the whole of an existing file into a slice of the target file.

Parameters:	byte_range – The range to copy in the source file Download range headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers
Returns:	`PutObjectResult`

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

Class to encrypt the operation of Bucket and Object, such as upload/download object. Create/Delete bucket operations need to use the interface of Class Bucket.

Usage (Suppose Bucket belongs to the Hangzhou region):

>>> 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>

Parameters:

auth (oss2.Auth) – It is an oss2.Auth object containing access-key-id and access-key-secret.
endpoint (str) – Domain name of endpoint or the CName.
bucket_name (str) – Bucket name.
crypto_provider (oss2.crypto.LocalRsaProvider) – The client encryption class, The parameter is empty by default.
is_cname (bool) – True if the endpoint is CNAME. Otherwise, it is False.
session (oss2.Session) – Session instance. None for creating a new session, if it is not None it will resuse the session.
connect_timeout (float) – Connection timeout in seconds.
app_name (str) – App name. If it is not empty, it is appended in User Agent. Note that this value will be part of the HTTP Header value and thus must follow http protocol’s format.
enable_crc (bool) – True if you want to enable the CRC check. Otherwise it is False.

get_object(key, headers=None, progress_callback=None, params=None)[source]¶

Download a file.

Usage:

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

Parameters:	key – The object name in OSS. headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers. progress_callback – User callback. See Upload or Download Progress for more information.
Returns:	The file-like object.
Raises:	If the file does not exist, `NoSuchKey` is thrown. Other exceptions may also be thrown.

get_object_to_file(key, filename, headers=None, progress_callback=None, params=None)[source]¶

Download a file to the local folder.

Parameters:

key – The object name in OSS.
filename – Local file name. The folder of the file must be available for write and must be pre-existing.
headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers
progress_callback – User callback. See Upload or Download Progress for more information.
process – OSS file process, for example, image processing. The process is applied to the returned object.

Returns:

If the file does not exist, NoSuchKey is thrown. Other exceptions may also be thrown.

put_object(key, data, headers=None, progress_callback=None)[source]¶

Upload a normal file.

Usage:

>>> 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)

Parameters:

key – The object name in OSS.
data (bytes, str or file-like object) – The content for upload.
headers (dict or oss2.CaseInsensitiveDict(recommended)) – HTTP headers. It can be content-type, Content-MD5 or x-oss-meta- prefixed headers.
progress_callback – The user’s callback. Typical usage is the progress bar. See Upload or Download Progress for more information.

Returns:

put_object_from_file(key, filename, headers=None, progress_callback=None)[source]¶

Upload a normal object from a local file to OSS.

Parameters:

key (str) – The object name in OSS.
filename (str) – Local file path, called needs the read permission.
headers (dict, but recommendation is oss2.CaseInsensitiveDict) – HTTP headers. It could be content-type, Content-MD5 or x-oss-meta- prefixed headers.
progress_callback – The user’s callback. A typical usage is the progress bar. See Upload or Download Progress for more information.

Returns:

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

Bases: oss2.api._Base

The class for interacting with Service related operations, such as listing all buckets.

Usage:

>>> 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>

Parameters:

auth (oss2.Auth) – The auth instance that contains access-key-id and access-key-secret.
endpoint (str) – The endpoint domain, such as ‘oss-cn-hangzhou.aliyuncs.com’.
session (oss2.Session) – The session instance. If specified as None, a new session is used. Otherwise, it will reuse the previous session.
connect_timeout (float) – The connection timeout in seconds.
app_name (str) – App name. If this is not empty, it will be appended in the User Agent header. Note that this value will be a part of the HTTP Header value and thus must follow http protocol’s format.

list_buckets(prefix='', marker='', max_keys=100)[source]¶

List buckets by prefix

Parameters:	prefix (str) – List buckets with the prefix. List all buckets if it’s empty. marker (str) – The paging maker. It’s empty for first page and then use next_marker in the response of the previous page. max_keys (int) – Max bucket count to return.
Returns:	The bucket list
Return type:	`ListBucketsResult`

oss2.auth module¶

class oss2.auth.AnonymousAuth[source]¶

Bases: object

Anonymous Auth

Note

Anonymous users can only read buckets with public-read permissions, or read from or write to buckets with public-read-write permissions. They are unable to execute service or bucket related operations, such as listing objects under a bucket.

class oss2.auth.Auth(access_key_id, access_key_secret)[source]¶

Bases: oss2.auth.AuthBase

The first version of the signature. Stores AccessKeyId and AccessKeySecret of the user, and calculates the signature.

class oss2.auth.AuthBase(access_key_id, access_key_secret)[source]¶

Bases: object

Store user’s AccessKeyId,AccessKeySecret information and calcualte the signature.

class oss2.auth.AuthV2(access_key_id, access_key_secret)[source]¶

Bases: oss2.auth.AuthBase

The signature version 2. The differences from version 1 are below : 1. Using the SHA256 algorithm, it has higher security. 2. Parameter calculation contains all HTTP query parameters.

class oss2.auth.StsAuth(access_key_id, access_key_secret, security_token, auth_version='v1')[source]¶

Bases: object

Used for STS authentication. Users can get the AccessKeyID, AccessKeySecret, and SecurityToken from the Alibaba Cloud STS service (https://aliyuncs.com).

Note

The AccessKeyId/Secret and SecurityToken have expiration times. When they are renewed, the STSAuth property of class Bucket instance must be updated with the new credentials.

Parameters:	access_key_id (str) – Temporary AccessKeyId access_key_secret (str) – Temporary AccessKeySecret security_token (str) – Temporary SecurityToken auth_version (str) – The version of the auth needs to be generated, the default value is AUTH_VERSION_1(v1).

oss2.auth.make_auth(access_key_id, access_key_secret, auth_version='v1')[source]¶

oss2.auth.v2_uri_encode(raw_text)[source]¶

oss2.compat module¶

Compatible Python versions

oss2.compat.stringify(input)[source]¶

oss2.compat.to_bytes(data)[source]¶: Covert to UTF-8 encoding if the input is unicode; otherwise return the original data.

oss2.compat.to_string(data)[source]¶: Convert to str object

oss2.compat.to_unicode(data)[source]¶: Convert the input to unicode if it’s utf-8 bytes.

oss2.crypto module¶

oss2.encryption¶

The module contains functions and classes related to client-side encryption and decryption.

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

Bases: oss2.crypto.BaseCryptoProvider

Use the aliyun kms service to encrypt the data key. The detailed description of KMS please refer to https://help.aliyun.com/product/28933.html?spm=a2c4g.11186623.3.1.jlYT4v: This interface is not available if the Python version is less than py3.3. Refer to https://github.com/aliyun/aliyun-openapi-python-sdk/issues/61 for more information.

Parameters:

access_key_id (str) – The access_key_id to visit the KMS key service.
access_key_secret (str) – The access_key_secret to visit the KMS key service.
region (str) – The kms key service region.
cmkey (str) – User master key.
sts_token (str) – The security token which you need to provide if you use temporary AK.
passphrase (str) – Kms key service password.
cipher (class) – Data encryption, default is aes256, currently supports only the default implementation.

build_header(headers=None)[source]¶

decrypt_oss_meta_data(headers, key, conv=<function <lambda>>)[source]¶

get_key()[source]¶

get_start()[source]¶

class oss2.crypto.BaseCryptoProvider(cipher)[source]¶

Bases: object

CryptoProvider base class provides an encryption and decryption adapter for basic data.

make_decrypt_adapter(stream, key, start)[source]¶

make_encrypt_adapter(stream, key, start)[source]¶

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

Bases: oss2.crypto.BaseCryptoProvider

Use the local RSA to encrypt the data key.

Parameters:

dir (str) – The storage path of local RSA public key and private key.
key (str) – The prefix of local RSA public and private key name.
passphrase (str) – The password of local RSA public key and private key.
cipher (class) – Data encryption. It is aes256 by default. Users can achieve their own symmetric encryption algorithm, but need to comply with the AESCipher annotation rules.

PRIV_KEY_FILE = '.private_key.pem'¶

PUB_KEY_FILE = '.public_key.pem'¶

build_header(headers=None)[source]¶

decrypt_oss_meta_data(headers, key, conv=<function <lambda>>)[source]¶

get_key()[source]¶

get_start()[source]¶

oss2.defaults module¶

oss2.defaults¶

Global Default variables.

oss2.defaults.connect_timeout = 60¶: Connection timeout

oss2.defaults.connection_pool_size = 10¶: Connection pool size for each session.

oss2.defaults.get(value, default_value)[source]¶

oss2.defaults.get_logger()[source]¶

oss2.defaults.logger = <logging.RootLogger object>¶: Default Logger

oss2.defaults.multiget_num_threads = 4¶: Default thread count for multipart download (multiget)

oss2.defaults.multiget_part_size = 10485760¶: Default part size in multipart download (multiget)

oss2.defaults.multiget_threshold = 104857600¶: The threshold of file size for using multipart download (multiget) in some APIs.

oss2.defaults.multipart_num_threads = 1¶: Default thread count for multipart upload.

oss2.defaults.multipart_threshold = 10485760¶: The threshold of file size for using multipart upload in some APIs.

oss2.defaults.part_size = 10485760¶: Default part size.

oss2.defaults.request_retries = 3¶: Retry count

oss2.exceptions module¶

oss2.exceptions¶

Exception classes

exception oss2.exceptions.AccessDenied(status, headers, body, details)[source]¶

code = 'AccessDenied'¶

status = 403¶

exception oss2.exceptions.BucketNotEmpty(status, headers, body, details)[source]¶

code = 'BucketNotEmpty'¶

status = 409¶

exception oss2.exceptions.ChannelStillLive(status, headers, body, details)[source]¶

code = 'ChannelStillLive'¶

status = 409¶

exception oss2.exceptions.ClientError(message)[source]¶: Bases: oss2.exceptions.OssError

exception oss2.exceptions.Conflict(status, headers, body, details)[source]¶

code = ''¶

status = 409¶

exception oss2.exceptions.InconsistentError(message, request_id='')[source]¶: Bases: oss2.exceptions.OssError

exception oss2.exceptions.InvalidArgument(status, headers, body, details)[source]¶

code = 'InvalidArgument'¶

status = 400¶

exception oss2.exceptions.InvalidDigest(status, headers, body, details)[source]¶

code = 'InvalidDigest'¶

status = 400¶

exception oss2.exceptions.InvalidObjectName(status, headers, body, details)[source]¶

code = 'InvalidObjectName'¶

status = 400¶

exception oss2.exceptions.InvalidRequest(status, headers, body, details)[source]¶

code = 'InvalidRequest'¶

status = 400¶

exception oss2.exceptions.LiveChannelDisabled(status, headers, body, details)[source]¶

code = 'LiveChannelDisabled'¶

status = 409¶

exception oss2.exceptions.MalformedXml(status, headers, body, details)[source]¶

code = 'MalformedXML'¶

status = 400¶

exception oss2.exceptions.NoSuchBucket(status, headers, body, details)[source]¶

code = 'NoSuchBucket'¶

status = 404¶

exception oss2.exceptions.NoSuchCors(status, headers, body, details)[source]¶

code = 'NoSuchCORSConfiguration'¶

status = 404¶

exception oss2.exceptions.NoSuchKey(status, headers, body, details)[source]¶

code = 'NoSuchKey'¶

status = 404¶

exception oss2.exceptions.NoSuchLifecycle(status, headers, body, details)[source]¶

code = 'NoSuchLifecycle'¶

status = 404¶

exception oss2.exceptions.NoSuchLiveChannel(status, headers, body, details)[source]¶

code = 'NoSuchLiveChannel'¶

status = 404¶

exception oss2.exceptions.NoSuchUpload(status, headers, body, details)[source]¶

code = 'NoSuchUpload'¶

status = 404¶

exception oss2.exceptions.NoSuchWebsite(status, headers, body, details)[source]¶

code = 'NoSuchWebsiteConfiguration'¶

status = 404¶

exception oss2.exceptions.NotFound(status, headers, body, details)[source]¶

code = ''¶

status = 404¶

exception oss2.exceptions.NotModified(status, headers, body, details)[source]¶

code = ''¶

status = 304¶

exception oss2.exceptions.ObjectNotAppendable(status, headers, body, details)[source]¶

code = 'ObjectNotAppendable'¶

status = 409¶

exception oss2.exceptions.OpenApiFormatError(message)[source]¶: Bases: oss2.exceptions.OssError

exception oss2.exceptions.OpenApiServerError(status, request_id, message, error_code)[source]¶: Bases: oss2.exceptions.OssError

exception oss2.exceptions.OperationNotSupported(status, headers, body, details)[source]¶

code = 'OperationNotSupported'¶

status = 400¶

exception oss2.exceptions.OssError(status, headers, body, details)[source]¶

Bases: exceptions.Exception

body = None¶: HTTP response body

code = None¶: OSS error code

details = None¶: The error messages. It is a dict of <string, string>

request_id = None¶: Request ID, which represents a unique OSS request. It is useful when submitting a support ticket.

status = None¶: HTTP Status code (such as 200)

exception oss2.exceptions.PositionNotEqualToLength(status, headers, body, details)[source]¶

code = 'PositionNotEqualToLength'¶

status = 409¶

exception oss2.exceptions.PreconditionFailed(status, headers, body, details)[source]¶

code = 'PreconditionFailed'¶

status = 412¶

exception oss2.exceptions.RequestError(e)[source]¶: Bases: oss2.exceptions.OssError

exception oss2.exceptions.RestoreAlreadyInProgress(status, headers, body, details)[source]¶