s3bucket

messageflux.iodevices.objectstorage.s3api.s3bucket

S3Bucket

S3Bucket(bucket_name, s3_resource, auto_create=False)

this class represents a single S3 Bucket

this class represents a single S3 Bucket

Parameters:

Name	Type	Description	Default
bucket_name	str	the name of the bucket to work with	required
s3_resource	S3ServiceResource	the s3 resource to use	required
auto_create	bool	should we create the bucket if it doesn't exist?	False

name property

name

returns the bucket name

Returns:

Type	Description
	the bucket name

s3_resource property

s3_resource

the client for this bucket

allow_public_access

allow_public_access()

makes the bucket publicly accessible from web

clear_objects

clear_objects()

clears all the objects in the bucket

compute_url

compute_url(key)

computes the item url, by key

Parameters:

Name	Type	Description	Default
key		the key to item	required

Returns:

Type	Description
	the url to item

create_bucket staticmethod

create_bucket(
    s3_resource,
    bucket_name,
    lifetime_in_days=None,
    allow_public_access=False,
)

creates and returns a bucket

Parameters:

Name	Type	Description	Default
s3_resource	S3ServiceResource	the s3 resource to use	required
bucket_name	str	the bucket name to create and get	required
lifetime_in_days	Optional[int]	the lifetime of objects in the bucket to set (None for no change)	None
allow_public_access		should we make the bucket publicly accessible from web	False

Returns:

Type	Description
S3Bucket	the bucket

delete_bucket

delete_bucket(force=False)

deletes all items in bucket, and then deletes bucket

Parameters:

Name	Type	Description	Default
force		True will delete all objects on bucket, before deleting the bucket	False

delete_object

delete_object(key)

deletes a binary from the bucket

Parameters:

Name	Type	Description	Default
key	str	the key of the binary	required

download_object

download_object(key, writable_stream, **kwargs)

downloads an object from the bucket into a writable stream

Parameters:

Name	Type	Description	Default
key	str	the key of the object to download	required
writable_stream	IO[Any]	the writable stream to write into	required

Returns:

Type	Description

find_objects

find_objects(
    prefix=None, delimiter=None, max_keys=1000, **kwargs
)

find objects ih the bucket.

Parameters:

Name	Type	Description	Default
delimiter	Optional[str]	A Delimiter is a character you use to group keys	None
prefix	Optional[str]	Limits the response to keys that begin with the specified prefix	None
max_keys	int	Sets the maximum number of keys returned in the response	1000
**kwargs		additional filters to s3	{}

Returns:

Type	Description
Iterator[S3Object]	dict from object key to last modified

get_object

get_object(key)

gets a binary from the bucket

Parameters:

Name	Type	Description	Default
key	str	the key of the binary	required

Returns:

Type	Description
S3Object	the buffer of the object, and the metadata dict

list_buckets staticmethod

list_buckets(s3_resource)

returns a list of all the buckets in this client

Parameters:

Name	Type	Description	Default
s3_resource	S3ServiceResource	the s3 resource to use	required

Returns:

Type	Description
Iterator[S3Bucket]	iterator of bucket objects

list_objects

list_objects()

lists all the objects in this bucket

Returns:

Type	Description
Iterator[S3Object]	a generator of S3Objects

put_object

put_object(key, buf, metadata, **kwargs)

puts a binary object in the bucket

Parameters:

Name	Type	Description	Default
key	str	the key of the object to put	required
buf	Union[str, bytes, IO[Any]]	the buffer to put in the bucket	required
metadata	Dict[str, str]	extra metadata	required

set_lifetime_in_days

set_lifetime_in_days(days)

sets the lifetime of all objects in bucket to 'days' days (or <=0 to cancel expiration)

Parameters:

Name	Type	Description	Default
days	int	the number of days for an item to live	required

upload_object

upload_object(key, stream, metadata, **kwargs)

uploads a binary stream to the bucket

Parameters:

Name	Type	Description	Default
key	str	the key of the object to put	required
stream	IO[Any]	the stream to put in the bucket	required
metadata	Dict[str, str]	extra metadata	required

S3BucketException

Bases: Exception

represents errors thrown from S3 bucket

S3NoSuchBucket

Bases: S3BucketException

represents no such bucket

S3NoSuchItem

Bases: S3BucketException

represents no such item in bucket

S3Object

S3Object(object_summery, object_cache=None)

represents an s3 object with lazy content get

body property

body

the bytes for the object's body (lazy read)

body_stream property

body_stream

the stream for the object's body (lazy read)

key property

key

the object's key

last_modified property

last_modified

the object's last modified time (might incur a request to the server)

metadata property

metadata

the object's metadata

size property

size

the object's size (might incur a request to the server)