S3

Client

class S3.Client

A low-level client representing Amazon Simple Storage Service (S3):

import boto3

client = boto3.client('s3')

These are the available methods:

abort_multipart_upload(**kwargs)

Aborts a multipart upload.

To verify that all parts have been removed, so you don't get charged for the part storage, you should call the List Parts operation and ensure the parts list is empty.

Request Syntax

response = client.abort_multipart_upload(
    Bucket='string',
    Key='string',
    UploadId='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • UploadId (string) -- [REQUIRED]
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

can_paginate(operation_name)

Check if an operation can be paginated.

Parameters:operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Returns:True if the operation can be paginated, False otherwise.
complete_multipart_upload(**kwargs)

Completes a multipart upload by assembling previously uploaded parts.

Request Syntax

response = client.complete_multipart_upload(
    Bucket='string',
    Key='string',
    MultipartUpload={
        'Parts': [
            {
                'ETag': 'string',
                'PartNumber': 123
            },
        ]
    },
    UploadId='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • MultipartUpload (dict) --
    • Parts (list) --
      • (dict) --
        • ETag (string) -- Entity tag returned when the part was uploaded.
        • PartNumber (integer) -- Part number that identifies the part. This is a positive integer between 1 and 10,000.
  • UploadId (string) -- [REQUIRED]
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Location': 'string',
    'Bucket': 'string',
    'Key': 'string',
    'Expiration': 'string',
    'ETag': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'VersionId': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Location (string) --
    • Bucket (string) --
    • Key (string) --
    • Expiration (string) -- If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
    • ETag (string) -- Entity tag of the object.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • VersionId (string) -- Version of the object.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

copy_object(**kwargs)

Creates a copy of an object that is already stored in Amazon S3.

Request Syntax

response = client.copy_object(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Bucket='string',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    CopySource='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince=datetime(2015, 1, 1),
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince=datetime(2015, 1, 1),
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Key='string',
    Metadata={
        'string': 'string'
    },
    MetadataDirective='COPY'|'REPLACE',
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    CopySourceSSECustomerAlgorithm='string',
    CopySourceSSECustomerKey='string',
    CopySourceSSECustomerKeyMD5='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Bucket (string) -- [REQUIRED]
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • CopySource (string) -- [REQUIRED] The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
  • CopySourceIfMatch (string) -- Copies the object if its entity tag (ETag) matches the specified tag.
  • CopySourceIfModifiedSince (datetime) -- Copies the object if it has been modified since the specified time.
  • CopySourceIfNoneMatch (string) -- Copies the object if its entity tag (ETag) is different than the specified ETag.
  • CopySourceIfUnmodifiedSince (datetime) -- Copies the object if it hasn't been modified since the specified time.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Key (string) -- [REQUIRED]
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • MetadataDirective (string) -- Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • CopySourceSSECustomerAlgorithm (string) -- Specifies the algorithm to use when decrypting the source object (e.g., AES256).
  • CopySourceSSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
  • CopySourceSSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'CopyObjectResult': {
        'ETag': 'string',
        'LastModified': datetime(2015, 1, 1)
    },
    'Expiration': 'string',
    'CopySourceVersionId': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • CopyObjectResult (dict) --
      • ETag (string) --
      • LastModified (datetime) --
    • Expiration (string) -- If the object expiration is configured, the response includes this header.
    • CopySourceVersionId (string) --
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

create_bucket(**kwargs)

Creates a new bucket.

Request Syntax

response = client.create_bucket(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read',
    Bucket='string',
    CreateBucketConfiguration={
        'LocationConstraint': 'EU'|'eu-west-1'|'us-west-1'|'us-west-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-northeast-1'|'sa-east-1'|'cn-north-1'|'eu-central-1'
    },
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the bucket.
  • Bucket (string) -- [REQUIRED]
  • CreateBucketConfiguration (dict) --
    • LocationConstraint (string) -- Specifies the region where the bucket will be created. If you don't specify a region, the bucket will be created in US Standard.
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
Return type:

dict

Returns:

Response Syntax

{
    'Location': 'string'
}

Response Structure

  • (dict) --
    • Location (string) --

create_multipart_upload(**kwargs)

Initiates a multipart upload and returns an upload ID.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Request Syntax

response = client.create_multipart_upload(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Bucket='string',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Key='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Bucket (string) -- [REQUIRED]
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Key (string) -- [REQUIRED]
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Bucket': 'string',
    'Key': 'string',
    'UploadId': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Bucket (string) -- Name of the bucket to which the multipart upload was initiated.
    • Key (string) -- Object key for which the multipart upload was initiated.
    • UploadId (string) -- ID for the initiated multipart upload.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

delete_bucket(**kwargs)

Deletes the bucket. All objects (including all object versions and Delete Markers) in the bucket must be deleted before the bucket itself can be deleted.

Request Syntax

response = client.delete_bucket(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_cors(**kwargs)

Deletes the cors configuration information set for the bucket.

Request Syntax

response = client.delete_bucket_cors(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_lifecycle(**kwargs)

Deletes the lifecycle configuration from the bucket.

Request Syntax

response = client.delete_bucket_lifecycle(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_policy(**kwargs)

Deletes the policy from the bucket.

Request Syntax

response = client.delete_bucket_policy(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_replication(**kwargs)

Request Syntax

response = client.delete_bucket_replication(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_tagging(**kwargs)

Deletes the tags from the bucket.

Request Syntax

response = client.delete_bucket_tagging(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_bucket_website(**kwargs)

This operation removes the website configuration from the bucket.

Request Syntax

response = client.delete_bucket_website(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
delete_object(**kwargs)

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

Request Syntax

response = client.delete_object(
    Bucket='string',
    Key='string',
    MFA='string',
    VersionId='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'VersionId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
    • VersionId (string) -- Returns the version ID of the delete marker created as a result of the DELETE operation.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

delete_objects(**kwargs)

This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.

Request Syntax

response = client.delete_objects(
    Bucket='string',
    Delete={
        'Objects': [
            {
                'Key': 'string',
                'VersionId': 'string'
            },
        ],
        'Quiet': True|False
    },
    MFA='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delete (dict) --

    [REQUIRED]

    • Objects (list) -- [REQUIRED]
      • (dict) --
        • Key (string) -- [REQUIRED] Key name of the object to delete.
        • VersionId (string) -- VersionId for the specific version of the object to delete.
    • Quiet (boolean) -- Element to enable quiet mode for the request. When you add this element, you must set its value to true.
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Deleted': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'DeleteMarker': True|False,
            'DeleteMarkerVersionId': 'string'
        },
    ],
    'RequestCharged': 'requester',
    'Errors': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Deleted (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • DeleteMarker (boolean) --
        • DeleteMarkerVersionId (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • Errors (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • Code (string) --
        • Message (string) --

download_file(Bucket, Key, Filename, ExtraArgs=None, Callback=None, Config=None)
generate_presigned_post(Bucket, Key, Fields=None, Conditions=None, ExpiresIn=3600)

Builds the url and the form fields used for a presigned s3 post

Parameters:
  • Bucket (string) -- The name of the bucket to presign the post to. Note that bucket related conditions should not be included in the conditions parameter.
  • Key (string) -- Key name, optionally add ${filename} to the end to attach the submitted filename. Note that key related condtions and fields are filled out for you and should not be included in the fields or condtions parmater.
  • Fields (dict) --

    A dictionary of prefilled form fields to build on top of. Elements that may be included are acl, Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires, success_action_redirect, redirect, success_action_status, and x-amz-meta-.

    Note that if a particular element is included in the fields dictionary it will not be automatically added to the conditions list. You must specify a condition for the element as well.

  • Conditions (list) --

    A list of conditions to include in the policy. Each element can be either a list or a structure. For example:

    [
    {"acl": "public-read"}, ["content-length-range", 2, 5], ["starts-with", "$success_action_redirect", ""]

    ]

    Conditions that are included may pertain to acl, content-length-range, Cache-Control, Content-Type, Content-Disposition, Content-Encoding, Expires, success_action_redirect, redirect, success_action_status, and/or x-amz-meta-.

    Note that if you include a condition, you must specify the a valid value in the fields dictionary as well. A value will not be added automatically to the fields dictionary based on the conditions.

  • ExpiresIn (int) -- The number of seconds the presigned post is valid for.
Return type:

dict

Returns:

A dictionary with two elements: url and fields. Url is the url to post to. Fields is a dictionary filled with the form fields and respective values to use when submitting the post. For example:

{'url': 'https://mybucket.s3.amazonaws.com
'fields': {'acl': 'public-read',

'key': 'mykey', 'signature': 'mysignature', 'policy': 'mybase64 encoded policy'}

}

generate_presigned_url(ClientMethod, Params=None, ExpiresIn=3600, HttpMethod=None)

Generate a presigned url given a client, its method, and arguments

Parameters:
  • ClientMethod (string) -- The client method to presign for
  • Params (dict) -- The parameters normally passed to ClientMethod.
  • ExpiresIn (int) -- The number of seconds the presigned url is valid for. By default it expires in an hour (3600 seconds)
  • HttpMethod (string) -- The http method to use on the generated url. By default, the http method is whatever is used in the method's model.
Returns:

The presigned url

get_bucket_acl(**kwargs)

Gets the access control policy for the bucket.

Request Syntax

response = client.get_bucket_acl(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grants': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'EmailAddress': 'string',
                'ID': 'string',
                'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
        },
    ]
}

Response Structure

  • (dict) --
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
get_bucket_cors(**kwargs)

Returns the cors configuration for the bucket.

Request Syntax

response = client.get_bucket_cors(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'CORSRules': [
        {
            'AllowedHeaders': [
                'string',
            ],
            'AllowedMethods': [
                'string',
            ],
            'AllowedOrigins': [
                'string',
            ],
            'ExposeHeaders': [
                'string',
            ],
            'MaxAgeSeconds': 123
        },
    ]
}

Response Structure

  • (dict) --
    • CORSRules (list) --
      • (dict) --
        • AllowedHeaders (list) -- Specifies which headers are allowed in a pre-flight OPTIONS request.
          • (string) --
        • AllowedMethods (list) -- Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
          • (string) --
        • AllowedOrigins (list) -- One or more origins you want customers to be able to access the bucket from.
          • (string) --
        • ExposeHeaders (list) -- One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).
          • (string) --
        • MaxAgeSeconds (integer) -- The time in seconds that your browser is to cache the preflight response for the specified resource.
get_bucket_lifecycle(**kwargs)

Returns the lifecycle configuration information set on the bucket.

Request Syntax

response = client.get_bucket_lifecycle(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'Rules': [
        {
            'Expiration': {
                'Date': datetime(2015, 1, 1),
                'Days': 123
            },
            'ID': 'string',
            'Prefix': 'string',
            'Status': 'Enabled'|'Disabled',
            'Transition': {
                'Date': datetime(2015, 1, 1),
                'Days': 123,
                'StorageClass': 'GLACIER'
            },
            'NoncurrentVersionTransition': {
                'NoncurrentDays': 123,
                'StorageClass': 'GLACIER'
            },
            'NoncurrentVersionExpiration': {
                'NoncurrentDays': 123
            }
        },
    ]
}

Response Structure

  • (dict) --
    • Rules (list) --
      • (dict) --
        • Expiration (dict) --
          • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
          • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
        • ID (string) -- Unique identifier for the rule. The value cannot be longer than 255 characters.
        • Prefix (string) -- Prefix identifying one or more objects to which the rule applies.
        • Status (string) -- If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
        • Transition (dict) --
          • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
          • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
          • StorageClass (string) -- The class of storage used to store the object.
        • NoncurrentVersionTransition (dict) -- Container for the transition rule that describes when noncurrent objects transition to the GLACIER storage class. If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the GLACIER storage class at a specific period in the object's lifetime.
          • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
          • StorageClass (string) -- The class of storage used to store the object.
        • NoncurrentVersionExpiration (dict) -- Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
          • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
get_bucket_location(**kwargs)

Returns the region the bucket resides in.

Request Syntax

response = client.get_bucket_location(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'LocationConstraint': 'EU'|'eu-west-1'|'us-west-1'|'us-west-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-northeast-1'|'sa-east-1'|'cn-north-1'|'eu-central-1'
}

Response Structure

  • (dict) --
    • LocationConstraint (string) --
get_bucket_logging(**kwargs)

Returns the logging status of a bucket and the permissions users have to view and modify that status. To use GET, you must be the bucket owner.

Request Syntax

response = client.get_bucket_logging(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'LoggingEnabled': {
        'TargetBucket': 'string',
        'TargetGrants': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'EmailAddress': 'string',
                    'ID': 'string',
                    'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'READ'|'WRITE'
            },
        ],
        'TargetPrefix': 'string'
    }
}

Response Structure

  • (dict) --
    • LoggingEnabled (dict) --
      • TargetBucket (string) -- Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.
      • TargetGrants (list) --
        • (dict) --
          • Grantee (dict) --
            • DisplayName (string) -- Screen name of the grantee.
            • EmailAddress (string) -- Email address of the grantee.
            • ID (string) -- The canonical user ID of the grantee.
            • Type (string) -- Type of grantee
            • URI (string) -- URI of the grantee group.
          • Permission (string) -- Logging permissions assigned to the Grantee for the bucket.
      • TargetPrefix (string) -- This element lets you specify a prefix for the keys that the log files will be stored under.
get_bucket_notification(**kwargs)

Deprecated, see the GetBucketNotificationConfiguration operation.

Request Syntax

response = client.get_bucket_notification(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED] Name of the buket to get the notification configuration for.
Return type:dict
Returns:Response Syntax
{
    'TopicConfiguration': {
        'Id': 'string',
        'Events': [
            's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        ],
        'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        'Topic': 'string'
    },
    'QueueConfiguration': {
        'Id': 'string',
        'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        'Events': [
            's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        ],
        'Queue': 'string'
    },
    'CloudFunctionConfiguration': {
        'Id': 'string',
        'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        'Events': [
            's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
        ],
        'CloudFunction': 'string',
        'InvocationRole': 'string'
    }
}

Response Structure

  • (dict) --
    • TopicConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • Event (string) -- Bucket event for which to send notifications.
      • Topic (string) -- Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the bucket.
    • QueueConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Event (string) -- Bucket event for which to send notifications.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • Queue (string) --
    • CloudFunctionConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Event (string) -- Bucket event for which to send notifications.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • CloudFunction (string) --
      • InvocationRole (string) --
get_bucket_notification_configuration(**kwargs)

Returns the notification configuration of a bucket.

Request Syntax

response = client.get_bucket_notification_configuration(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED] Name of the buket to get the notification configuration for.
Return type:dict
Returns:Response Syntax
{
    'TopicConfigurations': [
        {
            'Id': 'string',
            'TopicArn': 'string',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ]
        },
    ],
    'QueueConfigurations': [
        {
            'Id': 'string',
            'QueueArn': 'string',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ]
        },
    ],
    'LambdaFunctionConfigurations': [
        {
            'Id': 'string',
            'LambdaFunctionArn': 'string',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ]
        },
    ]
}

Response Structure

  • (dict) -- Container for specifying the notification configuration of the bucket. If this element is empty, notifications are turned off on the bucket.
    • TopicConfigurations (list) --
      • (dict) -- Container for specifying the configuration when you want Amazon S3 to publish events to an Amazon Simple Notification Service (Amazon SNS) topic.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • TopicArn (string) -- Amazon SNS topic ARN to which Amazon S3 will publish a message when it detects events of specified type.
        • Events (list) --
          • (string) -- Bucket event for which to send notifications.
    • QueueConfigurations (list) --
      • (dict) -- Container for specifying an configuration when you want Amazon S3 to publish events to an Amazon Simple Queue Service (Amazon SQS) queue.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • QueueArn (string) -- Amazon SQS queue ARN to which Amazon S3 will publish a message when it detects events of specified type.
        • Events (list) --
          • (string) -- Bucket event for which to send notifications.
    • LambdaFunctionConfigurations (list) --
      • (dict) -- Container for specifying the AWS Lambda notification configuration.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • LambdaFunctionArn (string) -- Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the specified type.
        • Events (list) --
          • (string) -- Bucket event for which to send notifications.
get_bucket_policy(**kwargs)

Returns the policy of a specified bucket.

Request Syntax

response = client.get_bucket_policy(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'Policy': 'string'
}

Response Structure

  • (dict) --
    • Policy (string) -- The bucket policy as a JSON document.
get_bucket_replication(**kwargs)

Request Syntax

response = client.get_bucket_replication(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'ReplicationConfiguration': {
        'Role': 'string',
        'Rules': [
            {
                'ID': 'string',
                'Prefix': 'string',
                'Status': 'Enabled'|'Disabled',
                'Destination': {
                    'Bucket': 'string'
                }
            },
        ]
    }
}

Response Structure

  • (dict) --
    • ReplicationConfiguration (dict) -- Container for replication rules. You can add as many as 1,000 rules. Total replication configuration size can be up to 2 MB.
      • Role (string) -- Amazon Resource Name (ARN) of an IAM role for Amazon S3 to assume when replicating the objects.
      • Rules (list) -- Container for information about a particular replication rule. Replication configuration must have at least one rule and can contain up to 1,000 rules.
        • (dict) --
          • ID (string) -- Unique identifier for the rule. The value cannot be longer than 255 characters.
          • Prefix (string) -- Object keyname prefix identifying one or more objects to which the rule applies. Maximum prefix length can be up to 1,024 characters. Overlapping prefixes are not supported.
          • Status (string) -- The rule is ignored if status is not Enabled.
          • Destination (dict) --
            • Bucket (string) -- Amazon resource name (ARN) of the bucket where you want Amazon S3 to store replicas of the object identified by the rule.
get_bucket_request_payment(**kwargs)

Returns the request payment configuration of a bucket.

Request Syntax

response = client.get_bucket_request_payment(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'Payer': 'Requester'|'BucketOwner'
}

Response Structure

  • (dict) --
    • Payer (string) -- Specifies who pays for the download and request fees.
get_bucket_tagging(**kwargs)

Returns the tag set associated with the bucket.

Request Syntax

response = client.get_bucket_tagging(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'TagSet': [
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • TagSet (list) --
      • (dict) --
        • Key (string) -- Name of the tag.
        • Value (string) -- Value of the tag.
get_bucket_versioning(**kwargs)

Returns the versioning state of a bucket.

Request Syntax

response = client.get_bucket_versioning(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'Status': 'Enabled'|'Suspended',
    'MFADelete': 'Enabled'|'Disabled'
}

Response Structure

  • (dict) --
    • Status (string) -- The versioning state of the bucket.
    • MFADelete (string) -- Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.
get_bucket_website(**kwargs)

Returns the website configuration for a bucket.

Request Syntax

response = client.get_bucket_website(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Return type:dict
Returns:Response Syntax
{
    'RedirectAllRequestsTo': {
        'HostName': 'string',
        'Protocol': 'http'|'https'
    },
    'IndexDocument': {
        'Suffix': 'string'
    },
    'ErrorDocument': {
        'Key': 'string'
    },
    'RoutingRules': [
        {
            'Condition': {
                'HttpErrorCodeReturnedEquals': 'string',
                'KeyPrefixEquals': 'string'
            },
            'Redirect': {
                'HostName': 'string',
                'HttpRedirectCode': 'string',
                'Protocol': 'http'|'https',
                'ReplaceKeyPrefixWith': 'string',
                'ReplaceKeyWith': 'string'
            }
        },
    ]
}

Response Structure

  • (dict) --
    • RedirectAllRequestsTo (dict) --
      • HostName (string) -- Name of the host where requests will be redirected.
      • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
    • IndexDocument (dict) --
      • Suffix (string) -- A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix is index.html and you make a request to samplebucket/images/ the data that is returned will be for the object with the key name images/index.html) The suffix must not be empty and must not include a slash character.
    • ErrorDocument (dict) --
      • Key (string) -- The object key name to use when a 4XX class error occurs.
    • RoutingRules (list) --
      • (dict) --
        • Condition (dict) -- A container for describing a condition that must be met for the specified redirect to apply. For example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in HTTP error 4xx, redirect request to another host where you might process the error.
          • HttpErrorCodeReturnedEquals (string) -- The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied. Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.
          • KeyPrefixEquals (string) -- The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder. Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.
        • Redirect (dict) -- Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can can specify a different error code to return.
          • HostName (string) -- The host name to use in the redirect request.
          • HttpRedirectCode (string) -- The HTTP redirect code to use on the response. Not required if one of the siblings is present.
          • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
          • ReplaceKeyPrefixWith (string) -- The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.
          • ReplaceKeyWith (string) -- The specific object key to use in the redirect request. For example, redirect request to error.html. Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.
get_object(**kwargs)

Retrieves objects from Amazon S3.

Request Syntax

response = client.get_object(
    Bucket='string',
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Key='string',
    Range='string',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires=datetime(2015, 1, 1),
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Key (string) -- [REQUIRED]
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • ResponseCacheControl (string) -- Sets the Cache-Control header of the response.
  • ResponseContentDisposition (string) -- Sets the Content-Disposition header of the response
  • ResponseContentEncoding (string) -- Sets the Content-Encoding header of the response.
  • ResponseContentLanguage (string) -- Sets the Content-Language header of the response.
  • ResponseContentType (string) -- Sets the Content-Type header of the response.
  • ResponseExpires (datetime) -- Sets the Expires header of the response.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Body': b'bytes',
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentRange': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • Body (bytes) -- Object data.
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentRange (string) -- The portion of the object returned in the response.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

get_object_acl(**kwargs)

Returns the access control list (ACL) of an object.

Request Syntax

response = client.get_object_acl(
    Bucket='string',
    Key='string',
    VersionId='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'Grants': [
        {
            'Grantee': {
                'DisplayName': 'string',
                'EmailAddress': 'string',
                'ID': 'string',
                'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                'URI': 'string'
            },
            'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
        },
    ],
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

get_object_torrent(**kwargs)

Return torrent files from a bucket.

Request Syntax

response = client.get_object_torrent(
    Bucket='string',
    Key='string',
    RequestPayer='requester'
)
Parameters:
Return type:

dict

Returns:

Response Syntax

{
    'Body': b'bytes',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Body (bytes) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

get_paginator(operation_name)

Create a paginator for an operation.

Parameters:operation_name (string) -- The operation name. This is the same name as the method name on the client. For example, if the method name is create_foo, and you'd normally invoke the operation as client.create_foo(**kwargs), if the create_foo operation can be paginated, you can use the call client.get_paginator("create_foo").
Raises OperationNotPageableError:
 Raised if the operation is not pageable. You can use the client.can_paginate method to check if an operation is pageable.
Return type:L{botocore.paginate.Paginator}
Returns:A paginator object.
get_waiter(waiter_name)
head_bucket(**kwargs)

This operation is useful to determine if a bucket exists and you have permission to access it.

Request Syntax

response = client.head_bucket(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
head_object(**kwargs)

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.

Request Syntax

response = client.head_object(
    Bucket='string',
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Key='string',
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Key (string) -- [REQUIRED]
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

list_buckets()

Returns a list of all buckets owned by the authenticated sender of the request.

Request Syntax

response = client.list_buckets()
Return type:dict
Returns:Response Syntax
{
    'Buckets': [
        {
            'Name': 'string',
            'CreationDate': datetime(2015, 1, 1)
        },
    ],
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    }
}

Response Structure

  • (dict) --
    • Buckets (list) --
      • (dict) --
        • Name (string) -- The name of the bucket.
        • CreationDate (datetime) -- Date the bucket was created.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
list_multipart_uploads(**kwargs)

This operation lists in-progress multipart uploads.

Request Syntax

response = client.list_multipart_uploads(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    KeyMarker='string',
    MaxUploads=123,
    Prefix='string',
    UploadIdMarker='string'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- Character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • KeyMarker (string) -- Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin.
  • MaxUploads (integer) -- Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
  • Prefix (string) -- Lists in-progress uploads only for those keys that begin with the specified prefix.
  • UploadIdMarker (string) -- Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored.
Return type:

dict

Returns:

Response Syntax

{
    'Bucket': 'string',
    'KeyMarker': 'string',
    'UploadIdMarker': 'string',
    'NextKeyMarker': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'NextUploadIdMarker': 'string',
    'MaxUploads': 123,
    'IsTruncated': True|False,
    'Uploads': [
        {
            'UploadId': 'string',
            'Key': 'string',
            'Initiated': datetime(2015, 1, 1),
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            },
            'Initiator': {
                'ID': 'string',
                'DisplayName': 'string'
            }
        },
    ],
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url'
}

Response Structure

  • (dict) --
    • Bucket (string) -- Name of the bucket to which the multipart upload was initiated.
    • KeyMarker (string) -- The key at or after which the listing began.
    • UploadIdMarker (string) -- Upload ID after which listing began.
    • NextKeyMarker (string) -- When a list is truncated, this element specifies the value that should be used for the key-marker request parameter in a subsequent request.
    • Prefix (string) -- When a prefix is provided in the request, this field contains the specified prefix. The result contains only keys starting with the specified prefix.
    • Delimiter (string) --
    • NextUploadIdMarker (string) -- When a list is truncated, this element specifies the value that should be used for the upload-id-marker request parameter in a subsequent request.
    • MaxUploads (integer) -- Maximum number of multipart uploads that could have been included in the response.
    • IsTruncated (boolean) -- Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit allowed or specified by max uploads.
    • Uploads (list) --
      • (dict) --
        • UploadId (string) -- Upload ID that identifies the multipart upload.
        • Key (string) -- Key of the object for which the multipart upload was initiated.
        • Initiated (datetime) -- Date and time at which the multipart upload was initiated.
        • StorageClass (string) -- The class of storage used to store the object.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
        • Initiator (dict) -- Identifies who initiated the multipart upload.
          • ID (string) -- If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
          • DisplayName (string) -- Name of the Principal.
    • CommonPrefixes (list) --
      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

list_object_versions(**kwargs)

Returns metadata about all of the versions of objects in a bucket.

Request Syntax

response = client.list_object_versions(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    KeyMarker='string',
    MaxKeys=123,
    Prefix='string',
    VersionIdMarker='string'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • KeyMarker (string) -- Specifies the key to start with when listing objects in a bucket.
  • MaxKeys (integer) -- Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
  • VersionIdMarker (string) -- Specifies the object version you want to start listing from.
Return type:

dict

Returns:

Response Syntax

{
    'IsTruncated': True|False,
    'KeyMarker': 'string',
    'VersionIdMarker': 'string',
    'NextKeyMarker': 'string',
    'NextVersionIdMarker': 'string',
    'Versions': [
        {
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD',
            'Key': 'string',
            'VersionId': 'string',
            'IsLatest': True|False,
            'LastModified': datetime(2015, 1, 1),
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'DeleteMarkers': [
        {
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            },
            'Key': 'string',
            'VersionId': 'string',
            'IsLatest': True|False,
            'LastModified': datetime(2015, 1, 1)
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url'
}

Response Structure

  • (dict) --
    • IsTruncated (boolean) -- A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria. If your results were truncated, you can make a follow-up paginated request using the NextKeyMarker and NextVersionIdMarker response parameters as a starting place in another request to return the rest of the results.
    • KeyMarker (string) -- Marks the last Key returned in a truncated response.
    • VersionIdMarker (string) --
    • NextKeyMarker (string) -- Use this value for the key marker request parameter in a subsequent request.
    • NextVersionIdMarker (string) -- Use this value for the next version id marker parameter in a subsequent request.
    • Versions (list) --
      • (dict) --
        • ETag (string) --
        • Size (integer) -- Size in bytes of the object.
        • StorageClass (string) -- The class of storage used to store the object.
        • Key (string) -- The object key.
        • VersionId (string) -- Version ID of an object.
        • IsLatest (boolean) -- Specifies whether the object is (true) or is not (false) the latest version of an object.
        • LastModified (datetime) -- Date and time the object was last modified.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
    • DeleteMarkers (list) --
      • (dict) --
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
        • Key (string) -- The object key.
        • VersionId (string) -- Version ID of an object.
        • IsLatest (boolean) -- Specifies whether the object is (true) or is not (false) the latest version of an object.
        • LastModified (datetime) -- Date and time the object was last modified.
    • Name (string) --
    • Prefix (string) --
    • Delimiter (string) --
    • MaxKeys (integer) --
    • CommonPrefixes (list) --
      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

list_objects(**kwargs)

Returns some or all (up to 1000) of the objects in a bucket. You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

Request Syntax

response = client.list_objects(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    Marker='string',
    MaxKeys=123,
    Prefix='string'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • Marker (string) -- Specifies the key to start with when listing objects in a bucket.
  • MaxKeys (integer) -- Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
Return type:

dict

Returns:

Response Syntax

{
    'IsTruncated': True|False,
    'Marker': 'string',
    'NextMarker': 'string',
    'Contents': [
        {
            'Key': 'string',
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'GLACIER',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url'
}

Response Structure

  • (dict) --
    • IsTruncated (boolean) -- A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria.
    • Marker (string) --
    • NextMarker (string) -- When response is truncated (the IsTruncated element value in the response is true), you can use the key name in this field as marker in the subsequent request to get next set of objects. Amazon S3 lists objects in alphabetical order Note: This element is returned only if you have delimiter request parameter specified. If response does not include the NextMaker and it is truncated, you can use the value of the last Key in the response as the marker in the subsequent request to get the next set of object keys.
    • Contents (list) --
      • (dict) --
        • Key (string) --
        • LastModified (datetime) --
        • ETag (string) --
        • Size (integer) --
        • StorageClass (string) -- The class of storage used to store the object.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
    • Name (string) --
    • Prefix (string) --
    • Delimiter (string) --
    • MaxKeys (integer) --
    • CommonPrefixes (list) --
      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

list_parts(**kwargs)

Lists the parts that have been uploaded for a specific multipart upload.

Request Syntax

response = client.list_parts(
    Bucket='string',
    Key='string',
    MaxParts=123,
    PartNumberMarker=123,
    UploadId='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • MaxParts (integer) -- Sets the maximum number of parts to return.
  • PartNumberMarker (integer) -- Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
  • UploadId (string) -- [REQUIRED] Upload ID identifying the multipart upload whose parts are being listed.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Bucket': 'string',
    'Key': 'string',
    'UploadId': 'string',
    'PartNumberMarker': 123,
    'NextPartNumberMarker': 123,
    'MaxParts': 123,
    'IsTruncated': True|False,
    'Parts': [
        {
            'PartNumber': 123,
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123
        },
    ],
    'Initiator': {
        'ID': 'string',
        'DisplayName': 'string'
    },
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Bucket (string) -- Name of the bucket to which the multipart upload was initiated.
    • Key (string) -- Object key for which the multipart upload was initiated.
    • UploadId (string) -- Upload ID identifying the multipart upload whose parts are being listed.
    • PartNumberMarker (integer) -- Part number after which listing begins.
    • NextPartNumberMarker (integer) -- When a list is truncated, this element specifies the last part in the list, as well as the value to use for the part-number-marker request parameter in a subsequent request.
    • MaxParts (integer) -- Maximum number of parts that were allowed in the response.
    • IsTruncated (boolean) -- Indicates whether the returned list of parts is truncated.
    • Parts (list) --
      • (dict) --
        • PartNumber (integer) -- Part number identifying the part. This is a positive integer between 1 and 10,000.
        • LastModified (datetime) -- Date and time at which the part was uploaded.
        • ETag (string) -- Entity tag returned when the part was uploaded.
        • Size (integer) -- Size of the uploaded part data.
    • Initiator (dict) -- Identifies who initiated the multipart upload.
      • ID (string) -- If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
      • DisplayName (string) -- Name of the Principal.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
    • StorageClass (string) -- The class of storage used to store the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

put_bucket_acl(**kwargs)

Sets the permissions on a bucket using access control lists (ACL).

Request Syntax

response = client.put_bucket_acl(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read',
    AccessControlPolicy={
        'Grants': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'EmailAddress': 'string',
                    'ID': 'string',
                    'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    },
    Bucket='string',
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the bucket.
  • AccessControlPolicy (dict) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- [REQUIRED] Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
  • Bucket (string) -- [REQUIRED]
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
Returns:

None

put_bucket_cors(**kwargs)

Sets the cors configuration for a bucket.

Request Syntax

response = client.put_bucket_cors(
    Bucket='string',
    CORSConfiguration={
        'CORSRules': [
            {
                'AllowedHeaders': [
                    'string',
                ],
                'AllowedMethods': [
                    'string',
                ],
                'AllowedOrigins': [
                    'string',
                ],
                'ExposeHeaders': [
                    'string',
                ],
                'MaxAgeSeconds': 123
            },
        ]
    },

)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • CORSConfiguration (dict) --
    • CORSRules (list) --
      • (dict) --
        • AllowedHeaders (list) -- Specifies which headers are allowed in a pre-flight OPTIONS request.
          • (string) --
        • AllowedMethods (list) -- Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
          • (string) --
        • AllowedOrigins (list) -- One or more origins you want customers to be able to access the bucket from.
          • (string) --
        • ExposeHeaders (list) -- One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).
          • (string) --
        • MaxAgeSeconds (integer) -- The time in seconds that your browser is to cache the preflight response for the specified resource.
Returns:

None

put_bucket_lifecycle(**kwargs)

Sets lifecycle configuration for your bucket. If a lifecycle configuration exists, it replaces it.

Request Syntax

response = client.put_bucket_lifecycle(
    Bucket='string',
    LifecycleConfiguration={
        'Rules': [
            {
                'Expiration': {
                    'Date': datetime(2015, 1, 1),
                    'Days': 123
                },
                'ID': 'string',
                'Prefix': 'string',
                'Status': 'Enabled'|'Disabled',
                'Transition': {
                    'Date': datetime(2015, 1, 1),
                    'Days': 123,
                    'StorageClass': 'GLACIER'
                },
                'NoncurrentVersionTransition': {
                    'NoncurrentDays': 123,
                    'StorageClass': 'GLACIER'
                },
                'NoncurrentVersionExpiration': {
                    'NoncurrentDays': 123
                }
            },
        ]
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • LifecycleConfiguration (dict) --
    • Rules (list) -- [REQUIRED]
      • (dict) --
        • Expiration (dict) --
          • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
          • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
        • ID (string) -- Unique identifier for the rule. The value cannot be longer than 255 characters.
        • Prefix (string) -- [REQUIRED] Prefix identifying one or more objects to which the rule applies.
        • Status (string) -- [REQUIRED] If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
        • Transition (dict) --
          • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
          • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
          • StorageClass (string) -- The class of storage used to store the object.
        • NoncurrentVersionTransition (dict) -- Container for the transition rule that describes when noncurrent objects transition to the GLACIER storage class. If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the GLACIER storage class at a specific period in the object's lifetime.
          • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
          • StorageClass (string) -- The class of storage used to store the object.
        • NoncurrentVersionExpiration (dict) -- Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
          • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
Returns:

None

put_bucket_logging(**kwargs)

Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. To set the logging status of a bucket, you must be the bucket owner.

Request Syntax

response = client.put_bucket_logging(
    Bucket='string',
    BucketLoggingStatus={
        'LoggingEnabled': {
            'TargetBucket': 'string',
            'TargetGrants': [
                {
                    'Grantee': {
                        'DisplayName': 'string',
                        'EmailAddress': 'string',
                        'ID': 'string',
                        'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                        'URI': 'string'
                    },
                    'Permission': 'FULL_CONTROL'|'READ'|'WRITE'
                },
            ],
            'TargetPrefix': 'string'
        }
    },

)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • BucketLoggingStatus (dict) --

    [REQUIRED]

    • LoggingEnabled (dict) --
      • TargetBucket (string) -- Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.
      • TargetGrants (list) --
        • (dict) --
          • Grantee (dict) --
            • DisplayName (string) -- Screen name of the grantee.
            • EmailAddress (string) -- Email address of the grantee.
            • ID (string) -- The canonical user ID of the grantee.
            • Type (string) -- [REQUIRED] Type of grantee
            • URI (string) -- URI of the grantee group.
          • Permission (string) -- Logging permissions assigned to the Grantee for the bucket.
      • TargetPrefix (string) -- This element lets you specify a prefix for the keys that the log files will be stored under.
Returns:

None

put_bucket_notification(**kwargs)

Deprecated, see the PutBucketNotificationConfiguraiton operation.

Request Syntax

response = client.put_bucket_notification(
    Bucket='string',
    NotificationConfiguration={
        'TopicConfiguration': {
            'Id': 'string',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ],
            'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            'Topic': 'string'
        },
        'QueueConfiguration': {
            'Id': 'string',
            'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ],
            'Queue': 'string'
        },
        'CloudFunctionConfiguration': {
            'Id': 'string',
            'Event': 's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            'Events': [
                's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
            ],
            'CloudFunction': 'string',
            'InvocationRole': 'string'
        }
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • NotificationConfiguration (dict) --

    [REQUIRED]

    • TopicConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • Event (string) -- Bucket event for which to send notifications.
      • Topic (string) -- Amazon SNS topic to which Amazon S3 will publish a message to report the specified events for the bucket.
    • QueueConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Event (string) -- Bucket event for which to send notifications.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • Queue (string) --
    • CloudFunctionConfiguration (dict) --
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • Event (string) -- Bucket event for which to send notifications.
      • Events (list) --
        • (string) -- Bucket event for which to send notifications.
      • CloudFunction (string) --
      • InvocationRole (string) --
Returns:

None

put_bucket_notification_configuration(**kwargs)

Enables notifications of specified events for a bucket.

Request Syntax

response = client.put_bucket_notification_configuration(
    Bucket='string',
    NotificationConfiguration={
        'TopicConfigurations': [
            {
                'Id': 'string',
                'TopicArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ],
        'QueueConfigurations': [
            {
                'Id': 'string',
                'QueueArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ],
        'LambdaFunctionConfigurations': [
            {
                'Id': 'string',
                'LambdaFunctionArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ]
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • NotificationConfiguration (dict) --

    [REQUIRED] Container for specifying the notification configuration of the bucket. If this element is empty, notifications are turned off on the bucket.

    • TopicConfigurations (list) --
      • (dict) -- Container for specifying the configuration when you want Amazon S3 to publish events to an Amazon Simple Notification Service (Amazon SNS) topic.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • TopicArn (string) -- [REQUIRED] Amazon SNS topic ARN to which Amazon S3 will publish a message when it detects events of specified type.
        • Events (list) -- [REQUIRED]
          • (string) -- Bucket event for which to send notifications.
    • QueueConfigurations (list) --
      • (dict) -- Container for specifying an configuration when you want Amazon S3 to publish events to an Amazon Simple Queue Service (Amazon SQS) queue.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • QueueArn (string) -- [REQUIRED] Amazon SQS queue ARN to which Amazon S3 will publish a message when it detects events of specified type.
        • Events (list) -- [REQUIRED]
          • (string) -- Bucket event for which to send notifications.
    • LambdaFunctionConfigurations (list) --
      • (dict) -- Container for specifying the AWS Lambda notification configuration.
        • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
        • LambdaFunctionArn (string) -- [REQUIRED] Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the specified type.
        • Events (list) -- [REQUIRED]
          • (string) -- Bucket event for which to send notifications.
Returns:

None

put_bucket_policy(**kwargs)

Replaces a policy on a bucket. If the bucket already has a policy, the one in this request completely replaces it.

Request Syntax

response = client.put_bucket_policy(
    Bucket='string',
    Policy='string'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Policy (string) -- [REQUIRED] The bucket policy as a JSON document.
Returns:

None

put_bucket_replication(**kwargs)

Creates a new replication configuration (or replaces an existing one, if present).

Request Syntax

response = client.put_bucket_replication(
    Bucket='string',
    ReplicationConfiguration={
        'Role': 'string',
        'Rules': [
            {
                'ID': 'string',
                'Prefix': 'string',
                'Status': 'Enabled'|'Disabled',
                'Destination': {
                    'Bucket': 'string'
                }
            },
        ]
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • ReplicationConfiguration (dict) --

    [REQUIRED] Container for replication rules. You can add as many as 1,000 rules. Total replication configuration size can be up to 2 MB.

    • Role (string) -- [REQUIRED] Amazon Resource Name (ARN) of an IAM role for Amazon S3 to assume when replicating the objects.
    • Rules (list) -- [REQUIRED] Container for information about a particular replication rule. Replication configuration must have at least one rule and can contain up to 1,000 rules.
      • (dict) --
        • ID (string) -- Unique identifier for the rule. The value cannot be longer than 255 characters.
        • Prefix (string) -- [REQUIRED] Object keyname prefix identifying one or more objects to which the rule applies. Maximum prefix length can be up to 1,024 characters. Overlapping prefixes are not supported.
        • Status (string) -- [REQUIRED] The rule is ignored if status is not Enabled.
        • Destination (dict) -- [REQUIRED]
          • Bucket (string) -- [REQUIRED] Amazon resource name (ARN) of the bucket where you want Amazon S3 to store replicas of the object identified by the rule.
Returns:

None

put_bucket_request_payment(**kwargs)

Sets the request payment configuration for a bucket. By default, the bucket owner pays for downloads from the bucket. This configuration parameter enables the bucket owner (only) to specify that the person requesting the download will be charged for the download. Documentation on requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html

Request Syntax

response = client.put_bucket_request_payment(
    Bucket='string',
    RequestPaymentConfiguration={
        'Payer': 'Requester'|'BucketOwner'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • RequestPaymentConfiguration (dict) --

    [REQUIRED]

    • Payer (string) -- [REQUIRED] Specifies who pays for the download and request fees.
Returns:

None

put_bucket_tagging(**kwargs)

Sets the tags for a bucket.

Request Syntax

response = client.put_bucket_tagging(
    Bucket='string',
    Tagging={
        'TagSet': [
            {
                'Key': 'string',
                'Value': 'string'
            },
        ]
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Tagging (dict) --

    [REQUIRED]

    • TagSet (list) -- [REQUIRED]
      • (dict) --
        • Key (string) -- [REQUIRED] Name of the tag.
        • Value (string) -- [REQUIRED] Value of the tag.
Returns:

None

put_bucket_versioning(**kwargs)

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Request Syntax

response = client.put_bucket_versioning(
    Bucket='string',
    MFA='string',
    VersioningConfiguration={
        'MFADelete': 'Enabled'|'Disabled',
        'Status': 'Enabled'|'Suspended'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • VersioningConfiguration (dict) --

    [REQUIRED]

    • MFADelete (string) -- Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.
    • Status (string) -- The versioning state of the bucket.
Returns:

None

put_bucket_website(**kwargs)

Set the website configuration for a bucket.

Request Syntax

response = client.put_bucket_website(
    Bucket='string',
    WebsiteConfiguration={
        'ErrorDocument': {
            'Key': 'string'
        },
        'IndexDocument': {
            'Suffix': 'string'
        },
        'RedirectAllRequestsTo': {
            'HostName': 'string',
            'Protocol': 'http'|'https'
        },
        'RoutingRules': [
            {
                'Condition': {
                    'HttpErrorCodeReturnedEquals': 'string',
                    'KeyPrefixEquals': 'string'
                },
                'Redirect': {
                    'HostName': 'string',
                    'HttpRedirectCode': 'string',
                    'Protocol': 'http'|'https',
                    'ReplaceKeyPrefixWith': 'string',
                    'ReplaceKeyWith': 'string'
                }
            },
        ]
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • WebsiteConfiguration (dict) --

    [REQUIRED]

    • ErrorDocument (dict) --
      • Key (string) -- [REQUIRED] The object key name to use when a 4XX class error occurs.
    • IndexDocument (dict) --
      • Suffix (string) -- [REQUIRED] A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix is index.html and you make a request to samplebucket/images/ the data that is returned will be for the object with the key name images/index.html) The suffix must not be empty and must not include a slash character.
    • RedirectAllRequestsTo (dict) --
      • HostName (string) -- [REQUIRED] Name of the host where requests will be redirected.
      • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
    • RoutingRules (list) --
      • (dict) --
        • Condition (dict) -- A container for describing a condition that must be met for the specified redirect to apply. For example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in HTTP error 4xx, redirect request to another host where you might process the error.
          • HttpErrorCodeReturnedEquals (string) -- The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied. Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.
          • KeyPrefixEquals (string) -- The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder. Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.
        • Redirect (dict) -- [REQUIRED] Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can can specify a different error code to return.
          • HostName (string) -- The host name to use in the redirect request.
          • HttpRedirectCode (string) -- The HTTP redirect code to use on the response. Not required if one of the siblings is present.
          • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
          • ReplaceKeyPrefixWith (string) -- The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.
          • ReplaceKeyWith (string) -- The specific object key to use in the redirect request. For example, redirect request to error.html. Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.
Returns:

None

put_object(**kwargs)

Adds an object to a bucket.

Request Syntax

response = client.put_object(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Body=b'bytes',
    Bucket='string',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength=123,
    ContentMD5='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Key='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Body (bytes) -- Object data.
  • Bucket (string) -- [REQUIRED]
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Key (string) -- [REQUIRED]
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Expiration': 'string',
    'ETag': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'VersionId': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Expiration (string) -- If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
    • ETag (string) -- Entity tag for the uploaded object.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • VersionId (string) -- Version of the object.
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

put_object_acl(**kwargs)

uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a bucket

Request Syntax

response = client.put_object_acl(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    AccessControlPolicy={
        'Grants': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'EmailAddress': 'string',
                    'ID': 'string',
                    'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    },
    Bucket='string',
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string',
    Key='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • AccessControlPolicy (dict) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- [REQUIRED] Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
  • Bucket (string) -- [REQUIRED]
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
  • Key (string) -- [REQUIRED]
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

restore_object(**kwargs)

Restores an archived copy of an object back into Amazon S3

Request Syntax

response = client.restore_object(
    Bucket='string',
    Key='string',
    VersionId='string',
    RestoreRequest={
        'Days': 123
    },
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • VersionId (string) --
  • RestoreRequest (dict) --
    • Days (integer) -- [REQUIRED] Lifetime of the active copy in days
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

upload_file(Filename, Bucket, Key, ExtraArgs=None, Callback=None, Config=None)
upload_part(**kwargs)

Uploads a part in a multipart upload.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Request Syntax

response = client.upload_part(
    Body=b'bytes',
    Bucket='string',
    ContentLength=123,
    ContentMD5='string',
    Key='string',
    PartNumber=123,
    UploadId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Body (bytes) --
  • Bucket (string) -- [REQUIRED]
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • Key (string) -- [REQUIRED]
  • PartNumber (integer) -- [REQUIRED] Part number of part being uploaded. This is a positive integer between 1 and 10,000.
  • UploadId (string) -- [REQUIRED] Upload ID identifying the multipart upload whose part is being uploaded.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'ETag': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • ETag (string) -- Entity tag for the uploaded object.
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

upload_part_copy(**kwargs)

Uploads a part by copying data from an existing object as data source.

Request Syntax

response = client.upload_part_copy(
    Bucket='string',
    CopySource='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince=datetime(2015, 1, 1),
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince=datetime(2015, 1, 1),
    CopySourceRange='string',
    Key='string',
    PartNumber=123,
    UploadId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    CopySourceSSECustomerAlgorithm='string',
    CopySourceSSECustomerKey='string',
    CopySourceSSECustomerKeyMD5='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • CopySource (string) -- [REQUIRED] The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
  • CopySourceIfMatch (string) -- Copies the object if its entity tag (ETag) matches the specified tag.
  • CopySourceIfModifiedSince (datetime) -- Copies the object if it has been modified since the specified time.
  • CopySourceIfNoneMatch (string) -- Copies the object if its entity tag (ETag) is different than the specified ETag.
  • CopySourceIfUnmodifiedSince (datetime) -- Copies the object if it hasn't been modified since the specified time.
  • CopySourceRange (string) -- The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source. You can copy a range only if the source object is greater than 5 GB.
  • Key (string) -- [REQUIRED]
  • PartNumber (integer) -- [REQUIRED] Part number of part being copied. This is a positive integer between 1 and 10,000.
  • UploadId (string) -- [REQUIRED] Upload ID identifying the multipart upload whose part is being copied.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • CopySourceSSECustomerAlgorithm (string) -- Specifies the algorithm to use when decrypting the source object (e.g., AES256).
  • CopySourceSSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
  • CopySourceSSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'CopySourceVersionId': 'string',
    'CopyPartResult': {
        'ETag': 'string',
        'LastModified': datetime(2015, 1, 1)
    },
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • CopySourceVersionId (string) -- The version of the source object that was copied, if you have enabled versioning on the source bucket.
    • CopyPartResult (dict) --
      • ETag (string) -- Entity tag of the object.
      • LastModified (datetime) -- Date and time at which the object was uploaded.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

Paginators

The available paginators are:

class S3.Paginator.list_multipart_uploads
paginator = client.get_paginator('list_multipart_uploads')
paginate(**kwargs)

Creates an iterator that will paginate through responses from S3.Client.list_multipart_uploads().

Request Syntax

response_iterator = paginator.paginate(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    Prefix='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- Character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • Prefix (string) -- Lists in-progress uploads only for those keys that begin with the specified prefix.
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'Bucket': 'string',
    'KeyMarker': 'string',
    'UploadIdMarker': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxUploads': 123,
    'IsTruncated': True|False,
    'Uploads': [
        {
            'UploadId': 'string',
            'Key': 'string',
            'Initiated': datetime(2015, 1, 1),
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            },
            'Initiator': {
                'ID': 'string',
                'DisplayName': 'string'
            }
        },
    ],
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url',
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Bucket (string) -- Name of the bucket to which the multipart upload was initiated.

    • KeyMarker (string) -- The key at or after which the listing began.

    • UploadIdMarker (string) -- Upload ID after which listing began.

    • Prefix (string) -- When a prefix is provided in the request, this field contains the specified prefix. The result contains only keys starting with the specified prefix.

    • Delimiter (string) --

    • MaxUploads (integer) -- Maximum number of multipart uploads that could have been included in the response.

    • IsTruncated (boolean) -- Indicates whether the returned list of multipart uploads is truncated. A value of true indicates that the list was truncated. The list can be truncated if the number of multipart uploads exceeds the limit allowed or specified by max uploads.

    • Uploads (list) --

      • (dict) --
        • UploadId (string) -- Upload ID that identifies the multipart upload.
        • Key (string) -- Key of the object for which the multipart upload was initiated.
        • Initiated (datetime) -- Date and time at which the multipart upload was initiated.
        • StorageClass (string) -- The class of storage used to store the object.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
        • Initiator (dict) -- Identifies who initiated the multipart upload.
          • ID (string) -- If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
          • DisplayName (string) -- Name of the Principal.
    • CommonPrefixes (list) --

      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

    • NextToken (string) --

      A token to resume pagination.

class S3.Paginator.list_object_versions
paginator = client.get_paginator('list_object_versions')
paginate(**kwargs)

Creates an iterator that will paginate through responses from S3.Client.list_object_versions().

Request Syntax

response_iterator = paginator.paginate(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    Prefix='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'IsTruncated': True|False,
    'KeyMarker': 'string',
    'VersionIdMarker': 'string',
    'Versions': [
        {
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD',
            'Key': 'string',
            'VersionId': 'string',
            'IsLatest': True|False,
            'LastModified': datetime(2015, 1, 1),
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'DeleteMarkers': [
        {
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            },
            'Key': 'string',
            'VersionId': 'string',
            'IsLatest': True|False,
            'LastModified': datetime(2015, 1, 1)
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url',
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • IsTruncated (boolean) -- A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria. If your results were truncated, you can make a follow-up paginated request using the NextKeyMarker and NextVersionIdMarker response parameters as a starting place in another request to return the rest of the results.

    • KeyMarker (string) -- Marks the last Key returned in a truncated response.

    • VersionIdMarker (string) --

    • Versions (list) --

      • (dict) --
        • ETag (string) --
        • Size (integer) -- Size in bytes of the object.
        • StorageClass (string) -- The class of storage used to store the object.
        • Key (string) -- The object key.
        • VersionId (string) -- Version ID of an object.
        • IsLatest (boolean) -- Specifies whether the object is (true) or is not (false) the latest version of an object.
        • LastModified (datetime) -- Date and time the object was last modified.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
    • DeleteMarkers (list) --

      • (dict) --
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
        • Key (string) -- The object key.
        • VersionId (string) -- Version ID of an object.
        • IsLatest (boolean) -- Specifies whether the object is (true) or is not (false) the latest version of an object.
        • LastModified (datetime) -- Date and time the object was last modified.
    • Name (string) --

    • Prefix (string) --

    • Delimiter (string) --

    • MaxKeys (integer) --

    • CommonPrefixes (list) --

      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

    • NextToken (string) --

      A token to resume pagination.

class S3.Paginator.list_objects
paginator = client.get_paginator('list_objects')
paginate(**kwargs)

Creates an iterator that will paginate through responses from S3.Client.list_objects().

Request Syntax

response_iterator = paginator.paginate(
    Bucket='string',
    Delimiter='string',
    EncodingType='url',
    Prefix='string',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'IsTruncated': True|False,
    'Marker': 'string',
    'NextMarker': 'string',
    'Contents': [
        {
            'Key': 'string',
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123,
            'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'GLACIER',
            'Owner': {
                'DisplayName': 'string',
                'ID': 'string'
            }
        },
    ],
    'Name': 'string',
    'Prefix': 'string',
    'Delimiter': 'string',
    'MaxKeys': 123,
    'CommonPrefixes': [
        {
            'Prefix': 'string'
        },
    ],
    'EncodingType': 'url',
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • IsTruncated (boolean) -- A flag that indicates whether or not Amazon S3 returned all of the results that satisfied the search criteria.

    • Marker (string) --

    • NextMarker (string) -- When response is truncated (the IsTruncated element value in the response is true), you can use the key name in this field as marker in the subsequent request to get next set of objects. Amazon S3 lists objects in alphabetical order Note: This element is returned only if you have delimiter request parameter specified. If response does not include the NextMaker and it is truncated, you can use the value of the last Key in the response as the marker in the subsequent request to get the next set of object keys.

    • Contents (list) --

      • (dict) --
        • Key (string) --
        • LastModified (datetime) --
        • ETag (string) --
        • Size (integer) --
        • StorageClass (string) -- The class of storage used to store the object.
        • Owner (dict) --
          • DisplayName (string) --
          • ID (string) --
    • Name (string) --

    • Prefix (string) --

    • Delimiter (string) --

    • MaxKeys (integer) --

    • CommonPrefixes (list) --

      • (dict) --
        • Prefix (string) --
    • EncodingType (string) -- Encoding type used by Amazon S3 to encode object keys in the response.

    • NextToken (string) --

      A token to resume pagination.

class S3.Paginator.list_parts
paginator = client.get_paginator('list_parts')
paginate(**kwargs)

Creates an iterator that will paginate through responses from S3.Client.list_parts().

Request Syntax

response_iterator = paginator.paginate(
    Bucket='string',
    Key='string',
    UploadId='string',
    RequestPayer='requester',
    PaginationConfig={
        'MaxItems': 123,
        'PageSize': 123,
        'StartingToken': 'string'
    }
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • Key (string) -- [REQUIRED]
  • UploadId (string) -- [REQUIRED] Upload ID identifying the multipart upload whose parts are being listed.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
  • PaginationConfig (dict) --

    A dictionary that provides parameters to control pagination.

    • MaxItems (integer) --

      The total number of items to return. If the total number of items available is more than the value specified in max-items then a NextToken will be provided in the output that you can use to resume pagination.

    • PageSize (integer) --

      The size of each page.

    • StartingToken (string) --

      A token to specify where to start paginating. This is the NextToken from a previous response.

Return type:

dict

Returns:

Response Syntax

{
    'Bucket': 'string',
    'Key': 'string',
    'UploadId': 'string',
    'PartNumberMarker': 123,
    'MaxParts': 123,
    'IsTruncated': True|False,
    'Parts': [
        {
            'PartNumber': 123,
            'LastModified': datetime(2015, 1, 1),
            'ETag': 'string',
            'Size': 123
        },
    ],
    'Initiator': {
        'ID': 'string',
        'DisplayName': 'string'
    },
    'Owner': {
        'DisplayName': 'string',
        'ID': 'string'
    },
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'NextToken': 'string'
}

Response Structure

  • (dict) --

    • Bucket (string) -- Name of the bucket to which the multipart upload was initiated.

    • Key (string) -- Object key for which the multipart upload was initiated.

    • UploadId (string) -- Upload ID identifying the multipart upload whose parts are being listed.

    • PartNumberMarker (integer) -- Part number after which listing begins.

    • MaxParts (integer) -- Maximum number of parts that were allowed in the response.

    • IsTruncated (boolean) -- Indicates whether the returned list of parts is truncated.

    • Parts (list) --

      • (dict) --
        • PartNumber (integer) -- Part number identifying the part. This is a positive integer between 1 and 10,000.
        • LastModified (datetime) -- Date and time at which the part was uploaded.
        • ETag (string) -- Entity tag returned when the part was uploaded.
        • Size (integer) -- Size of the uploaded part data.
    • Initiator (dict) -- Identifies who initiated the multipart upload.

      • ID (string) -- If the principal is an AWS account, it provides the Canonical User ID. If the principal is an IAM User, it provides a user ARN value.
      • DisplayName (string) -- Name of the Principal.
    • Owner (dict) --

      • DisplayName (string) --
      • ID (string) --
    • StorageClass (string) -- The class of storage used to store the object.

    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

    • NextToken (string) --

      A token to resume pagination.

Waiters

The available waiters are:

class S3.Waiter.bucket_exists
waiter = client.get_waiter('bucket_exists')
wait(**kwargs)

This polls S3.Client.head_bucket() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

waiter.wait(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
class S3.Waiter.bucket_not_exists
waiter = client.get_waiter('bucket_not_exists')
wait(**kwargs)

This polls S3.Client.head_bucket() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

waiter.wait(
    Bucket='string'
)
Parameters:Bucket (string) -- [REQUIRED]
Returns:None
class S3.Waiter.object_exists
waiter = client.get_waiter('object_exists')
wait(**kwargs)

This polls S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

waiter.wait(
    Bucket='string',
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Key='string',
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Key (string) -- [REQUIRED]
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Returns:

None

class S3.Waiter.object_not_exists
waiter = client.get_waiter('object_not_exists')
wait(**kwargs)

This polls S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

waiter.wait(
    Bucket='string',
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Key='string',
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Bucket (string) -- [REQUIRED]
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Key (string) -- [REQUIRED]
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Returns:

None

Service Resource

class S3.ServiceResource

A resource representing Amazon Simple Storage Service (S3):

import boto3

s3 = boto3.resource('s3')

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available collections:

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

create_bucket(**kwargs)

Creates a new bucket.

Request Syntax

bucket = s3.create_bucket(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read',
    Bucket='string',
    CreateBucketConfiguration={
        'LocationConstraint': 'EU'|'eu-west-1'|'us-west-1'|'us-west-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-northeast-1'|'sa-east-1'|'cn-north-1'|'eu-central-1'
    },
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the bucket.
  • Bucket (string) -- [REQUIRED]
  • CreateBucketConfiguration (dict) --
    • LocationConstraint (string) -- Specifies the region where the bucket will be created. If you don't specify a region, the bucket will be created in US Standard.
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
Return type:

s3.Bucket

Returns:

A Bucket resource

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket(name)

Creates a Bucket resource.:

bucket = s3.Bucket('name')
Parameters:name (string) -- The Bucket's name identifier. This must be set.
Return type:S3.Bucket
Returns:A Bucket resource
BucketAcl(bucket_name)

Creates a BucketAcl resource.:

bucket_acl = s3.BucketAcl('bucket_name')
Parameters:bucket_name (string) -- The BucketAcl's bucket_name identifier. This must be set.
Return type:S3.BucketAcl
Returns:A BucketAcl resource
BucketCors(bucket_name)

Creates a BucketCors resource.:

bucket_cors = s3.BucketCors('bucket_name')
Parameters:bucket_name (string) -- The BucketCors's bucket_name identifier. This must be set.
Return type:S3.BucketCors
Returns:A BucketCors resource
BucketLifecycle(bucket_name)

Creates a BucketLifecycle resource.:

bucket_lifecycle = s3.BucketLifecycle('bucket_name')
Parameters:bucket_name (string) -- The BucketLifecycle's bucket_name identifier. This must be set.
Return type:S3.BucketLifecycle
Returns:A BucketLifecycle resource
BucketLogging(bucket_name)

Creates a BucketLogging resource.:

bucket_logging = s3.BucketLogging('bucket_name')
Parameters:bucket_name (string) -- The BucketLogging's bucket_name identifier. This must be set.
Return type:S3.BucketLogging
Returns:A BucketLogging resource
BucketNotification(bucket_name)

Creates a BucketNotification resource.:

bucket_notification = s3.BucketNotification('bucket_name')
Parameters:bucket_name (string) -- The BucketNotification's bucket_name identifier. This must be set.
Return type:S3.BucketNotification
Returns:A BucketNotification resource
BucketPolicy(bucket_name)

Creates a BucketPolicy resource.:

bucket_policy = s3.BucketPolicy('bucket_name')
Parameters:bucket_name (string) -- The BucketPolicy's bucket_name identifier. This must be set.
Return type:S3.BucketPolicy
Returns:A BucketPolicy resource
BucketRequestPayment(bucket_name)

Creates a BucketRequestPayment resource.:

bucket_request_payment = s3.BucketRequestPayment('bucket_name')
Parameters:bucket_name (string) -- The BucketRequestPayment's bucket_name identifier. This must be set.
Return type:S3.BucketRequestPayment
Returns:A BucketRequestPayment resource
BucketTagging(bucket_name)

Creates a BucketTagging resource.:

bucket_tagging = s3.BucketTagging('bucket_name')
Parameters:bucket_name (string) -- The BucketTagging's bucket_name identifier. This must be set.
Return type:S3.BucketTagging
Returns:A BucketTagging resource
BucketVersioning(bucket_name)

Creates a BucketVersioning resource.:

bucket_versioning = s3.BucketVersioning('bucket_name')
Parameters:bucket_name (string) -- The BucketVersioning's bucket_name identifier. This must be set.
Return type:S3.BucketVersioning
Returns:A BucketVersioning resource
BucketWebsite(bucket_name)

Creates a BucketWebsite resource.:

bucket_website = s3.BucketWebsite('bucket_name')
Parameters:bucket_name (string) -- The BucketWebsite's bucket_name identifier. This must be set.
Return type:S3.BucketWebsite
Returns:A BucketWebsite resource
MultipartUpload(bucket_name, object_key, id)

Creates a MultipartUpload resource.:

multipart_upload = s3.MultipartUpload('bucket_name','object_key','id')
Parameters:
  • bucket_name (string) -- The MultipartUpload's bucket_name identifier. This must be set.
  • object_key (string) -- The MultipartUpload's object_key identifier. This must be set.
  • id (string) -- The MultipartUpload's id identifier. This must be set.
Return type:

S3.MultipartUpload

Returns:

A MultipartUpload resource

MultipartUploadPart(bucket_name, object_key, multipart_upload_id, part_number)

Creates a MultipartUploadPart resource.:

multipart_upload_part = s3.MultipartUploadPart('bucket_name','object_key','multipart_upload_id','part_number')
Parameters:
  • bucket_name (string) -- The MultipartUploadPart's bucket_name identifier. This must be set.
  • object_key (string) -- The MultipartUploadPart's object_key identifier. This must be set.
  • multipart_upload_id (string) -- The MultipartUploadPart's multipart_upload_id identifier. This must be set.
  • part_number (string) -- The MultipartUploadPart's part_number identifier. This must be set.
Return type:

S3.MultipartUploadPart

Returns:

A MultipartUploadPart resource

Object(bucket_name, key)

Creates a Object resource.:

object = s3.Object('bucket_name','key')
Parameters:
  • bucket_name (string) -- The Object's bucket_name identifier. This must be set.
  • key (string) -- The Object's key identifier. This must be set.
Return type:

S3.Object

Returns:

A Object resource

ObjectAcl(bucket_name, object_key)

Creates a ObjectAcl resource.:

object_acl = s3.ObjectAcl('bucket_name','object_key')
Parameters:
  • bucket_name (string) -- The ObjectAcl's bucket_name identifier. This must be set.
  • object_key (string) -- The ObjectAcl's object_key identifier. This must be set.
Return type:

S3.ObjectAcl

Returns:

A ObjectAcl resource

ObjectSummary(bucket_name, key)

Creates a ObjectSummary resource.:

object_summary = s3.ObjectSummary('bucket_name','key')
Parameters:
  • bucket_name (string) -- The ObjectSummary's bucket_name identifier. This must be set.
  • key (string) -- The ObjectSummary's key identifier. This must be set.
Return type:

S3.ObjectSummary

Returns:

A ObjectSummary resource

ObjectVersion(bucket_name, object_key, id)

Creates a ObjectVersion resource.:

object_version = s3.ObjectVersion('bucket_name','object_key','id')
Parameters:
  • bucket_name (string) -- The ObjectVersion's bucket_name identifier. This must be set.
  • object_key (string) -- The ObjectVersion's object_key identifier. This must be set.
  • id (string) -- The ObjectVersion's id identifier. This must be set.
Return type:

S3.ObjectVersion

Returns:

A ObjectVersion resource

Collections

Collections provide an interface to iterate over and manipulate groups of resources. For more information about collections refer to the Resources Introduction Guide.

buckets
all()

Creates an iterable of all Bucket resources in the collection.

Request Syntax

bucket_iterator = s3.buckets.all()
Return type:s3.Bucket
Returns:A Bucket resource
filter()

Creates an iterable of all Bucket resources in the collection filtered by kwargs passed to method.

Request Syntax

bucket_iterator = s3.buckets.filter()
Return type:s3.Bucket
Returns:A Bucket resource
limit(**kwargs)

Creates an iterable up to a specified amount of Bucket resources in the collection.

Request Syntax

bucket_iterator = s3.buckets.limit()
Return type:s3.Bucket
Returns:A Bucket resource
page_size(**kwargs)

Creates an iterable of all Bucket resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

bucket_iterator = s3.buckets.page_size()
Return type:s3.Bucket
Returns:A Bucket resource

Bucket

class S3.Bucket(name)

A resource representing an Amazon Simple Storage Service (S3) Bucket:

import boto3

s3 = boto3.resource('s3')
bucket = s3.Bucket('name')
Parameters:name (string) -- The Bucket's name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available collections:

These are the resource's available waiters:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

name

(string) The Bucket's name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

creation_date

(datetime) Date the bucket was created.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load(*args, **kwargs)
create(**kwargs)

Creates a new bucket.

Request Syntax

response = bucket.create(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read',
    CreateBucketConfiguration={
        'LocationConstraint': 'EU'|'eu-west-1'|'us-west-1'|'us-west-2'|'ap-southeast-1'|'ap-southeast-2'|'ap-northeast-1'|'sa-east-1'|'cn-north-1'|'eu-central-1'
    },
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the bucket.
  • CreateBucketConfiguration (dict) --
    • LocationConstraint (string) -- Specifies the region where the bucket will be created. If you don't specify a region, the bucket will be created in US Standard.
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
Return type:

dict

Returns:

Response Syntax

{
    'Location': 'string'
}

Response Structure

  • (dict) --
    • Location (string) --

delete()

Deletes the bucket. All objects (including all object versions and Delete Markers) in the bucket must be deleted before the bucket itself can be deleted.

Request Syntax

response = bucket.delete()
Returns:None
delete_objects(**kwargs)

This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.

Request Syntax

response = bucket.delete_objects(
    Delete={
        'Objects': [
            {
                'Key': 'string',
                'VersionId': 'string'
            },
        ],
        'Quiet': True|False
    },
    MFA='string',
    RequestPayer='requester'
)
Parameters:
  • Delete (dict) --

    [REQUIRED]

    • Objects (list) -- [REQUIRED]
      • (dict) --
        • Key (string) -- [REQUIRED] Key name of the object to delete.
        • VersionId (string) -- VersionId for the specific version of the object to delete.
    • Quiet (boolean) -- Element to enable quiet mode for the request. When you add this element, you must set its value to true.
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Deleted': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'DeleteMarker': True|False,
            'DeleteMarkerVersionId': 'string'
        },
    ],
    'RequestCharged': 'requester',
    'Errors': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Deleted (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • DeleteMarker (boolean) --
        • DeleteMarkerVersionId (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • Errors (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • Code (string) --
        • Message (string) --

Calls s3.Client.list_buckets() to update the attributes of the Bucket resource.

put_object(**kwargs)

Adds an object to a bucket.

Request Syntax

object = bucket.put_object(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Body=b'bytes',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength=123,
    ContentMD5='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Key='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Body (bytes) -- Object data.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Key (string) -- [REQUIRED]
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

s3.Object

Returns:

A Object resource

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Acl()

Creates a BucketAcl resource.:

bucket_acl = bucket.Acl()
Return type:S3.BucketAcl
Returns:A BucketAcl resource
Cors()

Creates a BucketCors resource.:

bucket_cors = bucket.Cors()
Return type:S3.BucketCors
Returns:A BucketCors resource
Lifecycle()

Creates a BucketLifecycle resource.:

bucket_lifecycle = bucket.Lifecycle()
Return type:S3.BucketLifecycle
Returns:A BucketLifecycle resource
Logging()

Creates a BucketLogging resource.:

bucket_logging = bucket.Logging()
Return type:S3.BucketLogging
Returns:A BucketLogging resource
Notification()

Creates a BucketNotification resource.:

bucket_notification = bucket.Notification()
Return type:S3.BucketNotification
Returns:A BucketNotification resource
Object(key)

Creates a Object resource.:

object = bucket.Object('key')
Parameters:key (string) -- The Object's key identifier. This must be set.
Return type:S3.Object
Returns:A Object resource
Policy()

Creates a BucketPolicy resource.:

bucket_policy = bucket.Policy()
Return type:S3.BucketPolicy
Returns:A BucketPolicy resource
RequestPayment()

Creates a BucketRequestPayment resource.:

bucket_request_payment = bucket.RequestPayment()
Return type:S3.BucketRequestPayment
Returns:A BucketRequestPayment resource
Tagging()

Creates a BucketTagging resource.:

bucket_tagging = bucket.Tagging()
Return type:S3.BucketTagging
Returns:A BucketTagging resource
Versioning()

Creates a BucketVersioning resource.:

bucket_versioning = bucket.Versioning()
Return type:S3.BucketVersioning
Returns:A BucketVersioning resource
Website()

Creates a BucketWebsite resource.:

bucket_website = bucket.Website()
Return type:S3.BucketWebsite
Returns:A BucketWebsite resource

Collections

Collections provide an interface to iterate over and manipulate groups of resources. For more information about collections refer to the Resources Introduction Guide.

multipart_uploads
all()

Creates an iterable of all MultipartUpload resources in the collection.

Request Syntax

multipart_upload_iterator = bucket.multipart_uploads.all()
Return type:s3.MultipartUpload
Returns:A MultipartUpload resource
filter(**kwargs)

Creates an iterable of all MultipartUpload resources in the collection filtered by kwargs passed to method.

Request Syntax

multipart_upload_iterator = bucket.multipart_uploads.filter(
    Delimiter='string',
    EncodingType='url',
    KeyMarker='string',
    MaxUploads=123,
    Prefix='string',
    UploadIdMarker='string'
)
Parameters:
  • Delimiter (string) -- Character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • KeyMarker (string) -- Together with upload-id-marker, this parameter specifies the multipart upload after which listing should begin.
  • MaxUploads (integer) -- Sets the maximum number of multipart uploads, from 1 to 1,000, to return in the response body. 1,000 is the maximum number of uploads that can be returned in a response.
  • Prefix (string) -- Lists in-progress uploads only for those keys that begin with the specified prefix.
  • UploadIdMarker (string) -- Together with key-marker, specifies the multipart upload after which listing should begin. If key-marker is not specified, the upload-id-marker parameter is ignored.
Return type:

s3.MultipartUpload

Returns:

A MultipartUpload resource

limit(**kwargs)

Creates an iterable up to a specified amount of MultipartUpload resources in the collection.

Request Syntax

multipart_upload_iterator = bucket.multipart_uploads.limit(
    count=123
)
Parameters:count (integer) -- The limit to the number of resources in the iterable.
Return type:s3.MultipartUpload
Returns:A MultipartUpload resource
page_size(**kwargs)

Creates an iterable of all MultipartUpload resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

multipart_upload_iterator = bucket.multipart_uploads.page_size(
    count=123
)
Parameters:count (integer) -- The number of items returned by each service call
Return type:s3.MultipartUpload
Returns:A MultipartUpload resource
object_versions
all()

Creates an iterable of all ObjectVersion resources in the collection.

Request Syntax

object_version_iterator = bucket.object_versions.all()
Return type:s3.ObjectVersion
Returns:A ObjectVersion resource
delete(**kwargs)

This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.

Request Syntax

response = bucket.object_versions.delete(
    MFA='string',
    RequestPayer='requester'
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Deleted': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'DeleteMarker': True|False,
            'DeleteMarkerVersionId': 'string'
        },
    ],
    'RequestCharged': 'requester',
    'Errors': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Deleted (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • DeleteMarker (boolean) --
        • DeleteMarkerVersionId (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • Errors (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • Code (string) --
        • Message (string) --

filter(**kwargs)

Creates an iterable of all ObjectVersion resources in the collection filtered by kwargs passed to method.

Request Syntax

object_version_iterator = bucket.object_versions.filter(
    Delimiter='string',
    EncodingType='url',
    KeyMarker='string',
    MaxKeys=123,
    Prefix='string',
    VersionIdMarker='string'
)
Parameters:
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • KeyMarker (string) -- Specifies the key to start with when listing objects in a bucket.
  • MaxKeys (integer) -- Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
  • VersionIdMarker (string) -- Specifies the object version you want to start listing from.
Return type:

s3.ObjectVersion

Returns:

A ObjectVersion resource

limit(**kwargs)

Creates an iterable up to a specified amount of ObjectVersion resources in the collection.

Request Syntax

object_version_iterator = bucket.object_versions.limit(
    count=123
)
Parameters:count (integer) -- The limit to the number of resources in the iterable.
Return type:s3.ObjectVersion
Returns:A ObjectVersion resource
page_size(**kwargs)

Creates an iterable of all ObjectVersion resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

object_version_iterator = bucket.object_versions.page_size(
    count=123
)
Parameters:count (integer) -- The number of items returned by each service call
Return type:s3.ObjectVersion
Returns:A ObjectVersion resource
objects
all()

Creates an iterable of all ObjectSummary resources in the collection.

Request Syntax

object_summary_iterator = bucket.objects.all()
Return type:s3.ObjectSummary
Returns:A ObjectSummary resource
delete(**kwargs)

This operation enables you to delete multiple objects from a bucket using a single HTTP request. You may specify up to 1000 keys.

Request Syntax

response = bucket.objects.delete(
    MFA='string',
    RequestPayer='requester'
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Deleted': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'DeleteMarker': True|False,
            'DeleteMarkerVersionId': 'string'
        },
    ],
    'RequestCharged': 'requester',
    'Errors': [
        {
            'Key': 'string',
            'VersionId': 'string',
            'Code': 'string',
            'Message': 'string'
        },
    ]
}

Response Structure

  • (dict) --
    • Deleted (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • DeleteMarker (boolean) --
        • DeleteMarkerVersionId (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • Errors (list) --
      • (dict) --
        • Key (string) --
        • VersionId (string) --
        • Code (string) --
        • Message (string) --

filter(**kwargs)

Creates an iterable of all ObjectSummary resources in the collection filtered by kwargs passed to method.

Request Syntax

object_summary_iterator = bucket.objects.filter(
    Delimiter='string',
    EncodingType='url',
    Marker='string',
    MaxKeys=123,
    Prefix='string'
)
Parameters:
  • Delimiter (string) -- A delimiter is a character you use to group keys.
  • EncodingType (string) -- Requests Amazon S3 to encode the object keys in the response and specifies the encoding method to use. An object key may contain any Unicode character; however, XML 1.0 parser cannot parse some characters, such as characters with an ASCII value from 0 to 10. For characters that are not supported in XML 1.0, you can add this parameter to request that Amazon S3 encode the keys in the response.
  • Marker (string) -- Specifies the key to start with when listing objects in a bucket.
  • MaxKeys (integer) -- Sets the maximum number of keys returned in the response. The response might contain fewer keys but will never contain more.
  • Prefix (string) -- Limits the response to keys that begin with the specified prefix.
Return type:

s3.ObjectSummary

Returns:

A ObjectSummary resource

limit(**kwargs)

Creates an iterable up to a specified amount of ObjectSummary resources in the collection.

Request Syntax

object_summary_iterator = bucket.objects.limit(
    count=123
)
Parameters:count (integer) -- The limit to the number of resources in the iterable.
Return type:s3.ObjectSummary
Returns:A ObjectSummary resource
page_size(**kwargs)

Creates an iterable of all ObjectSummary resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

object_summary_iterator = bucket.objects.page_size(
    count=123
)
Parameters:count (integer) -- The number of items returned by each service call
Return type:s3.ObjectSummary
Returns:A ObjectSummary resource

Waiters

Waiters provide an interface to wait for a resource to reach a specific state. For more information about waiters refer to the Resources Introduction Guide.

wait_until_exists()

Waits until this Bucket is exists. This method calls S3.Waiter.bucket_exists.wait() which polls. S3.Client.head_bucket() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

bucket.wait_until_exists()
Returns:None
wait_until_not_exists()

Waits until this Bucket is not exists. This method calls S3.Waiter.bucket_not_exists.wait() which polls. S3.Client.head_bucket() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

bucket.wait_until_not_exists()
Returns:None

BucketAcl

class S3.BucketAcl(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketAcl:

import boto3

s3 = boto3.resource('s3')
bucket_acl = s3.BucketAcl('bucket_name')
Parameters:bucket_name (string) -- The BucketAcl's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketAcl's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

owner

(dict)

grants

(list) A list of grants.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load()

Calls s3.Client.get_bucket_acl() to update the attributes of the BucketAcl resource

Request Syntax

bucket_acl.load()
Returns:None
put(**kwargs)

Sets the permissions on a bucket using access control lists (ACL).

Request Syntax

response = bucket_acl.put(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read',
    AccessControlPolicy={
        'Grants': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'EmailAddress': 'string',
                    'ID': 'string',
                    'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    },
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the bucket.
  • AccessControlPolicy (dict) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- [REQUIRED] Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
Returns:

None

reload()

Calls s3.Client.get_bucket_acl() to update the attributes of the BucketAcl resource

Request Syntax

bucket_acl.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_acl.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketCors

class S3.BucketCors(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketCors:

import boto3

s3 = boto3.resource('s3')
bucket_cors = s3.BucketCors('bucket_name')
Parameters:bucket_name (string) -- The BucketCors's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketCors's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

cors_rules

(list)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete()

Deletes the cors configuration information set for the bucket.

Request Syntax

response = bucket_cors.delete()
Returns:None
load()

Calls s3.Client.get_bucket_cors() to update the attributes of the BucketCors resource

Request Syntax

bucket_cors.load()
Returns:None
put(**kwargs)

Sets the cors configuration for a bucket.

Request Syntax

response = bucket_cors.put(
    CORSConfiguration={
        'CORSRules': [
            {
                'AllowedHeaders': [
                    'string',
                ],
                'AllowedMethods': [
                    'string',
                ],
                'AllowedOrigins': [
                    'string',
                ],
                'ExposeHeaders': [
                    'string',
                ],
                'MaxAgeSeconds': 123
            },
        ]
    },

)
Parameters:CORSConfiguration (dict) --
  • CORSRules (list) --
    • (dict) --
      • AllowedHeaders (list) -- Specifies which headers are allowed in a pre-flight OPTIONS request.
        • (string) --
      • AllowedMethods (list) -- Identifies HTTP methods that the domain/origin specified in the rule is allowed to execute.
        • (string) --
      • AllowedOrigins (list) -- One or more origins you want customers to be able to access the bucket from.
        • (string) --
      • ExposeHeaders (list) -- One or more headers in the response that you want customers to be able to access from their applications (for example, from a JavaScript XMLHttpRequest object).
        • (string) --
      • MaxAgeSeconds (integer) -- The time in seconds that your browser is to cache the preflight response for the specified resource.
Returns:None
reload()

Calls s3.Client.get_bucket_cors() to update the attributes of the BucketCors resource

Request Syntax

bucket_cors.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_cors.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketLifecycle

class S3.BucketLifecycle(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketLifecycle:

import boto3

s3 = boto3.resource('s3')
bucket_lifecycle = s3.BucketLifecycle('bucket_name')
Parameters:bucket_name (string) -- The BucketLifecycle's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketLifecycle's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

rules

(list)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete()

Deletes the lifecycle configuration from the bucket.

Request Syntax

response = bucket_lifecycle.delete()
Returns:None
load()

Calls s3.Client.get_bucket_lifecycle() to update the attributes of the BucketLifecycle resource

Request Syntax

bucket_lifecycle.load()
Returns:None
put(**kwargs)

Sets lifecycle configuration for your bucket. If a lifecycle configuration exists, it replaces it.

Request Syntax

response = bucket_lifecycle.put(
    LifecycleConfiguration={
        'Rules': [
            {
                'Expiration': {
                    'Date': datetime(2015, 1, 1),
                    'Days': 123
                },
                'ID': 'string',
                'Prefix': 'string',
                'Status': 'Enabled'|'Disabled',
                'Transition': {
                    'Date': datetime(2015, 1, 1),
                    'Days': 123,
                    'StorageClass': 'GLACIER'
                },
                'NoncurrentVersionTransition': {
                    'NoncurrentDays': 123,
                    'StorageClass': 'GLACIER'
                },
                'NoncurrentVersionExpiration': {
                    'NoncurrentDays': 123
                }
            },
        ]
    }
)
Parameters:LifecycleConfiguration (dict) --
  • Rules (list) -- [REQUIRED]
    • (dict) --
      • Expiration (dict) --
        • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
        • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
      • ID (string) -- Unique identifier for the rule. The value cannot be longer than 255 characters.
      • Prefix (string) -- [REQUIRED] Prefix identifying one or more objects to which the rule applies.
      • Status (string) -- [REQUIRED] If 'Enabled', the rule is currently being applied. If 'Disabled', the rule is not currently being applied.
      • Transition (dict) --
        • Date (datetime) -- Indicates at what date the object is to be moved or deleted. Should be in GMT ISO 8601 Format.
        • Days (integer) -- Indicates the lifetime, in days, of the objects that are subject to the rule. The value must be a non-zero positive integer.
        • StorageClass (string) -- The class of storage used to store the object.
      • NoncurrentVersionTransition (dict) -- Container for the transition rule that describes when noncurrent objects transition to the GLACIER storage class. If your bucket is versioning-enabled (or versioning is suspended), you can set this action to request that Amazon S3 transition noncurrent object versions to the GLACIER storage class at a specific period in the object's lifetime.
        • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
        • StorageClass (string) -- The class of storage used to store the object.
      • NoncurrentVersionExpiration (dict) -- Specifies when noncurrent object versions expire. Upon expiration, Amazon S3 permanently deletes the noncurrent object versions. You set this lifecycle configuration action on a bucket that has versioning enabled (or suspended) to request that Amazon S3 delete noncurrent object versions at a specific period in the object's lifetime.
        • NoncurrentDays (integer) -- Specifies the number of days an object is noncurrent before Amazon S3 can perform the associated action. For information about the noncurrent days calculations, see How Amazon S3 Calculates When an Object Became Noncurrent in the Amazon Simple Storage Service Developer Guide.
Returns:None
reload()

Calls s3.Client.get_bucket_lifecycle() to update the attributes of the BucketLifecycle resource

Request Syntax

bucket_lifecycle.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_lifecycle.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketLogging

class S3.BucketLogging(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketLogging:

import boto3

s3 = boto3.resource('s3')
bucket_logging = s3.BucketLogging('bucket_name')
Parameters:bucket_name (string) -- The BucketLogging's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketLogging's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

logging_enabled

(dict)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load()

Calls s3.Client.get_bucket_logging() to update the attributes of the BucketLogging resource

Request Syntax

bucket_logging.load()
Returns:None
put(**kwargs)

Set the logging parameters for a bucket and to specify permissions for who can view and modify the logging parameters. To set the logging status of a bucket, you must be the bucket owner.

Request Syntax

response = bucket_logging.put(
    BucketLoggingStatus={
        'LoggingEnabled': {
            'TargetBucket': 'string',
            'TargetGrants': [
                {
                    'Grantee': {
                        'DisplayName': 'string',
                        'EmailAddress': 'string',
                        'ID': 'string',
                        'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                        'URI': 'string'
                    },
                    'Permission': 'FULL_CONTROL'|'READ'|'WRITE'
                },
            ],
            'TargetPrefix': 'string'
        }
    },

)
Parameters:BucketLoggingStatus (dict) --

[REQUIRED]

  • LoggingEnabled (dict) --
    • TargetBucket (string) -- Specifies the bucket where you want Amazon S3 to store server access logs. You can have your logs delivered to any bucket that you own, including the same bucket that is being logged. You can also configure multiple buckets to deliver their logs to the same target bucket. In this case you should choose a different TargetPrefix for each source bucket so that the delivered log files can be distinguished by key.
    • TargetGrants (list) --
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- [REQUIRED] Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Logging permissions assigned to the Grantee for the bucket.
    • TargetPrefix (string) -- This element lets you specify a prefix for the keys that the log files will be stored under.
Returns:None
reload()

Calls s3.Client.get_bucket_logging() to update the attributes of the BucketLogging resource

Request Syntax

bucket_logging.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_logging.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketNotification

class S3.BucketNotification(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketNotification:

import boto3

s3 = boto3.resource('s3')
bucket_notification = s3.BucketNotification('bucket_name')
Parameters:bucket_name (string) -- The BucketNotification's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketNotification's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

lambda_function_configurations

(list)

topic_configurations

(list)

queue_configurations

(list)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load()

Calls s3.Client.get_bucket_notification_configuration() to update the attributes of the BucketNotification resource

Request Syntax

bucket_notification.load()
Returns:None
put(**kwargs)

Enables notifications of specified events for a bucket.

Request Syntax

response = bucket_notification.put(
    NotificationConfiguration={
        'TopicConfigurations': [
            {
                'Id': 'string',
                'TopicArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ],
        'QueueConfigurations': [
            {
                'Id': 'string',
                'QueueArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ],
        'LambdaFunctionConfigurations': [
            {
                'Id': 'string',
                'LambdaFunctionArn': 'string',
                'Events': [
                    's3:ReducedRedundancyLostObject'|'s3:ObjectCreated:*'|'s3:ObjectCreated:Put'|'s3:ObjectCreated:Post'|'s3:ObjectCreated:Copy'|'s3:ObjectCreated:CompleteMultipartUpload'|'s3:ObjectRemoved:*'|'s3:ObjectRemoved:Delete'|'s3:ObjectRemoved:DeleteMarkerCreated',
                ]
            },
        ]
    }
)
Parameters:NotificationConfiguration (dict) --

[REQUIRED] Container for specifying the notification configuration of the bucket. If this element is empty, notifications are turned off on the bucket.

  • TopicConfigurations (list) --
    • (dict) -- Container for specifying the configuration when you want Amazon S3 to publish events to an Amazon Simple Notification Service (Amazon SNS) topic.
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • TopicArn (string) -- [REQUIRED] Amazon SNS topic ARN to which Amazon S3 will publish a message when it detects events of specified type.
      • Events (list) -- [REQUIRED]
        • (string) -- Bucket event for which to send notifications.
  • QueueConfigurations (list) --
    • (dict) -- Container for specifying an configuration when you want Amazon S3 to publish events to an Amazon Simple Queue Service (Amazon SQS) queue.
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • QueueArn (string) -- [REQUIRED] Amazon SQS queue ARN to which Amazon S3 will publish a message when it detects events of specified type.
      • Events (list) -- [REQUIRED]
        • (string) -- Bucket event for which to send notifications.
  • LambdaFunctionConfigurations (list) --
    • (dict) -- Container for specifying the AWS Lambda notification configuration.
      • Id (string) -- Optional unique identifier for configurations in a notification configuration. If you don't provide one, Amazon S3 will assign an ID.
      • LambdaFunctionArn (string) -- [REQUIRED] Lambda cloud function ARN that Amazon S3 can invoke when it detects events of the specified type.
      • Events (list) -- [REQUIRED]
        • (string) -- Bucket event for which to send notifications.
Returns:None
reload()

Calls s3.Client.get_bucket_notification_configuration() to update the attributes of the BucketNotification resource

Request Syntax

bucket_notification.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_notification.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketPolicy

class S3.BucketPolicy(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketPolicy:

import boto3

s3 = boto3.resource('s3')
bucket_policy = s3.BucketPolicy('bucket_name')
Parameters:bucket_name (string) -- The BucketPolicy's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketPolicy's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

policy

(string) The bucket policy as a JSON document.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete()

Deletes the policy from the bucket.

Request Syntax

response = bucket_policy.delete()
Returns:None
load()

Calls s3.Client.get_bucket_policy() to update the attributes of the BucketPolicy resource

Request Syntax

bucket_policy.load()
Returns:None
put(**kwargs)

Replaces a policy on a bucket. If the bucket already has a policy, the one in this request completely replaces it.

Request Syntax

response = bucket_policy.put(
    Policy='string'
)
Parameters:Policy (string) -- [REQUIRED] The bucket policy as a JSON document.
Returns:None
reload()

Calls s3.Client.get_bucket_policy() to update the attributes of the BucketPolicy resource

Request Syntax

bucket_policy.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_policy.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketRequestPayment

class S3.BucketRequestPayment(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketRequestPayment:

import boto3

s3 = boto3.resource('s3')
bucket_request_payment = s3.BucketRequestPayment('bucket_name')
Parameters:bucket_name (string) -- The BucketRequestPayment's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketRequestPayment's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

payer

(string) Specifies who pays for the download and request fees.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load()

Calls s3.Client.get_bucket_request_payment() to update the attributes of the BucketRequestPayment resource

Request Syntax

bucket_request_payment.load()
Returns:None
put(**kwargs)

Sets the request payment configuration for a bucket. By default, the bucket owner pays for downloads from the bucket. This configuration parameter enables the bucket owner (only) to specify that the person requesting the download will be charged for the download. Documentation on requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/RequesterPaysBuckets.html

Request Syntax

response = bucket_request_payment.put(
    RequestPaymentConfiguration={
        'Payer': 'Requester'|'BucketOwner'
    }
)
Parameters:RequestPaymentConfiguration (dict) --

[REQUIRED]

  • Payer (string) -- [REQUIRED] Specifies who pays for the download and request fees.
Returns:None
reload()

Calls s3.Client.get_bucket_request_payment() to update the attributes of the BucketRequestPayment resource

Request Syntax

bucket_request_payment.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_request_payment.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketTagging

class S3.BucketTagging(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketTagging:

import boto3

s3 = boto3.resource('s3')
bucket_tagging = s3.BucketTagging('bucket_name')
Parameters:bucket_name (string) -- The BucketTagging's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketTagging's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

tag_set

(list)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete()

Deletes the tags from the bucket.

Request Syntax

response = bucket_tagging.delete()
Returns:None
load()

Calls s3.Client.get_bucket_tagging() to update the attributes of the BucketTagging resource

Request Syntax

bucket_tagging.load()
Returns:None
put(**kwargs)

Sets the tags for a bucket.

Request Syntax

response = bucket_tagging.put(
    Tagging={
        'TagSet': [
            {
                'Key': 'string',
                'Value': 'string'
            },
        ]
    }
)
Parameters:Tagging (dict) --

[REQUIRED]

  • TagSet (list) -- [REQUIRED]
    • (dict) --
      • Key (string) -- [REQUIRED] Name of the tag.
      • Value (string) -- [REQUIRED] Value of the tag.
Returns:None
reload()

Calls s3.Client.get_bucket_tagging() to update the attributes of the BucketTagging resource

Request Syntax

bucket_tagging.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_tagging.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketVersioning

class S3.BucketVersioning(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketVersioning:

import boto3

s3 = boto3.resource('s3')
bucket_versioning = s3.BucketVersioning('bucket_name')
Parameters:bucket_name (string) -- The BucketVersioning's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketVersioning's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

status

(string) The versioning state of the bucket.

mfa_delete

(string) Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

enable(**kwargs)

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Request Syntax

response = bucket_versioning.enable(
    MFA='string',

)
Parameters:MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
Returns:None
load()

Calls s3.Client.get_bucket_versioning() to update the attributes of the BucketVersioning resource

Request Syntax

bucket_versioning.load()
Returns:None
put(**kwargs)

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Request Syntax

response = bucket_versioning.put(
    MFA='string',
    VersioningConfiguration={
        'MFADelete': 'Enabled'|'Disabled',
        'Status': 'Enabled'|'Suspended'
    }
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • VersioningConfiguration (dict) --

    [REQUIRED]

    • MFADelete (string) -- Specifies whether MFA delete is enabled in the bucket versioning configuration. This element is only returned if the bucket has been configured with MFA delete. If the bucket has never been so configured, this element is not returned.
    • Status (string) -- The versioning state of the bucket.
Returns:

None

reload()

Calls s3.Client.get_bucket_versioning() to update the attributes of the BucketVersioning resource

Request Syntax

bucket_versioning.reload()
Returns:None
suspend(**kwargs)

Sets the versioning state of an existing bucket. To set the versioning state, you must be the bucket owner.

Request Syntax

response = bucket_versioning.suspend(
    MFA='string',

)
Parameters:MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_versioning.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

BucketWebsite

class S3.BucketWebsite(bucket_name)

A resource representing an Amazon Simple Storage Service (S3) BucketWebsite:

import boto3

s3 = boto3.resource('s3')
bucket_website = s3.BucketWebsite('bucket_name')
Parameters:bucket_name (string) -- The BucketWebsite's bucket_name identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The BucketWebsite's bucket_name identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

routing_rules

(list)

redirect_all_requests_to

(dict)

error_document

(dict)

index_document

(dict)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete()

This operation removes the website configuration from the bucket.

Request Syntax

response = bucket_website.delete()
Returns:None
load()

Calls s3.Client.get_bucket_website() to update the attributes of the BucketWebsite resource

Request Syntax

bucket_website.load()
Returns:None
put(**kwargs)

Set the website configuration for a bucket.

Request Syntax

response = bucket_website.put(
    WebsiteConfiguration={
        'ErrorDocument': {
            'Key': 'string'
        },
        'IndexDocument': {
            'Suffix': 'string'
        },
        'RedirectAllRequestsTo': {
            'HostName': 'string',
            'Protocol': 'http'|'https'
        },
        'RoutingRules': [
            {
                'Condition': {
                    'HttpErrorCodeReturnedEquals': 'string',
                    'KeyPrefixEquals': 'string'
                },
                'Redirect': {
                    'HostName': 'string',
                    'HttpRedirectCode': 'string',
                    'Protocol': 'http'|'https',
                    'ReplaceKeyPrefixWith': 'string',
                    'ReplaceKeyWith': 'string'
                }
            },
        ]
    }
)
Parameters:WebsiteConfiguration (dict) --

[REQUIRED]

  • ErrorDocument (dict) --
    • Key (string) -- [REQUIRED] The object key name to use when a 4XX class error occurs.
  • IndexDocument (dict) --
    • Suffix (string) -- [REQUIRED] A suffix that is appended to a request that is for a directory on the website endpoint (e.g. if the suffix is index.html and you make a request to samplebucket/images/ the data that is returned will be for the object with the key name images/index.html) The suffix must not be empty and must not include a slash character.
  • RedirectAllRequestsTo (dict) --
    • HostName (string) -- [REQUIRED] Name of the host where requests will be redirected.
    • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
  • RoutingRules (list) --
    • (dict) --
      • Condition (dict) -- A container for describing a condition that must be met for the specified redirect to apply. For example, 1. If request is for pages in the /docs folder, redirect to the /documents folder. 2. If request results in HTTP error 4xx, redirect request to another host where you might process the error.
        • HttpErrorCodeReturnedEquals (string) -- The HTTP error code when the redirect is applied. In the event of an error, if the error code equals this value, then the specified redirect is applied. Required when parent element Condition is specified and sibling KeyPrefixEquals is not specified. If both are specified, then both must be true for the redirect to be applied.
        • KeyPrefixEquals (string) -- The object key name prefix when the redirect is applied. For example, to redirect requests for ExamplePage.html, the key prefix will be ExamplePage.html. To redirect request for all pages with the prefix docs/, the key prefix will be /docs, which identifies all objects in the docs/ folder. Required when the parent element Condition is specified and sibling HttpErrorCodeReturnedEquals is not specified. If both conditions are specified, both must be true for the redirect to be applied.
      • Redirect (dict) -- [REQUIRED] Container for redirect information. You can redirect requests to another host, to another page, or with another protocol. In the event of an error, you can can specify a different error code to return.
        • HostName (string) -- The host name to use in the redirect request.
        • HttpRedirectCode (string) -- The HTTP redirect code to use on the response. Not required if one of the siblings is present.
        • Protocol (string) -- Protocol to use (http, https) when redirecting requests. The default is the protocol that is used in the original request.
        • ReplaceKeyPrefixWith (string) -- The object key prefix to use in the redirect request. For example, to redirect requests for all pages with prefix docs/ (objects in the docs/ folder) to documents/, you can set a condition block with KeyPrefixEquals set to docs/ and in the Redirect set ReplaceKeyPrefixWith to /documents. Not required if one of the siblings is present. Can be present only if ReplaceKeyWith is not provided.
        • ReplaceKeyWith (string) -- The specific object key to use in the redirect request. For example, redirect request to error.html. Not required if one of the sibling is present. Can be present only if ReplaceKeyPrefixWith is not provided.
Returns:None
reload()

Calls s3.Client.get_bucket_website() to update the attributes of the BucketWebsite resource

Request Syntax

bucket_website.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Bucket()

Creates a Bucket resource.:

bucket = bucket_website.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource

MultipartUpload

class S3.MultipartUpload(bucket_name, object_key, id)

A resource representing an Amazon Simple Storage Service (S3) MultipartUpload:

import boto3

s3 = boto3.resource('s3')
multipart_upload = s3.MultipartUpload('bucket_name','object_key','id')
Parameters:
  • bucket_name (string) -- The MultipartUpload's bucket_name identifier. This must be set.
  • object_key (string) -- The MultipartUpload's object_key identifier. This must be set.
  • id (string) -- The MultipartUpload's id identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available collections:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The MultipartUpload's bucket_name identifier. This must be set.

object_key

(string) The MultipartUpload's object_key identifier. This must be set.

id

(string) The MultipartUpload's id identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

initiator

(dict) Identifies who initiated the multipart upload.

initiated

(datetime) Date and time at which the multipart upload was initiated.

storage_class

(string) The class of storage used to store the object.

upload_id

(string) Upload ID that identifies the multipart upload.

key

(string) Key of the object for which the multipart upload was initiated.

owner

(dict)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

abort(**kwargs)

Aborts a multipart upload.

To verify that all parts have been removed, so you don't get charged for the part storage, you should call the List Parts operation and ensure the parts list is empty.

Request Syntax

response = multipart_upload.abort(
    RequestPayer='requester'
)
Parameters:RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:dict
Returns:Response Syntax
{
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
complete(**kwargs)

Completes a multipart upload by assembling previously uploaded parts.

Request Syntax

object = multipart_upload.complete(
    MultipartUpload={
        'Parts': [
            {
                'ETag': 'string',
                'PartNumber': 123
            },
        ]
    },
    RequestPayer='requester'
)
Parameters:
  • MultipartUpload (dict) --
    • Parts (list) --
      • (dict) --
        • ETag (string) -- Entity tag returned when the part was uploaded.
        • PartNumber (integer) -- Part number that identifies the part. This is a positive integer between 1 and 10,000.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

s3.Object

Returns:

A Object resource

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Object()

Creates a Object resource.:

object = multipart_upload.Object()
Return type:S3.Object
Returns:A Object resource
Part(part_number)

Creates a MultipartUploadPart resource.:

multipart_upload_part = multipart_upload.Part('part_number')
Parameters:part_number (string) -- The Part's part_number identifier. This must be set.
Return type:S3.MultipartUploadPart
Returns:A MultipartUploadPart resource

Collections

Collections provide an interface to iterate over and manipulate groups of resources. For more information about collections refer to the Resources Introduction Guide.

parts
all()

Creates an iterable of all MultipartUploadPart resources in the collection.

Request Syntax

multipart_upload_part_iterator = multipart_upload.parts.all()
Return type:s3.MultipartUploadPart
Returns:A MultipartUploadPart resource
filter(**kwargs)

Creates an iterable of all MultipartUploadPart resources in the collection filtered by kwargs passed to method.

Request Syntax

multipart_upload_part_iterator = multipart_upload.parts.filter(
    MaxParts=123,
    PartNumberMarker=123,
    RequestPayer='requester'
)
Parameters:
  • MaxParts (integer) -- Sets the maximum number of parts to return.
  • PartNumberMarker (integer) -- Specifies the part after which listing should begin. Only parts with higher part numbers will be listed.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

s3.MultipartUploadPart

Returns:

A MultipartUploadPart resource

limit(**kwargs)

Creates an iterable up to a specified amount of MultipartUploadPart resources in the collection.

Request Syntax

multipart_upload_part_iterator = multipart_upload.parts.limit(
    count=123
)
Parameters:count (integer) -- The limit to the number of resources in the iterable.
Return type:s3.MultipartUploadPart
Returns:A MultipartUploadPart resource
page_size(**kwargs)

Creates an iterable of all MultipartUploadPart resources in the collection, but limits the number of items returned by each service call by the specified amount.

Request Syntax

multipart_upload_part_iterator = multipart_upload.parts.page_size(
    count=123
)
Parameters:count (integer) -- The number of items returned by each service call
Return type:s3.MultipartUploadPart
Returns:A MultipartUploadPart resource

MultipartUploadPart

class S3.MultipartUploadPart(bucket_name, object_key, multipart_upload_id, part_number)

A resource representing an Amazon Simple Storage Service (S3) MultipartUploadPart:

import boto3

s3 = boto3.resource('s3')
multipart_upload_part = s3.MultipartUploadPart('bucket_name','object_key','multipart_upload_id','part_number')
Parameters:
  • bucket_name (string) -- The MultipartUploadPart's bucket_name identifier. This must be set.
  • object_key (string) -- The MultipartUploadPart's object_key identifier. This must be set.
  • multipart_upload_id (string) -- The MultipartUploadPart's multipart_upload_id identifier. This must be set.
  • part_number (string) -- The MultipartUploadPart's part_number identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The MultipartUploadPart's bucket_name identifier. This must be set.

object_key

(string) The MultipartUploadPart's object_key identifier. This must be set.

multipart_upload_id

(string) The MultipartUploadPart's multipart_upload_id identifier. This must be set.

part_number

(string) The MultipartUploadPart's part_number identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

last_modified

(datetime) Date and time at which the part was uploaded.

e_tag

(string) Entity tag returned when the part was uploaded.

size

(integer) Size of the uploaded part data.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

copy_from(**kwargs)

Uploads a part by copying data from an existing object as data source.

Request Syntax

response = multipart_upload_part.copy_from(
    CopySource='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince=datetime(2015, 1, 1),
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince=datetime(2015, 1, 1),
    CopySourceRange='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    CopySourceSSECustomerAlgorithm='string',
    CopySourceSSECustomerKey='string',
    CopySourceSSECustomerKeyMD5='string',
    RequestPayer='requester'
)
Parameters:
  • CopySource (string) -- [REQUIRED] The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
  • CopySourceIfMatch (string) -- Copies the object if its entity tag (ETag) matches the specified tag.
  • CopySourceIfModifiedSince (datetime) -- Copies the object if it has been modified since the specified time.
  • CopySourceIfNoneMatch (string) -- Copies the object if its entity tag (ETag) is different than the specified ETag.
  • CopySourceIfUnmodifiedSince (datetime) -- Copies the object if it hasn't been modified since the specified time.
  • CopySourceRange (string) -- The range of bytes to copy from the source object. The range value must use the form bytes=first-last, where the first and last are the zero-based byte offsets to copy. For example, bytes=0-9 indicates that you want to copy the first ten bytes of the source. You can copy a range only if the source object is greater than 5 GB.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • CopySourceSSECustomerAlgorithm (string) -- Specifies the algorithm to use when decrypting the source object (e.g., AES256).
  • CopySourceSSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
  • CopySourceSSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'CopySourceVersionId': 'string',
    'CopyPartResult': {
        'ETag': 'string',
        'LastModified': datetime(2015, 1, 1)
    },
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • CopySourceVersionId (string) -- The version of the source object that was copied, if you have enabled versioning on the source bucket.
    • CopyPartResult (dict) --
      • ETag (string) -- Entity tag of the object.
      • LastModified (datetime) -- Date and time at which the object was uploaded.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

upload(**kwargs)

Uploads a part in a multipart upload.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Request Syntax

response = multipart_upload_part.upload(
    Body=b'bytes',
    ContentLength=123,
    ContentMD5='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • Body (bytes) --
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header. This must be the same encryption key specified in the initiate multipart upload request.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'ETag': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • ETag (string) -- Entity tag for the uploaded object.
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

MultipartUpload()

Creates a MultipartUpload resource.:

multipart_upload = multipart_upload_part.MultipartUpload()
Return type:S3.MultipartUpload
Returns:A MultipartUpload resource

Object

class S3.Object(bucket_name, key)

A resource representing an Amazon Simple Storage Service (S3) Object:

import boto3

s3 = boto3.resource('s3')
object = s3.Object('bucket_name','key')
Parameters:
  • bucket_name (string) -- The Object's bucket_name identifier. This must be set.
  • key (string) -- The Object's key identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available waiters:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The Object's bucket_name identifier. This must be set.

key

(string) The Object's key identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

content_length

(integer) Size of the body in bytes.

restore

(string) Provides information about object restoration operation and expiration time of the restored object copy.

sse_customer_key_md5

(string) If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.

content_language

(string) The language the content is in.

replication_status

(string)

server_side_encryption

(string) The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).

sse_customer_algorithm

(string) If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.

missing_meta

(integer) This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.

delete_marker

(boolean) Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.

content_encoding

(string) Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.

content_disposition

(string) Specifies presentational information for the object.

cache_control

(string) Specifies caching behavior along the request/reply chain.

metadata

(dict) A map of metadata to store with the object in S3.

request_charged

(string) If present, indicates that the requester was successfully charged for the request.

e_tag

(string) An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL

expires

(datetime) The date and time at which the object is no longer cacheable.

version_id

(string) Version of the object.

last_modified

(datetime) Last modified date of the object

content_type

(string) A standard MIME type describing the format of the object data.

website_redirect_location

(string) If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.

ssekms_key_id

(string) If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.

accept_ranges

(string)

storage_class

(string)

expiration

(string) If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

copy_from(**kwargs)

Creates a copy of an object that is already stored in Amazon S3.

Request Syntax

response = object.copy_from(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    CopySource='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince=datetime(2015, 1, 1),
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince=datetime(2015, 1, 1),
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    MetadataDirective='COPY'|'REPLACE',
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    CopySourceSSECustomerAlgorithm='string',
    CopySourceSSECustomerKey='string',
    CopySourceSSECustomerKeyMD5='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • CopySource (string) -- [REQUIRED] The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
  • CopySourceIfMatch (string) -- Copies the object if its entity tag (ETag) matches the specified tag.
  • CopySourceIfModifiedSince (datetime) -- Copies the object if it has been modified since the specified time.
  • CopySourceIfNoneMatch (string) -- Copies the object if its entity tag (ETag) is different than the specified ETag.
  • CopySourceIfUnmodifiedSince (datetime) -- Copies the object if it hasn't been modified since the specified time.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • MetadataDirective (string) -- Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • CopySourceSSECustomerAlgorithm (string) -- Specifies the algorithm to use when decrypting the source object (e.g., AES256).
  • CopySourceSSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
  • CopySourceSSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'CopyObjectResult': {
        'ETag': 'string',
        'LastModified': datetime(2015, 1, 1)
    },
    'Expiration': 'string',
    'CopySourceVersionId': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • CopyObjectResult (dict) --
      • ETag (string) --
      • LastModified (datetime) --
    • Expiration (string) -- If the object expiration is configured, the response includes this header.
    • CopySourceVersionId (string) --
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

delete(**kwargs)

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

Request Syntax

response = object.delete(
    MFA='string',
    VersionId='string',
    RequestPayer='requester'
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'VersionId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
    • VersionId (string) -- Returns the version ID of the delete marker created as a result of the DELETE operation.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

get(**kwargs)

Retrieves objects from Amazon S3.

Request Syntax

response = object.get(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires=datetime(2015, 1, 1),
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • ResponseCacheControl (string) -- Sets the Cache-Control header of the response.
  • ResponseContentDisposition (string) -- Sets the Content-Disposition header of the response
  • ResponseContentEncoding (string) -- Sets the Content-Encoding header of the response.
  • ResponseContentLanguage (string) -- Sets the Content-Language header of the response.
  • ResponseContentType (string) -- Sets the Content-Type header of the response.
  • ResponseExpires (datetime) -- Sets the Expires header of the response.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Body': b'bytes',
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentRange': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • Body (bytes) -- Object data.
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentRange (string) -- The portion of the object returned in the response.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

initiate_multipart_upload(**kwargs)

Initiates a multipart upload and returns an upload ID.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Request Syntax

multipart_upload = object.initiate_multipart_upload(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

s3.MultipartUpload

Returns:

A MultipartUpload resource

load()

Calls s3.Client.head_object() to update the attributes of the Object resource

Request Syntax

object.load()
Returns:None
put(**kwargs)

Adds an object to a bucket.

Request Syntax

response = object.put(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Body=b'bytes',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength=123,
    ContentMD5='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Body (bytes) -- Object data.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Expiration': 'string',
    'ETag': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'VersionId': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Expiration (string) -- If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
    • ETag (string) -- Entity tag for the uploaded object.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • VersionId (string) -- Version of the object.
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

reload()

Calls s3.Client.head_object() to update the attributes of the Object resource

Request Syntax

object.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Acl()

Creates a ObjectAcl resource.:

object_acl = object.Acl()
Return type:S3.ObjectAcl
Returns:A ObjectAcl resource
Bucket()

Creates a Bucket resource.:

bucket = object.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource
MultipartUpload(id)

Creates a MultipartUpload resource.:

multipart_upload = object.MultipartUpload('id')
Parameters:id (string) -- The MultipartUpload's id identifier. This must be set.
Return type:S3.MultipartUpload
Returns:A MultipartUpload resource
Version(id)

Creates a ObjectVersion resource.:

object_version = object.Version('id')
Parameters:id (string) -- The Version's id identifier. This must be set.
Return type:S3.ObjectVersion
Returns:A ObjectVersion resource

Waiters

Waiters provide an interface to wait for a resource to reach a specific state. For more information about waiters refer to the Resources Introduction Guide.

wait_until_exists(**kwargs)

Waits until this Object is exists. This method calls S3.Waiter.object_exists.wait() which polls. S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

object.wait_until_exists(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

wait_until_not_exists(**kwargs)

Waits until this Object is not exists. This method calls S3.Waiter.object_not_exists.wait() which polls. S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

object.wait_until_not_exists(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

ObjectAcl

class S3.ObjectAcl(bucket_name, object_key)

A resource representing an Amazon Simple Storage Service (S3) ObjectAcl:

import boto3

s3 = boto3.resource('s3')
object_acl = s3.ObjectAcl('bucket_name','object_key')
Parameters:
  • bucket_name (string) -- The ObjectAcl's bucket_name identifier. This must be set.
  • object_key (string) -- The ObjectAcl's object_key identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The ObjectAcl's bucket_name identifier. This must be set.

object_key

(string) The ObjectAcl's object_key identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

owner

(dict)

request_charged

(string) If present, indicates that the requester was successfully charged for the request.

grants

(list) A list of grants.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

load()

Calls s3.Client.get_object_acl() to update the attributes of the ObjectAcl resource

Request Syntax

object_acl.load()
Returns:None
put(**kwargs)

uses the acl subresource to set the access control list (ACL) permissions for an object that already exists in a bucket

Request Syntax

response = object_acl.put(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    AccessControlPolicy={
        'Grants': [
            {
                'Grantee': {
                    'DisplayName': 'string',
                    'EmailAddress': 'string',
                    'ID': 'string',
                    'Type': 'CanonicalUser'|'AmazonCustomerByEmail'|'Group',
                    'URI': 'string'
                },
                'Permission': 'FULL_CONTROL'|'WRITE'|'WRITE_ACP'|'READ'|'READ_ACP'
            },
        ],
        'Owner': {
            'DisplayName': 'string',
            'ID': 'string'
        }
    },
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWrite='string',
    GrantWriteACP='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • AccessControlPolicy (dict) --
    • Grants (list) -- A list of grants.
      • (dict) --
        • Grantee (dict) --
          • DisplayName (string) -- Screen name of the grantee.
          • EmailAddress (string) -- Email address of the grantee.
          • ID (string) -- The canonical user ID of the grantee.
          • Type (string) -- [REQUIRED] Type of grantee
          • URI (string) -- URI of the grantee group.
        • Permission (string) -- Specifies the permission given to the grantee.
    • Owner (dict) --
      • DisplayName (string) --
      • ID (string) --
  • GrantFullControl (string) -- Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.
  • GrantRead (string) -- Allows grantee to list the objects in the bucket.
  • GrantReadACP (string) -- Allows grantee to read the bucket ACL.
  • GrantWrite (string) -- Allows grantee to create, overwrite, and delete any object in the bucket.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable bucket.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

reload()

Calls s3.Client.get_object_acl() to update the attributes of the ObjectAcl resource

Request Syntax

object_acl.reload()
Returns:None

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Object()

Creates a Object resource.:

object = object_acl.Object()
Return type:S3.Object
Returns:A Object resource

ObjectSummary

class S3.ObjectSummary(bucket_name, key)

A resource representing an Amazon Simple Storage Service (S3) ObjectSummary:

import boto3

s3 = boto3.resource('s3')
object_summary = s3.ObjectSummary('bucket_name','key')
Parameters:
  • bucket_name (string) -- The ObjectSummary's bucket_name identifier. This must be set.
  • key (string) -- The ObjectSummary's key identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

These are the resource's available waiters:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The ObjectSummary's bucket_name identifier. This must be set.

key

(string) The ObjectSummary's key identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

owner

(dict)

last_modified

(datetime)

e_tag

(string)

storage_class

(string) The class of storage used to store the object.

size

(integer)

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

copy_from(**kwargs)

Creates a copy of an object that is already stored in Amazon S3.

Request Syntax

response = object_summary.copy_from(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    CopySource='string',
    CopySourceIfMatch='string',
    CopySourceIfModifiedSince=datetime(2015, 1, 1),
    CopySourceIfNoneMatch='string',
    CopySourceIfUnmodifiedSince=datetime(2015, 1, 1),
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    MetadataDirective='COPY'|'REPLACE',
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    CopySourceSSECustomerAlgorithm='string',
    CopySourceSSECustomerKey='string',
    CopySourceSSECustomerKeyMD5='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • CopySource (string) -- [REQUIRED] The name of the source bucket and key name of the source object, separated by a slash (/). Must be URL-encoded.
  • CopySourceIfMatch (string) -- Copies the object if its entity tag (ETag) matches the specified tag.
  • CopySourceIfModifiedSince (datetime) -- Copies the object if it has been modified since the specified time.
  • CopySourceIfNoneMatch (string) -- Copies the object if its entity tag (ETag) is different than the specified ETag.
  • CopySourceIfUnmodifiedSince (datetime) -- Copies the object if it hasn't been modified since the specified time.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • MetadataDirective (string) -- Specifies whether the metadata is copied from the source object or replaced with metadata provided in the request.
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • CopySourceSSECustomerAlgorithm (string) -- Specifies the algorithm to use when decrypting the source object (e.g., AES256).
  • CopySourceSSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use to decrypt the source object. The encryption key provided in this header must be one that was used when the source object was created.
  • CopySourceSSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'CopyObjectResult': {
        'ETag': 'string',
        'LastModified': datetime(2015, 1, 1)
    },
    'Expiration': 'string',
    'CopySourceVersionId': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • CopyObjectResult (dict) --
      • ETag (string) --
      • LastModified (datetime) --
    • Expiration (string) -- If the object expiration is configured, the response includes this header.
    • CopySourceVersionId (string) --
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

delete(**kwargs)

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

Request Syntax

response = object_summary.delete(
    MFA='string',
    VersionId='string',
    RequestPayer='requester'
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'VersionId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
    • VersionId (string) -- Returns the version ID of the delete marker created as a result of the DELETE operation.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

get(**kwargs)

Retrieves objects from Amazon S3.

Request Syntax

response = object_summary.get(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires=datetime(2015, 1, 1),
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • ResponseCacheControl (string) -- Sets the Cache-Control header of the response.
  • ResponseContentDisposition (string) -- Sets the Content-Disposition header of the response
  • ResponseContentEncoding (string) -- Sets the Content-Encoding header of the response.
  • ResponseContentLanguage (string) -- Sets the Content-Language header of the response.
  • ResponseContentType (string) -- Sets the Content-Type header of the response.
  • ResponseExpires (datetime) -- Sets the Expires header of the response.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Body': b'bytes',
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentRange': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • Body (bytes) -- Object data.
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentRange (string) -- The portion of the object returned in the response.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

initiate_multipart_upload(**kwargs)

Initiates a multipart upload and returns an upload ID.

Note: After you initiate multipart upload and upload one or more parts, you must either complete or abort multipart upload in order to stop getting charged for storage of the uploaded parts. Only after you either complete or abort multipart upload, Amazon S3 frees up the parts storage and stops charging you for the parts storage.

Request Syntax

multipart_upload = object_summary.initiate_multipart_upload(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

s3.MultipartUpload

Returns:

A MultipartUpload resource

put(**kwargs)

Adds an object to a bucket.

Request Syntax

response = object_summary.put(
    ACL='private'|'public-read'|'public-read-write'|'authenticated-read'|'bucket-owner-read'|'bucket-owner-full-control',
    Body=b'bytes',
    CacheControl='string',
    ContentDisposition='string',
    ContentEncoding='string',
    ContentLanguage='string',
    ContentLength=123,
    ContentMD5='string',
    ContentType='string',
    Expires=datetime(2015, 1, 1),
    GrantFullControl='string',
    GrantRead='string',
    GrantReadACP='string',
    GrantWriteACP='string',
    Metadata={
        'string': 'string'
    },
    ServerSideEncryption='AES256'|'aws:kms',
    StorageClass='STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    WebsiteRedirectLocation='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    SSEKMSKeyId='string',
    RequestPayer='requester'
)
Parameters:
  • ACL (string) -- The canned ACL to apply to the object.
  • Body (bytes) -- Object data.
  • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
  • ContentDisposition (string) -- Specifies presentational information for the object.
  • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
  • ContentLanguage (string) -- The language the content is in.
  • ContentLength (integer) -- Size of the body in bytes. This parameter is useful when the size of the body cannot be determined automatically.
  • ContentMD5 (string) --
  • ContentType (string) -- A standard MIME type describing the format of the object data.
  • Expires (datetime) -- The date and time at which the object is no longer cacheable.
  • GrantFullControl (string) -- Gives the grantee READ, READ_ACP, and WRITE_ACP permissions on the object.
  • GrantRead (string) -- Allows grantee to read the object data and its metadata.
  • GrantReadACP (string) -- Allows grantee to read the object ACL.
  • GrantWriteACP (string) -- Allows grantee to write the ACL for the applicable object.
  • Metadata (dict) --

    A map of metadata to store with the object in S3.

    • (string) --
      • (string) --
  • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
  • StorageClass (string) -- The type of storage to use for the object. Defaults to 'STANDARD'.
  • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • SSEKMSKeyId (string) -- Specifies the AWS KMS key ID to use for object encryption. All GET and PUT requests for an object protected by AWS KMS will fail if not made via SSL or using SigV4. Documentation on configuring any of the officially supported AWS SDKs and CLI can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/UsingAWSSDK.html#specify-signature-version
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Expiration': 'string',
    'ETag': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'VersionId': 'string',
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • Expiration (string) -- If the object expiration is configured, this will contain the expiration date (expiry-date) and rule ID (rule-id). The value of rule-id is URL encoded.
    • ETag (string) -- Entity tag for the uploaded object.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • VersionId (string) -- Version of the object.
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Acl()

Creates a ObjectAcl resource.:

object_acl = object_summary.Acl()
Return type:S3.ObjectAcl
Returns:A ObjectAcl resource
Bucket()

Creates a Bucket resource.:

bucket = object_summary.Bucket()
Return type:S3.Bucket
Returns:A Bucket resource
MultipartUpload(id)

Creates a MultipartUpload resource.:

multipart_upload = object_summary.MultipartUpload('id')
Parameters:id (string) -- The MultipartUpload's id identifier. This must be set.
Return type:S3.MultipartUpload
Returns:A MultipartUpload resource
Object()

Creates a Object resource.:

object = object_summary.Object()
Return type:S3.Object
Returns:A Object resource
Version(id)

Creates a ObjectVersion resource.:

object_version = object_summary.Version('id')
Parameters:id (string) -- The Version's id identifier. This must be set.
Return type:S3.ObjectVersion
Returns:A ObjectVersion resource

Waiters

Waiters provide an interface to wait for a resource to reach a specific state. For more information about waiters refer to the Resources Introduction Guide.

wait_until_exists(**kwargs)

Waits until this ObjectSummary is exists. This method calls S3.Waiter.object_exists.wait() which polls. S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

object_summary.wait_until_exists(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

wait_until_not_exists(**kwargs)

Waits until this ObjectSummary is not exists. This method calls S3.Waiter.object_not_exists.wait() which polls. S3.Client.head_object() every 5 seconds until a successful state is reached. An error is returned after 20 failed checks.

Request Syntax

object_summary.wait_until_not_exists(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    VersionId='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • VersionId (string) -- VersionId used to reference a specific version of the object.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

ObjectVersion

class S3.ObjectVersion(bucket_name, object_key, id)

A resource representing an Amazon Simple Storage Service (S3) ObjectVersion:

import boto3

s3 = boto3.resource('s3')
object_version = s3.ObjectVersion('bucket_name','object_key','id')
Parameters:
  • bucket_name (string) -- The ObjectVersion's bucket_name identifier. This must be set.
  • object_key (string) -- The ObjectVersion's object_key identifier. This must be set.
  • id (string) -- The ObjectVersion's id identifier. This must be set.

These are the resource's available identifiers:

These are the resource's available attributes:

These are the resource's available actions:

These are the resource's available sub-resources:

Identifiers

Identifiers are properties of a resource that are set upon instantation of the resource. For more information about identifiers refer to the Resources Introduction Guide.

bucket_name

(string) The ObjectVersion's bucket_name identifier. This must be set.

object_key

(string) The ObjectVersion's object_key identifier. This must be set.

id

(string) The ObjectVersion's id identifier. This must be set.

Attributes

Attributes provide access to the properties of a resource. Attributes are lazy-loaded the first time one is accessed via the load() method. For more information about attributes refer to the Resources Introduction Guide.

e_tag

(string)

last_modified

(datetime) Date and time the object was last modified.

version_id

(string) Version ID of an object.

storage_class

(string) The class of storage used to store the object.

key

(string) The object key.

owner

(dict)

is_latest

(boolean) Specifies whether the object is (true) or is not (false) the latest version of an object.

size

(integer) Size in bytes of the object.

Actions

Actions call operations on resources. They may automatically handle the passing in of arguments set from identifiers and some attributes. For more information about actions refer to the Resources Introduction Guide.

delete(**kwargs)

Removes the null version (if there is one) of an object and inserts a delete marker, which becomes the latest version of the object. If there isn't a null version, Amazon S3 does not remove any objects.

Request Syntax

response = object_version.delete(
    MFA='string',
    RequestPayer='requester'
)
Parameters:
  • MFA (string) -- The concatenation of the authentication device's serial number, a space, and the value that is displayed on your authentication device.
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'VersionId': 'string',
    'RequestCharged': 'requester'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the versioned object that was permanently deleted was (true) or was not (false) a delete marker.
    • VersionId (string) -- Returns the version ID of the delete marker created as a result of the DELETE operation.
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.

get(**kwargs)

Retrieves objects from Amazon S3.

Request Syntax

response = object_version.get(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    ResponseCacheControl='string',
    ResponseContentDisposition='string',
    ResponseContentEncoding='string',
    ResponseContentLanguage='string',
    ResponseContentType='string',
    ResponseExpires=datetime(2015, 1, 1),
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • ResponseCacheControl (string) -- Sets the Cache-Control header of the response.
  • ResponseContentDisposition (string) -- Sets the Content-Disposition header of the response
  • ResponseContentEncoding (string) -- Sets the Content-Encoding header of the response.
  • ResponseContentLanguage (string) -- Sets the Content-Language header of the response.
  • ResponseContentType (string) -- Sets the Content-Type header of the response.
  • ResponseExpires (datetime) -- Sets the Expires header of the response.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'Body': b'bytes',
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentRange': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • Body (bytes) -- Object data.
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentRange (string) -- The portion of the object returned in the response.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

head(**kwargs)

The HEAD operation retrieves metadata from an object without returning the object itself. This operation is useful if you're only interested in an object's metadata. To use HEAD, you must have READ access to the object.

Request Syntax

response = object_version.head(
    IfMatch='string',
    IfModifiedSince=datetime(2015, 1, 1),
    IfNoneMatch='string',
    IfUnmodifiedSince=datetime(2015, 1, 1),
    Range='string',
    SSECustomerAlgorithm='string',
    SSECustomerKey='string',
    RequestPayer='requester'
)
Parameters:
  • IfMatch (string) -- Return the object only if its entity tag (ETag) is the same as the one specified, otherwise return a 412 (precondition failed).
  • IfModifiedSince (datetime) -- Return the object only if it has been modified since the specified time, otherwise return a 304 (not modified).
  • IfNoneMatch (string) -- Return the object only if its entity tag (ETag) is different from the one specified, otherwise return a 304 (not modified).
  • IfUnmodifiedSince (datetime) -- Return the object only if it has not been modified since the specified time, otherwise return a 412 (precondition failed).
  • Range (string) -- Downloads the specified range bytes of an object. For more information about the HTTP Range header, go to http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.35.
  • SSECustomerAlgorithm (string) -- Specifies the algorithm to use to when encrypting the object (e.g., AES256).
  • SSECustomerKey (string) -- Specifies the customer-provided encryption key for Amazon S3 to use in encrypting data. This value is used to store the object and then it is discarded; Amazon does not store the encryption key. The key must be appropriate for use with the algorithm specified in the x-amz-server-side-encryption-customer-algorithm header.
  • SSECustomerKeyMD5 (string) -- Specifies the 128-bit MD5 digest of the encryption key according to RFC 1321. Amazon S3 uses this header for a message integrity check to ensure the encryption key was transmitted without error. Please note that this parameter is automatically populated if it is not provided. Including this parameter is not required
  • RequestPayer (string) -- Confirms that the requester knows that she or he will be charged for the request. Bucket owners need not specify this parameter in their requests. Documentation on downloading objects from requester pays buckets can be found at http://docs.aws.amazon.com/AmazonS3/latest/dev/ObjectsinRequesterPaysBuckets.html
Return type:

dict

Returns:

Response Syntax

{
    'DeleteMarker': True|False,
    'AcceptRanges': 'string',
    'Expiration': 'string',
    'Restore': 'string',
    'LastModified': datetime(2015, 1, 1),
    'ContentLength': 123,
    'ETag': 'string',
    'MissingMeta': 123,
    'VersionId': 'string',
    'CacheControl': 'string',
    'ContentDisposition': 'string',
    'ContentEncoding': 'string',
    'ContentLanguage': 'string',
    'ContentType': 'string',
    'Expires': datetime(2015, 1, 1),
    'WebsiteRedirectLocation': 'string',
    'ServerSideEncryption': 'AES256'|'aws:kms',
    'Metadata': {
        'string': 'string'
    },
    'SSECustomerAlgorithm': 'string',
    'SSECustomerKeyMD5': 'string',
    'SSEKMSKeyId': 'string',
    'StorageClass': 'STANDARD'|'REDUCED_REDUNDANCY'|'LT',
    'RequestCharged': 'requester',
    'ReplicationStatus': 'COMPLETE'|'PENDING'|'FAILED'|'REPLICA'
}

Response Structure

  • (dict) --
    • DeleteMarker (boolean) -- Specifies whether the object retrieved was (true) or was not (false) a Delete Marker. If false, this response header does not appear in the response.
    • AcceptRanges (string) --
    • Expiration (string) -- If the object expiration is configured (see PUT Bucket lifecycle), the response includes this header. It includes the expiry-date and rule-id key value pairs providing object expiration information. The value of the rule-id is URL encoded.
    • Restore (string) -- Provides information about object restoration operation and expiration time of the restored object copy.
    • LastModified (datetime) -- Last modified date of the object
    • ContentLength (integer) -- Size of the body in bytes.
    • ETag (string) -- An ETag is an opaque identifier assigned by a web server to a specific version of a resource found at a URL
    • MissingMeta (integer) -- This is set to the number of metadata entries not returned in x-amz-meta headers. This can happen if you create metadata using an API like SOAP that supports more flexible metadata than the REST API. For example, using SOAP, you can create metadata whose values are not legal HTTP headers.
    • VersionId (string) -- Version of the object.
    • CacheControl (string) -- Specifies caching behavior along the request/reply chain.
    • ContentDisposition (string) -- Specifies presentational information for the object.
    • ContentEncoding (string) -- Specifies what content encodings have been applied to the object and thus what decoding mechanisms must be applied to obtain the media-type referenced by the Content-Type header field.
    • ContentLanguage (string) -- The language the content is in.
    • ContentType (string) -- A standard MIME type describing the format of the object data.
    • Expires (datetime) -- The date and time at which the object is no longer cacheable.
    • WebsiteRedirectLocation (string) -- If the bucket is configured as a website, redirects requests for this object to another object in the same bucket or to an external URL. Amazon S3 stores the value of this header in the object metadata.
    • ServerSideEncryption (string) -- The Server-side encryption algorithm used when storing this object in S3 (e.g., AES256, aws:kms).
    • Metadata (dict) -- A map of metadata to store with the object in S3.
      • (string) --
        • (string) --
    • SSECustomerAlgorithm (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header confirming the encryption algorithm used.
    • SSECustomerKeyMD5 (string) -- If server-side encryption with a customer-provided encryption key was requested, the response will include this header to provide round trip message integrity verification of the customer-provided encryption key.
    • SSEKMSKeyId (string) -- If present, specifies the ID of the AWS Key Management Service (KMS) master encryption key that was used for the object.
    • StorageClass (string) --
    • RequestCharged (string) -- If present, indicates that the requester was successfully charged for the request.
    • ReplicationStatus (string) --

Sub-resources

Sub-resources are methods that create a new instance of a child resource. This resource's identifiers get passed along to the child. For more information about sub-resources refer to the Resources Introduction Guide.

Object()

Creates a Object resource.:

object = object_version.Object()
Return type:S3.Object
Returns:A Object resource