.. Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
.. SPDX-License-Identifier: Apache-2.0

###############
Bucket policies
###############

An S3 bucket can have an optional policy that grants access permissions to 
other AWS accounts or AWS Identity and Access Management (IAM) users. Bucket 
policies are defined using the same JSON format as a resource-based IAM policy.


Retrieve a bucket policy
========================

Retrieve a bucket's policy by calling the AWS SDK for Python 
``get_bucket_policy`` method. The method accepts a parameter that specifies 
the bucket name.

.. code-block:: python

    import boto3

    # Retrieve the policy of the specified bucket
    s3 = boto3.client('s3')
    result = s3.get_bucket_policy(Bucket='amzn-s3-demo-bucket')
    print(result['Policy'])


Set a bucket policy
===================

A bucket's policy can be set by calling the ``put_bucket_policy`` method.

The policy is defined in the same JSON format as an IAM policy. The policy 
defined in the example below enables any user to retrieve any object 
stored in the bucket identified by the ``bucket_name`` variable.


.. code-block:: python

    import json

    # Create a bucket policy
    bucket_name = 'amzn-s3-demo-bucket'
    bucket_policy = {
        'Version': '2012-10-17',
        'Statement': [{
            'Sid': 'AddPerm',
            'Effect': 'Allow',
            'Principal': '*',
            'Action': ['s3:GetObject'],
            'Resource': f'arn:aws:s3:::{bucket_name}/*'
        }]
    }

    # Convert the policy from JSON dict to string
    bucket_policy = json.dumps(bucket_policy)

    # Set the new policy
    s3 = boto3.client('s3')
    s3.put_bucket_policy(Bucket=bucket_name, Policy=bucket_policy)


Delete a bucket policy
======================

A bucket's policy can be deleted by calling the ``delete_bucket_policy`` method.

.. code-block:: python

    # Delete a bucket's policy
    s3 = boto3.client('s3')
    s3.delete_bucket_policy(Bucket='BUCKET_NAME')
