

**
S3
**



======
Client
======



.. py:class:: S3.Client

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

    
    import boto3
    
    client = boto3.client('s3')

  

These are the available methods:

.. toctree::
  :maxdepth: 1
  :titlesonly:

  s3/client/abort_multipart_upload
  s3/client/can_paginate
  s3/client/close
  s3/client/complete_multipart_upload
  s3/client/copy
  s3/client/copy_object
  s3/client/create_bucket
  s3/client/create_bucket_metadata_configuration
  s3/client/create_bucket_metadata_table_configuration
  s3/client/create_multipart_upload
  s3/client/create_session
  s3/client/delete_bucket
  s3/client/delete_bucket_analytics_configuration
  s3/client/delete_bucket_cors
  s3/client/delete_bucket_encryption
  s3/client/delete_bucket_intelligent_tiering_configuration
  s3/client/delete_bucket_inventory_configuration
  s3/client/delete_bucket_lifecycle
  s3/client/delete_bucket_metadata_configuration
  s3/client/delete_bucket_metadata_table_configuration
  s3/client/delete_bucket_metrics_configuration
  s3/client/delete_bucket_ownership_controls
  s3/client/delete_bucket_policy
  s3/client/delete_bucket_replication
  s3/client/delete_bucket_tagging
  s3/client/delete_bucket_website
  s3/client/delete_object
  s3/client/delete_object_tagging
  s3/client/delete_objects
  s3/client/delete_public_access_block
  s3/client/download_file
  s3/client/download_fileobj
  s3/client/generate_presigned_post
  s3/client/generate_presigned_url
  s3/client/get_bucket_abac
  s3/client/get_bucket_accelerate_configuration
  s3/client/get_bucket_acl
  s3/client/get_bucket_analytics_configuration
  s3/client/get_bucket_cors
  s3/client/get_bucket_encryption
  s3/client/get_bucket_intelligent_tiering_configuration
  s3/client/get_bucket_inventory_configuration
  s3/client/get_bucket_lifecycle
  s3/client/get_bucket_lifecycle_configuration
  s3/client/get_bucket_location
  s3/client/get_bucket_logging
  s3/client/get_bucket_metadata_configuration
  s3/client/get_bucket_metadata_table_configuration
  s3/client/get_bucket_metrics_configuration
  s3/client/get_bucket_notification
  s3/client/get_bucket_notification_configuration
  s3/client/get_bucket_ownership_controls
  s3/client/get_bucket_policy
  s3/client/get_bucket_policy_status
  s3/client/get_bucket_replication
  s3/client/get_bucket_request_payment
  s3/client/get_bucket_tagging
  s3/client/get_bucket_versioning
  s3/client/get_bucket_website
  s3/client/get_object
  s3/client/get_object_acl
  s3/client/get_object_attributes
  s3/client/get_object_legal_hold
  s3/client/get_object_lock_configuration
  s3/client/get_object_retention
  s3/client/get_object_tagging
  s3/client/get_object_torrent
  s3/client/get_paginator
  s3/client/get_public_access_block
  s3/client/get_waiter
  s3/client/head_bucket
  s3/client/head_object
  s3/client/list_bucket_analytics_configurations
  s3/client/list_bucket_intelligent_tiering_configurations
  s3/client/list_bucket_inventory_configurations
  s3/client/list_bucket_metrics_configurations
  s3/client/list_buckets
  s3/client/list_directory_buckets
  s3/client/list_multipart_uploads
  s3/client/list_object_versions
  s3/client/list_objects
  s3/client/list_objects_v2
  s3/client/list_parts
  s3/client/put_bucket_abac
  s3/client/put_bucket_accelerate_configuration
  s3/client/put_bucket_acl
  s3/client/put_bucket_analytics_configuration
  s3/client/put_bucket_cors
  s3/client/put_bucket_encryption
  s3/client/put_bucket_intelligent_tiering_configuration
  s3/client/put_bucket_inventory_configuration
  s3/client/put_bucket_lifecycle
  s3/client/put_bucket_lifecycle_configuration
  s3/client/put_bucket_logging
  s3/client/put_bucket_metrics_configuration
  s3/client/put_bucket_notification
  s3/client/put_bucket_notification_configuration
  s3/client/put_bucket_ownership_controls
  s3/client/put_bucket_policy
  s3/client/put_bucket_replication
  s3/client/put_bucket_request_payment
  s3/client/put_bucket_tagging
  s3/client/put_bucket_versioning
  s3/client/put_bucket_website
  s3/client/put_object
  s3/client/put_object_acl
  s3/client/put_object_legal_hold
  s3/client/put_object_lock_configuration
  s3/client/put_object_retention
  s3/client/put_object_tagging
  s3/client/put_public_access_block
  s3/client/rename_object
  s3/client/restore_object
  s3/client/select_object_content
  s3/client/update_bucket_metadata_inventory_table_configuration
  s3/client/update_bucket_metadata_journal_table_configuration
  s3/client/update_object_encryption
  s3/client/upload_file
  s3/client/upload_fileobj
  s3/client/upload_part
  s3/client/upload_part_copy
  s3/client/write_get_object_response


