gufo.blob.aio.s3¶
Async S3Blob implementation.
S3Blob
¶
Bases: BlobBase
S3-compatible asynchronous blob storage.
Stores objects on an S3-compatible service using plain HTTP requests
through gufo.http.async_client.HttpClient. No AWS SDK is used — all
operations are standard REST calls executed natively in the event loop.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
bucket
|
str
|
Bucket name. |
required |
prefix
|
str
|
Optional key prefix within the bucket. |
''
|
endpoint
|
str
|
Custom endpoint URL (e.g., MinIO or moto).
If empty, uses default |
''
|
region
|
str
|
AWS region (default: |
'us-east-1'
|
access_key
|
str | None
|
Access key ID (optional). |
None
|
secret_key
|
str | None
|
Secret access key (optional). |
None
|
delete(key)
async
¶
Delete key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Object key. |
required |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the object does not exist. |
BlobError
|
On backend or I/O failure. |
exists(key)
async
¶
Check whether a key exists in the blob store.
Performs an asynchronous HEAD request on the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Object key. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the key exists, False otherwise. |
Raises:
| Type | Description |
|---|---|
BlobError
|
On backend or I/O failure. |
get(key)
async
¶
Retrieve data by key.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Object key. |
required |
Returns:
| Type | Description |
|---|---|
bytes
|
Stored bytes. |
Raises:
| Type | Description |
|---|---|
KeyError
|
If the object does not exist. |
BlobError
|
On backend or I/O failure. |
parse_url(url)
classmethod
¶
Parse S3 URL and extract parameters for constructor.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
url
|
str
|
S3 URL (e.g., |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
|
Raises:
| Type | Description |
|---|---|
BlobError
|
on malformed URLs. |
put(key, data)
async
¶
Store binary data under the given key.
Sends a PUT request to create or overwrite the object.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
key
|
str
|
Object key. |
required |
data
|
bytes
|
Binary payload. |
required |
Raises:
| Type | Description |
|---|---|
BlobError
|
On backend or I/O failure. |
scan(prefix)
¶
Iterate all keys within prefix.
Uses ListObjectsV2 API with continuation tokens for pagination.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
prefix
|
str
|
Prefix to scan (relative to bucket prefix). |
required |
Returns:
| Type | Description |
|---|---|
AsyncIterator[str]
|
Yields matched keys (without bucket prefix). |
Raises:
| Type | Description |
|---|---|
BlobError
|
On backend or I/O failure. |