create_bucket async ¶

async def create_bucket(
    self,
    bucket: "capo_s3.types.bucket_name.BucketName",
    *,
    config_overrides: Optional[AsyncS3ClientConfig] = None,
    acl: Optional["capo_s3.types.bucket_canned_acl.BucketCannedACL"] = None,
    create_bucket_configuration: Optional[
        "capo_s3.types.create_bucket_configuration.CreateBucketConfiguration"
    ] = None,
    grant_full_control: Optional[
        "capo_s3.types.grant_full_control.GrantFullControl"
    ] = None,
    grant_read: Optional["capo_s3.types.grant_read.GrantRead"] = None,
    grant_read_acp: Optional["capo_s3.types.grant_read_acp.GrantReadACP"] = None,
    grant_write: Optional["capo_s3.types.grant_write.GrantWrite"] = None,
    grant_write_acp: Optional["capo_s3.types.grant_write_acp.GrantWriteACP"] = None,
    object_lock_enabled_for_bucket: Optional[
        "capo_s3.types.object_lock_enabled_for_bucket.ObjectLockEnabledForBucket"
    ] = None,
    object_ownership: Optional[
        "capo_s3.types.object_ownership.ObjectOwnership"
    ] = None,
    bucket_namespace: Optional[
        "capo_s3.types.bucket_namespace.BucketNamespace"
    ] = None,
) -> "capo_s3.types.create_bucket_output.CreateBucketOutput":
    """<note> <p>This action creates an Amazon S3 bucket. To create an Amazon S3 on Outposts bucket, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_control_CreateBucket.html"> <code>CreateBucket</code> </a>.</p> </note> <p>Creates a new S3 bucket. To create a bucket, you must set up Amazon S3 and have a valid Amazon Web Services Access Key ID to authenticate requests. Anonymous requests are never allowed to create buckets. By creating the bucket, you become the bucket owner.</p> <p>There are two types of buckets: general purpose buckets and directory buckets. For more information about these bucket types, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-buckets-s3.html">Creating, configuring, and working with Amazon S3 buckets</a> in the <i>Amazon S3 User Guide</i>.</p> <p>General purpose buckets exist in a global namespace, which means that each bucket name must be unique across all Amazon Web Services accounts in all the Amazon Web Services Regions within a partition. A partition is a grouping of Regions. Amazon Web Services currently has four partitions: <code>aws</code> (Standard Regions), <code>aws-cn</code> (China Regions), <code>aws-us-gov</code> (Amazon Web Services GovCloud (US)), and <code>aws-eusc</code> (European Sovereign Cloud). When you create a general purpose bucket, you can choose to create a bucket in the shared global namespace or you can choose to create a bucket in your account regional namespace. Your account regional namespace is a subdivision of the global namespace that only your account can create buckets in. For more information on account regional namespaces, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/gpbucketnamespaces.html">Namespaces for general purpose buckets</a>.</p> <note> <ul> <li> <p> <b>General purpose buckets</b> - If you send your <code>CreateBucket</code> request to the <code>s3.amazonaws.com</code> global endpoint, the request goes to the <code>us-east-1</code> Region. So the signature calculations in Signature Version 4 must use <code>us-east-1</code> as the Region, even if the location constraint in the request specifies another Region where the bucket is to be created. If you create a bucket in a Region other than US East (N. Virginia), your application must be able to handle 307 redirect. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html">Virtual hosting of buckets</a> in the <i>Amazon S3 User Guide</i>.</p> </li> <li> <p> <b>Directory buckets </b> - For directory buckets, you must make requests for this API operation to the Regional endpoint. These endpoints support path-style requests in the format <code>https://s3express-control.<i>region-code</i>.amazonaws.com/<i>bucket-name</i> </code>. Virtual-hosted-style requests aren't supported. For more information about endpoints in Availability Zones, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/endpoint-directory-buckets-AZ.html">Regional and Zonal endpoints for directory buckets in Availability Zones</a> in the <i>Amazon S3 User Guide</i>. For more information about endpoints in Local Zones, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-lzs-for-directory-buckets.html">Concepts for directory buckets in Local Zones</a> in the <i>Amazon S3 User Guide</i>.</p> </li> </ul> </note> <dl> <dt>Permissions</dt> <dd> <ul> <li> <p> <b>General purpose bucket permissions</b> - In addition to the <code>s3:CreateBucket</code> permission, the following permissions are required in a policy when your <code>CreateBucket</code> request includes specific headers: </p> <ul> <li> <p> <b>Access control lists (ACLs)</b> - In your <code>CreateBucket</code> request, if you specify an access control list (ACL) and set it to <code>public-read</code>, <code>public-read-write</code>, <code>authenticated-read</code>, or if you explicitly specify any other custom ACLs, both <code>s3:CreateBucket</code> and <code>s3:PutBucketAcl</code> permissions are required. In your <code>CreateBucket</code> request, if you set the ACL to <code>private</code>, or if you don't specify any ACLs, only the <code>s3:CreateBucket</code> permission is required. </p> </li> <li> <p> <b>Object Lock</b> - In your <code>CreateBucket</code> request, if you set <code>x-amz-bucket-object-lock-enabled</code> to true, the <code>s3:PutBucketObjectLockConfiguration</code> and <code>s3:PutBucketVersioning</code> permissions are required.</p> </li> <li> <p> <b>S3 Object Ownership</b> - If your <code>CreateBucket</code> request includes the <code>x-amz-object-ownership</code> header, then the <code>s3:PutBucketOwnershipControls</code> permission is required.</p> <important> <p> To set an ACL on a bucket as part of a <code>CreateBucket</code> request, you must explicitly set S3 Object Ownership for the bucket to a different value than the default, <code>BucketOwnerEnforced</code>. Additionally, if your desired bucket ACL grants public access, you must first create the bucket (without the bucket ACL) and then explicitly disable Block Public Access on the bucket before using <code>PutBucketAcl</code> to set the ACL. If you try to create a bucket with a public ACL, the request will fail. </p> <p> For the majority of modern use cases in S3, we recommend that you keep all Block Public Access settings enabled and keep ACLs disabled. If you would like to share data with users outside of your account, you can use bucket policies as needed. For more information, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/about-object-ownership.html">Controlling ownership of objects and disabling ACLs for your bucket </a> and <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html">Blocking public access to your Amazon S3 storage </a> in the <i>Amazon S3 User Guide</i>. </p> </important> </li> <li> <p> <b>S3 Block Public Access</b> - If your specific use case requires granting public access to your S3 resources, you can disable Block Public Access. Specifically, you can create a new bucket with Block Public Access enabled, then separately call the <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeletePublicAccessBlock.html"> <code>DeletePublicAccessBlock</code> </a> API. To use this operation, you must have the <code>s3:PutBucketPublicAccessBlock</code> permission. For more information about S3 Block Public Access, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/access-control-block-public-access.html">Blocking public access to your Amazon S3 storage </a> in the <i>Amazon S3 User Guide</i>. </p> </li> </ul> </li> <li> <p> <b>Directory bucket permissions</b> - You must have the <code>s3express:CreateBucket</code> permission in an IAM identity-based policy instead of a bucket policy. Cross-account access to this API operation isn't supported. This operation can only be performed by the Amazon Web Services account that owns the resource. For more information about directory bucket policies and permissions, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-security-iam.html">Amazon Web Services Identity and Access Management (IAM) for S3 Express One Zone</a> in the <i>Amazon S3 User Guide</i>.</p> <important> <p>The permissions for ACLs, Object Lock, S3 Object Ownership, and S3 Block Public Access are not supported for directory buckets. For directory buckets, all Block Public Access settings are enabled at the bucket level and S3 Object Ownership is set to Bucket owner enforced (ACLs disabled). These settings can't be modified. </p> <p>For more information about permissions for creating and working with directory buckets, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-buckets-overview.html">Directory buckets</a> in the <i>Amazon S3 User Guide</i>. For more information about supported S3 features for directory buckets, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-express-one-zone.html#s3-express-features">Features of S3 Express One Zone</a> in the <i>Amazon S3 User Guide</i>.</p> </important> </li> </ul> </dd> <dt>HTTP Host header syntax</dt> <dd> <p> <b>Directory buckets </b> - The HTTP Host header syntax is <code>s3express-control.<i>region-code</i>.amazonaws.com</code>.</p> </dd> </dl> <p>The following operations are related to <code>CreateBucket</code>:</p> <ul> <li> <p> <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_PutObject.html">PutObject</a> </p> </li> <li> <p> <a href="https://docs.aws.amazon.com/AmazonS3/latest/API/API_DeleteBucket.html">DeleteBucket</a> </p> </li> </ul> <important> <p>You must URL encode any signed header values that contain spaces. For example, if your header value is <code>my file.txt</code>, containing two spaces after <code>my</code>, you must URL encode this value to <code>my%20%20file.txt</code>.</p> </important>

    Args:
        acl: <p>The canned ACL to apply to the bucket.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        bucket: <p>The name of the bucket to create.</p> <p> <b>General purpose buckets</b> - For information about bucket naming restrictions, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html">Bucket naming rules</a> in the <i>Amazon S3 User Guide</i>.</p> <p> <b>Directory buckets </b> - When you use this operation with a directory bucket, you must use path-style requests in the format <code>https://s3express-control.<i>region-code</i>.amazonaws.com/<i>bucket-name</i> </code>. Virtual-hosted-style requests aren't supported. Directory bucket names must be unique in the chosen Zone (Availability Zone or Local Zone). Bucket names must also follow the format <code> <i>bucket-base-name</i>--<i>zone-id</i>--x-s3</code> (for example, <code> <i>DOC-EXAMPLE-BUCKET</i>--<i>usw2-az1</i>--x-s3</code>). For information about bucket naming restrictions, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/directory-bucket-naming-rules.html">Directory bucket naming rules</a> in the <i>Amazon S3 User Guide</i> </p>
        create_bucket_configuration: <p>The configuration information for the bucket.</p>
        grant_full_control: <p>Allows grantee the read, write, read ACP, and write ACP permissions on the bucket.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        grant_read: <p>Allows grantee to list the objects in the bucket.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        grant_read_acp: <p>Allows grantee to read the bucket ACL.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        grant_write: <p>Allows grantee to create new objects in the bucket.</p> <p>For the bucket and object owners of existing objects, also allows deletions and overwrites of those objects.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        grant_write_acp: <p>Allows grantee to write the ACL for the applicable bucket.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        object_lock_enabled_for_bucket: <p>Specifies whether you want S3 Object Lock to be enabled for the new bucket.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>
        bucket_namespace: <p>Specifies the namespace where you want to create your general purpose bucket. When you create a general purpose bucket, you can choose to create a bucket in the shared global namespace or you can choose to create a bucket in your account regional namespace. Your account regional namespace is a subdivision of the global namespace that only your account can create buckets in. For more information on bucket namespaces, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/gpbucketnamespaces.html">Namespaces for general purpose buckets</a>.</p> <p>General purpose buckets in your account regional namespace must follow a specific naming convention. These buckets consist of a bucket name prefix that you create, and a suffix that contains your 12-digit Amazon Web Services Account ID, the Amazon Web Services Region code, and ends with <code>-an</code>. Bucket names must follow the format <code>bucket-name-prefix-accountId-region-an</code> (for example, <code>amzn-s3-demo-bucket-111122223333-us-west-2-an</code>). For information about bucket naming restrictions, see <a href="https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html#account-regional-naming-rules">Account regional namespace naming rules</a> in the <i>Amazon S3 User Guide</i>.</p> <note> <p>This functionality is not supported for directory buckets.</p> </note>

    Raises:
        capo_s3.errors.bucket_already_exists.BucketAlreadyExists: <p>The requested bucket name is not available. The bucket namespace is shared by all users of the system. Select a different name and try again.</p>
        capo_s3.errors.bucket_already_owned_by_you.BucketAlreadyOwnedByYou: <p>The bucket you tried to create already exists, and you own it. Amazon S3 returns this error in all Amazon Web Services Regions except in the North Virginia Region. For legacy compatibility, if you re-create an existing bucket that you already own in the North Virginia Region, Amazon S3 returns 200 OK and resets the bucket access control lists (ACLs).</p>
        capo_s3.errors.UnknownServiceError: The service returned an error code this client does not model.

    Examples:
        To create a bucket in a specific region
        The following example creates a bucket. The request specifies an AWS region where to create the bucket.

        >>> await client.create_bucket(bucket='examplebucket', create_bucket_configuration={'LocationConstraint': 'eu-west-1'})
        To create a bucket
        The following example creates a bucket.

        >>> await client.create_bucket(bucket='examplebucket')
    """

    async def _handler(
        req: "AsyncOperationRequest[capo_s3.types.create_bucket_request.CreateBucketRequest]",
    ) -> AsyncOperationResponse[
        "capo_s3.types.create_bucket_output.CreateBucketOutput"
    ]:
        import capo_s3._operations.amazon_s3.create_bucket

        (
            output,
            http_response,
        ) = await capo_s3._operations.amazon_s3.create_bucket.async_create_bucket(
            req.options, req.input
        )
        return AsyncOperationResponse(output=output, response=http_response)

    interceptors_, options_ = self.operation_options(
        config_overrides, OperationLogging("CreateBucket")
    )
    input_: capo_s3.types.create_bucket_request.CreateBucketRequest = {
        "bucket": bucket
    }
    if acl is not None:
        input_["acl"] = acl
    if create_bucket_configuration is not None:
        input_["create_bucket_configuration"] = create_bucket_configuration
    if grant_full_control is not None:
        input_["grant_full_control"] = grant_full_control
    if grant_read is not None:
        input_["grant_read"] = grant_read
    if grant_read_acp is not None:
        input_["grant_read_acp"] = grant_read_acp
    if grant_write is not None:
        input_["grant_write"] = grant_write
    if grant_write_acp is not None:
        input_["grant_write_acp"] = grant_write_acp
    if object_lock_enabled_for_bucket is not None:
        input_["object_lock_enabled_for_bucket"] = object_lock_enabled_for_bucket
    if object_ownership is not None:
        input_["object_ownership"] = object_ownership
    if bucket_namespace is not None:
        input_["bucket_namespace"] = bucket_namespace

    response = await aexecute_pipeline(
        AsyncOperationRequest(input=input_, options=options_),
        handler=_handler,
        interceptors=list(interceptors_),
    )
    await response.response.aclose()
    return response.output