bucket

Bucket related API.

Every method except from_bucket and list_buckets must be called on a bucket (e.g. S3Path("my-bucket")), and raises S3PathIsNotBucketError on any other path, before calling AWS.

Errors from AWS are raised as is (botocore.exceptions.ClientError), e.g. NoSuchBucket for a missing bucket.

class s3pathlib.core.bucket.BucketAPIMixin

A mixin class that implements the bucket related methods.

classmethod from_bucket(bucket: str) → S3Path

Create an S3Path object from a bucket name.

Only the format is checked (a non-empty name without / or :), not the bucket naming rules, so a legacy bucket name such as My_Bucket works.

Raises:

S3ValidationError – if it is not a single bucket name.

create_bucket(region: str | None = None, acl: str = OPT, grant_full_control: str = OPT, grant_read: str = OPT, grant_read_acp: str = OPT, grant_write: str = OPT, grant_write_acp: str = OPT, object_lock_enabled_for_bucket: bool = OPT, object_ownership: str = OPT, s3_client: S3Client | None = None) → dict

Create this bucket, see create_bucket.

Parameters:

region – the region of the new bucket. None (the default) means the region of the S3 client. S3 rejects a region other than the one of the client with IllegalLocationConstraintException, except when the client is in us-east-1.

Returns:

the response of create_bucket.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. BucketAlreadyExists when another AWS account owns the name, and BucketAlreadyOwnedByYou when you already own it.

Note

In us-east-1, creating a bucket you already own succeeds and resets its ACL, instead of raising BucketAlreadyOwnedByYou (a legacy behavior of S3).

delete_bucket(expected_bucket_owner: str = OPT, s3_client: S3Client | None = None) → dict

Delete this bucket, see delete_bucket. The bucket must be empty (no object, no object version, no delete marker). This S3Path is not changed: a bucket listed by list_buckets keeps its snapshot, like every other method that changes S3 (see core.metadata).

Returns:

the response of delete_bucket.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. NoSuchBucket, and BucketNotEmpty when the bucket is not empty.

get_bucket_versioning(expected_bucket_owner: str = OPT, s3_client: S3Client | None = None) → dict

Get the versioning state of this bucket, see get_bucket_versioning.

Returns:

the response of get_bucket_versioning. "Status" is "Enabled" or "Suspended", and missing if versioning was never enabled.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. NoSuchBucket.

is_versioning_enabled(s3_client: S3Client | None = None) → bool

Check if the versioning of this bucket is enabled. False if it is suspended or was never enabled.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. NoSuchBucket.

is_versioning_suspended(s3_client: S3Client | None = None) → bool

Check if the versioning of this bucket is suspended. False if it is enabled or was never enabled.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. NoSuchBucket.

put_bucket_versioning(enable_versioning: bool, enable_mfa_delete: bool | None = None, checksum_algorithm: str = OPT, mfa: str = OPT, expected_bucket_owner: str = OPT, s3_client: S3Client | None = None) → dict

Enable or suspend the versioning of this bucket, see put_bucket_versioning. Versioning cannot be turned off once enabled, only suspended.

Parameters:

• enable_versioning – True sets Status to "Enabled", False to "Suspended".

• enable_mfa_delete – True sets MFADelete to "Enabled", False to "Disabled"; None (default), it is not sent. Only the root user of the bucket owner account can change it, and it requires mfa.

• mfa – the serial number of the MFA device, a space, and the code it shows.

Returns:

the response of put_bucket_versioning.

Raises:

• S3PathIsNotBucketError – if this path is not a bucket.

• botocore.exceptions.ClientError – as is, e.g. NoSuchBucket.

classmethod list_buckets(s3_client: S3Client | None = None) → list[S3Path]

List all buckets of the AWS account, see list_buckets. It fetches every page (up to 10,000 buckets per call), so it also works for an account allowed to have more than 10,000 buckets, where S3 rejects a ListBuckets request without MaxBuckets.

Each bucket carries the data S3 returned: last_modified_at is the creation date of the bucket, and response["BucketRegion"] its region (when S3 returns it).

Raises:

botocore.exceptions.ClientError – as is, e.g. AccessDenied.