Getting Started

Last updated: 2020-12-21 10:38:08

    Download and Installation

    Relevant resources

    • Download the COS XML SDK for Python source code here.
    • Download the XML SDK for Python here.
    • Download the demo here.
    • Find the complete sample code here.
    • For the SDK changelog, please see Changelog.

    Environmental dependency

    COS XML SDK for Python currently supports Python 2.7, 3.4, and above.

    Note:

    For the definitions of parameters such as SecretId, SecretKey, Bucket, and Region, please see COS Glossary.

    Installing SDK

    You can install the SDK in three ways: installation through pip, manual installation, and offline installation.

    • Installing through pip (recommended)

      pip install -U cos-python-sdk-v5
    • Manual installation
      Download the source code here and install the SDK manually through setup by running the following command.

      python setup.py install
    • Offline installation

      # Run the following commands on a computer connected to the Internet.
      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
      # Copy the installation package to a computer that is not connected to the Internet and run the following commands.
      # Please make sure that the version of Python on the two computers is the same; otherwise, the installation will fail.
      tar -xzvf cos-python-sdk-packages.tar.gz
      pip install cos-python-sdk-v5 --no-index -f cos-python-sdk-packages

    Getting Started

    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

    Please see the following sample code:

    # -*- coding=utf-8
    # APPID has been removed from the configuration. Please add the APPID to the Bucket parameter in the format of BucketName-APPID.
    # 1. Set user configuration, including secretId, secretKey, and region.
    from qcloud_cos import CosConfig
    from qcloud_cos import CosS3Client
    import sys
    import logging
    
    logging.basicConfig(level=logging.INFO, stream=sys.stdout)
    
    secret_id = 'COS_SECRETID'      # Replace with your secretId.
    secret_key = 'COS_SECRETKEY'      # Replace with your secretKey.
    region = 'COS_REGION'     # Replace with your region.
    token = None                # If a temporary key is used, token needs to be passed in. This is optional and is left empty by default.
    scheme = 'https'            # Specify whether to use HTTP or HTTPS protocol to access COS. This is optional and is https by default.
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Token=token, Scheme=scheme)
    # 2. Get the client object.
    client = CosS3Client(config)
    # Refer to the description below or the demo. For more information, please visit https://github.com/tencentyun/cos-python-sdk-v5/blob/master/qcloud_cos/demo.py.

    Setting proxy:

    # APPID has been removed from the configuration. Please add the APPID to the Bucket parameter in the format of BucketName-APPID.
    # 1. Set user configuration, including secretId, secretKey, and region.
    secret_id = 'COS_SECRETID'      # Replace with your secretId.
    secret_key = 'COS_SECRETKEY'      # Replace with your secretKey.
    region = 'COS_REGION'     # Replace with your region.
    proxies = {
        'http': '127.0.0.1:80' # Replace with your HTTP Proxy IP.
        'https': '127.0.0.1:443' # Replace with your HTTPS Proxy IP.
    }
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Proxies=proxies)
    # 2. Get the client object
    client = CosS3Client(config)
    # Refer to the description below or the demo. For more information, please visit https://github.com/tencentyun/cos-python-sdk-v5/blob/master/qcloud_cos/demo.py.

    Set the endpoint:

    # APPID has been removed from the configuration. Please add the APPID to the Bucket parameter in the format of BucketName-APPID.
    # 1. Set user configuration, including secretId, secretKey, and region.
    secret_id = 'COS_SECRETID'      # Replace with your secretId.
    secret_key = 'COS_SECRETKEY'      # Replace with your secretKey.
    region = 'COS_REGION'     # Replace with your region.
    endpoint = 'cos.accelerate.myqcloud.com' # Replace with your endpoint.
    config = CosConfig(Region=region, SecretId=secret_id, SecretKey=secret_key, Endpoint=endpoint)
    # 2. Get the client object.
    client = CosS3Client(config)
    # Refer to the description below or the demo. For more information, please visit https://github.com/tencentyun/cos-python-sdk-v5/blob/master/qcloud_cos/demo.py.

    Note:

    For more information on how to generate and use a temporary key, please see Generating and Using Temporary Keys.

    Creating bucket

    response = client.create_bucket(
        Bucket='examplebucket-1250000000'
    )

    Querying bucket list

    response = client.list_buckets(
    )

    Uploading object

    Note:

    Simple upload cannot be used to upload files larger than 5 GB. For files larger than 5 GB, please use the advanced upload API described below. For parameter descriptions, please see Object Operations.

    #### Upload a file stream with simple upload (which cannot be used to upload files larger than 5 GB. For files larger than 5 GB, please use the advanced upload API described below).
    # We strongly recommend you open the file in binary mode; otherwise, an error may occur.
    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'])
    
    #### Uploading byte stream with simple upload
    response = client.put_object(
        Bucket='examplebucket-1250000000',
        Body=b'bytes',
        Key='picture.jpg',
        EnableMD5=False
    )
    print(response['ETag'])
    
    
    #### Simple chunk upload
    import requests
    stream = requests.get('https://intl.cloud.tencent.com/document/product/436/7778?from_cn_redirect=1')
    
    # Online streams will be transferred to COS in the Transfer-Encoding:chunked manner.
    response = client.put_object(
        Bucket='examplebucket-1250000000',
        Body=stream,
        Key='picture.jpg'
    )
    print(response['ETag'])
    
    #### Advanced upload API (recommended)
    # This API can automatically select between simple upload and multipart upload based on the file size. Multipart upload supports the checkpoint restart feature.
    response = client.upload_file(
        Bucket='examplebucket-1250000000',
        LocalFilePath='local.txt',
        Key='picture.jpg',
        PartSize=1,
        MAXThread=10,
        EnableMD5=False
    )
    print(response['ETag'])

    Querying object list

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

    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 object

    #### Downloading object to local file system
    response = client.get_object(
        Bucket='examplebucket-1250000000',
        Key='picture.jpg',
    )
    response['Body'].get_stream_to_file('output.txt')
    
    #### Downloading file stream
    response = client.get_object(
        Bucket='examplebucket-1250000000',
        Key='picture.jpg',
    )
    fp = response['Body'].get_raw_stream()
    print(fp.read(2))
    
    #### Setting response HTTP headers
    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))
    
    #### Specifying download range
    response = client.get_object(
        Bucket='examplebucket-1250000000',
        Key='picture.jpg',
        Range='bytes=0-10'
    )
    fp = response['Body'].get_raw_stream()
    print(fp.read())

    Deleting object

    # Delete one object
    ## deleteObject
    response = client.delete_object(
        Bucket='examplebucket-1250000000',
        Key='exampleobject'
    )
    
    # Delete multiple objects
    ## deleteObjects
    response = client.delete_objects(
        Bucket='examplebucket-1250000000',
        Delete={
            'Object': [
                {
                    'Key': 'exampleobject1',
                },
                {
                    'Key': 'exampleobject2',
                },
            ],
            'Quiet': 'true'|'false'
        }
    )

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help