==========
Paginators
==========


Paginators are available on a client instance via the ``get_paginator`` method. For more detailed instructions and examples on the usage of paginators, see the paginators `user guide <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/paginators.html>`_.

The available paginators are:

.. toctree::
  :maxdepth: 1
  :titlesonly:

  s3/paginator/ListBuckets
  s3/paginator/ListDirectoryBuckets
  s3/paginator/ListMultipartUploads
  s3/paginator/ListObjectVersions
  s3/paginator/ListObjects
  s3/paginator/ListObjectsV2
  s3/paginator/ListParts


=======
Waiters
=======


Waiters are available on a client instance via the ``get_waiter`` method. For more detailed instructions and examples on the usage or waiters, see the waiters `user guide <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/clients.html#waiters>`_.

The available waiters are:

.. toctree::
  :maxdepth: 1
  :titlesonly:

  s3/waiter/BucketExists
  s3/waiter/BucketNotExists
  s3/waiter/ObjectExists
  s3/waiter/ObjectNotExists


=========
Resources
=========


Resources are available in boto3 via the ``resource`` method. For more detailed instructions and examples on the usage of resources, see the resources `user guide <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/resources.html>`_.

The available resources are:

.. toctree::
  :maxdepth: 1
  :titlesonly:

  s3/service-resource/index
  s3/bucket/index
  s3/bucketacl/index
  s3/bucketcors/index
  s3/bucketlifecycle/index
  s3/bucketlifecycleconfiguration/index
  s3/bucketlogging/index
  s3/bucketnotification/index
  s3/bucketpolicy/index
  s3/bucketrequestpayment/index
  s3/buckettagging/index
  s3/bucketversioning/index
  s3/bucketwebsite/index
  s3/multipartupload/index
  s3/multipartuploadpart/index
  s3/object/index
  s3/objectacl/index
  s3/objectsummary/index
  s3/objectversion/index


========
Examples
========


List objects in an Amazon S3 bucket
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following example shows how to use an Amazon S3 bucket resource to list
the objects in the bucket.

.. code-block:: python

    import boto3

    s3 = boto3.resource('s3')
    bucket = s3.Bucket('amzn-s3-demo-bucket')
    for obj in bucket.objects.all():
        print(obj.key)


List top-level common prefixes in Amazon S3 bucket
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to list all of the top-level common prefixes in an
Amazon S3 bucket:

.. code-block:: python

    import boto3

    client = boto3.client('s3')
    paginator = client.get_paginator('list_objects')
    result = paginator.paginate(Bucket='amzn-s3-demo-bucket', Delimiter='/')
    for prefix in result.search('CommonPrefixes'):
        print(prefix.get('Prefix'))


Restore Glacier objects in an Amazon S3 bucket
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following example shows how to initiate restoration of glacier objects in
an Amazon S3 bucket, determine if a restoration is on-going, and determine if a
restoration is finished.

