Download and Installation
Relevant resources
Note
If you encounter errors such as non-existent functions or methods when using the XML version of the SDK, please update the SDK to the latest version and try again.
Environmental dependencies
Currently, COS’s XML Python SDK supports Python 2.7, Python 3.4, and later.
Note
For the definitions of parameters such as SecretId, SecretKey, Bucket, and Region, see COS’s Glossary. Installing SDK
You can install the SDK in three ways: installation via pip, manual installation, and offline installation.
Installing via pip (recommended)
pip install -U cos-python-sdk-v5
Manual installation
Download the source code here and install the SDK manually via setup by running the following command: Offline installation
mkdir cos-python-sdk-packages
pip download cos-python-sdk-v5 -d cos-python-sdk-packages
tar -czvf cos-python-sdk-packages.tar.gz cos-python-sdk-packages
tar -xzvf cos-python-sdk-packages.tar.gz
pip install cos-python-sdk-v5 --no-index -f cos-python-sdk-packages
Directions
The section below describes how to use the COS SDK for Python to perform basic operations, such as initializing a client, creating a bucket, querying the bucket list, uploading an object, querying the object list, downloading an object, and deleting an object.
Initialization
You can initialize the Python SDK Client in the following ways as needed:
Initializing with the COS default domain (default)
If you use the COS default domain to access COS, the SDK will access COS using a domain name formatted as {bucket-appid}.cos.{region}.myqcloud.com.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
Notes
Usually, you only need to generate one CosS3Client instance for a region, and can upload/download objects repeatedly. Do not generate a CosS3Client instance for every access. Otherwise, the Python process will occupy too many connections and threads.
Initializing with the COS default domain and proxy
Configure this part when you need to access COS with a proxy. Otherwise, skip this part.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
proxies = {
'http': '127.0.0.1:80',
'https': '127.0.0.1:443'
}
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Proxies=proxies)
client = CosS3Client(config)
Initializing with the COS acceleration domain
If you use the COS global acceleration domain to access COS, the SDK will access COS using a domain name formatted as {bucket-appid}.cos.accelerate.myqcloud.com. region will not appear in the domain name.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = None
token = None
scheme = 'https'
endpoint = 'cos.accelerate.myqcloud.com'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Endpoint=endpoint, Scheme=scheme)
client = CosS3Client(config)
Initializing with a custom domain
If you use a custom domain to access COS, the SDK will directly access COS using the user domain configured. Neither bucket nor region will appear in the domain name.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = None
token = None
scheme = 'https'
domain = 'user-define.example.com'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Domain=domain, Scheme=scheme)
client = CosS3Client(config)
Initializing with the CDN default domain
If you use the CDN default domain to access COS, the SDK will access CDN using a domain formatted as {bucket-appid}.file.mycloud.com and then access COS via the CDN origin server.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = None
token = None
scheme = 'https'
endpoint = 'file.mycloud.com'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Endpoint=endpoint, Scheme=scheme)
client = CosS3Client(config)
Initializing with a CDN custom domain
If you use a CDN custom domain to access COS, the SDK will directly access CDN using the user domain configured (neither bucket nor region will appear in the domain name) and then access COS via CDN origin server.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = None
token = None
scheme = 'https'
domain = 'user-define.example-cdn.com'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Domain=domain, Scheme=scheme)
client = CosS3Client(config)
Creating a bucket
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
response = client.create_bucket(
Bucket='examplebucket-1250000000'
)
Querying the bucket list
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
response = client.list_buckets(
)
Uploading an object
Note
Simple upload cannot be used to upload files larger than 5 GB. You can use the advanced upload API to upload large files. For more information about the related parameters, see Object Operations.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
with open('picture.jpg', 'rb') as fp:
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=fp,
Key='picture.jpg',
StorageClass='STANDARD',
EnableMD5=False
)
print(response['ETag'])
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=b'bytes',
Key='picture.jpg',
EnableMD5=False
)
print(response['ETag'])
import requests
stream = requests.get('https://cloud.tencent.com/document/product/436/7778')
response = client.put_object(
Bucket='examplebucket-1250000000',
Body=stream,
Key='picture.jpg'
)
print(response['ETag'])
response = client.upload_file(
Bucket='examplebucket-1250000000',
LocalFilePath='local.txt',
Key='picture.jpg',
PartSize=1,
MAXThread=10,
EnableMD5=False
)
print(response['ETag'])
Querying objects
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
response = client.list_objects(
Bucket='examplebucket-1250000000',
Prefix='folder1'
)
A single call to the list_objects API can query up to 1,000 objects. If you want to query all objects, you need to call it repeatedly.
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
marker = ""
while True:
response = client.list_objects(
Bucket='examplebucket-1250000000',
Prefix='folder1',
Marker=marker
)
print(response['Contents'])
if response['IsTruncated'] == 'false':
break
marker = response['NextMarker']
Downloading an object
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
response = client.get_object(
Bucket='examplebucket-1250000000',
Key='picture.jpg',
)
response['Body'].get_stream_to_file('output.txt')
response = client.get_object(
Bucket='examplebucket-1250000000',
Key='picture.jpg',
)
fp = response['Body'].get_raw_stream()
print(fp.read(2))
response = client.get_object(
Bucket='examplebucket-1250000000',
Key='picture.jpg',
ResponseContentType='text/html; charset=utf-8'
)
print(response['Content-Type'])
fp = response['Body'].get_raw_stream()
print(fp.read(2))
response = client.get_object(
Bucket='examplebucket-1250000000',
Key='picture.jpg',
Range='bytes=0-10'
)
fp = response['Body'].get_raw_stream()
print(fp.read())
Deleting an object
from qcloud_cos import CosConfig
from qcloud_cos import CosS3Client
import sys
import logging
logging.basicConfig(level=logging.INFO, stream=sys.stdout)
secret_id = 'SecretId'
secret_key = 'SecretKey'
region = 'ap-beijing'
token = None
scheme = 'https'
config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
client = CosS3Client(config)
response = client.delete_object(
Bucket='examplebucket-1250000000',
Key='exampleobject'
)
response = client.delete_objects(
Bucket='examplebucket-1250000000',
Delete={
'Object': [
{
'Key': 'exampleobject1',
},
{
'Key': 'exampleobject2',
},
],
'Quiet': 'true'|'false'
}
)