.. code-block:: python

    import boto3

    s3 = boto3.resource('s3')
    bucket = s3.Bucket('amzn-s3-demo-bucket')
    for obj_sum in bucket.objects.all():
        obj = s3.Object(obj_sum.bucket_name, obj_sum.key)
        if obj.storage_class == 'GLACIER':
            # Try to restore the object if the storage class is glacier and
            # the object does not have a completed or ongoing restoration
            # request.
            if obj.restore is None:
                print('Submitting restoration request: %s' % obj.key)
                obj.restore_object(RestoreRequest={'Days': 1})
            # Print out objects whose restoration is on-going
            elif 'ongoing-request="true"' in obj.restore:
                print('Restoration in-progress: %s' % obj.key)
            # Print out objects whose restoration is complete
            elif 'ongoing-request="false"' in obj.restore:
                print('Restoration complete: %s' % obj.key)


Uploading/downloading files using SSE KMS
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to use SSE-KMS to upload objects using
server side encryption with a key managed by KMS.

We can either use the default KMS master key, or create a
custom key in AWS and use it to encrypt the object by passing in its
key id.

With KMS, nothing else needs to be provided for getting the
object; S3 already knows how to decrypt the object.


.. code-block:: python

    import boto3
    import os

    BUCKET = 'amzn-s3-demo-bucket'
    s3 = boto3.client('s3')
    keyid = '<the key id>'

    print("Uploading S3 object with SSE-KMS")
    s3.put_object(Bucket=BUCKET,
                  Key='encrypt-key',
                  Body=b'foobar',
                  ServerSideEncryption='aws:kms',
                  # Optional: SSEKMSKeyId
                  SSEKMSKeyId=keyid)
    print("Done")

    # Getting the object:
    print("Getting S3 object...")
    response = s3.get_object(Bucket=BUCKET,
                             Key='encrypt-key')
    print("Done, response body:")
    print(response['Body'].read())


Uploading/downloading files using SSE Customer Keys
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to use SSE-C to upload objects using
server side encryption with a customer provided key.

First, we'll need a 32 byte key.  For this example, we'll
randomly generate a key but you can use any 32 byte key
you want.  Remember, you must the same key to download
the object.  If you lose the encryption key, you lose
the object.

Also note how we don't have to provide the SSECustomerKeyMD5.
Boto3 will automatically compute this value for us.


.. code-block:: python

    import boto3
    import os

    BUCKET = 'amzn-s3-demo-bucket'
    KEY = os.urandom(32)
    s3 = boto3.client('s3')

    print("Uploading S3 object with SSE-C")
    s3.put_object(Bucket=BUCKET,
                  Key='encrypt-key',
                  Body=b'foobar',
                  SSECustomerKey=KEY,
                  SSECustomerAlgorithm='AES256')
    print("Done")

    # Getting the object:
    print("Getting S3 object...")
    # Note how we're using the same ``KEY`` we
    # created earlier.
    response = s3.get_object(Bucket=BUCKET,
                             Key='encrypt-key',
                             SSECustomerKey=KEY,
                             SSECustomerAlgorithm='AES256')
    print("Done, response body:")
    print(response['Body'].read())


Downloading a specific version of an S3 object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to download a specific version of an
S3 object.

.. code-block:: python

    import boto3
    s3 = boto3.client('s3')

    s3.download_file(
        "amzn-s3-demo-bucket", "key-name", "tmp.txt",
        ExtraArgs={"VersionId": "my-version-id"}
    )


Filter objects by last modified time using JMESPath
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This example shows how to filter objects by last modified time
using JMESPath.

.. code-block:: python

    import boto3
    s3 = boto3.client("s3")

    s3_paginator = s3.get_paginator('list_objects_v2')
    s3_iterator = s3_paginator.paginate(Bucket='amzn-s3-demo-bucket')

    filtered_iterator = s3_iterator.search(
        "Contents[?to_string(LastModified)>='\"2022-01-05 08:05:37+00:00\"'].Key"
    )

    for key_data in filtered_iterator:
        print(key_data)


=========================
Client Context Parameters
=========================


Client context parameters are configurable on a client instance via the ``client_context_params`` parameter in the ``Config`` object. For more detailed instructions and examples on the exact usage of context params see the `configuration guide <https://boto3.amazonaws.com/v1/documentation/api/latest/guide/configuration.html>`_.

The available ``s3`` client context params are:

* ``disable_s3_express_session_auth`` (boolean) - Disables this client's usage of Session Auth for S3Express
      buckets and reverts to using conventional SigV4 for those.