async_storages¶

class async_storages.BaseStorage[source]¶

Bases: ABC

Abstract base class defining the interface for asynchronous file storage backends.

This class provides an asynchronous and pluggable contract for handling file operations such as uploading, retrieving, and deleting files across different storage systems.

abstractmethod async delete(name: str) → None[source]¶

Delete a stored file from the backend.

Parameters:: name – Original file name or path.
Returns:: None
Return type:: None

abstractmethod get_name(name: str) → str[source]¶

Normalize or sanitize a given file name or path.

Parameters:: name (str) – Original file name or path.
Returns:: A sanitized and valid file name or path for storage.
Return type:: str

abstractmethod async get_path(name: str) → str[source]¶

Generate a URL or path to access the stored file.

Parameters:: name (str) – Original file name or path.
Returns:: A URL or accessible path to the file.
Return type:: str

abstractmethod async get_size(name: str) → int[source]¶

Retrieve the size of a stored file in bytes.

Parameters:: name (str) – Original file name or path.
Returns:: File size in bytes.
Return type:: int

abstractmethod async open(name: str) → BytesIO[source]¶

Open and return a stored file as an in-memory binary stream.

Parameters:: name (str) – Original file name or path.
Returns:: A BytesIO object containing the file’s binary data.
Return type:: BytesIO

abstractmethod async upload(file: BinaryIO, name: str) → str[source]¶

Upload a binary file to the storage backend.

Parameters:

file (BinaryIO) – A binary file-like object to upload.
name (str) – Original file name or path.

Returns:

The final stored file name or path.

Return type:

str

class async_storages.S3Storage(bucket_name: str, endpoint_url: str | None = None, aws_access_key_id: str | None = None, aws_secret_access_key: str | None = None, region_name: str | None = None, use_ssl: bool = True, default_acl: str | None = None, custom_domain: str | None = None, querystring_auth: bool = False)[source]¶

Bases: BaseStorage

Asynchronous storage backend for Amazon S3-compatible object storage.

This class provides async methods for uploading, retrieving, and deleting files in an S3 bucket using the aioboto3 client.

Credentials can be provided explicitly via aws_access_key_id and aws_secret_access_key (useful in development with MinIO or similar), or omitted to let aioboto3 resolve them automatically through the standard AWS credential chain (environment variables, IAM roles, instance metadata, etc.).

Parameters:

bucket_name (str) – Name of the S3 bucket.
endpoint_url (str or None) – The S3 endpoint hostname (without protocol). Optional; when omitted the SDK uses the default AWS S3 endpoint for the region.
aws_access_key_id (str or None) – AWS access key ID for authentication. Optional; when omitted, credentials are resolved via the AWS credential chain.
aws_secret_access_key (str or None) – AWS secret access key for authentication. Optional; when omitted, credentials are resolved via the AWS credential chain.
region_name (str or None) – AWS region name (optional).
use_ssl (bool) – Whether to use HTTPS (True) or HTTP (False).
default_acl (str or None) – Default Access Control List (ACL) to apply when uploading files.
custom_domain (str or None) – Custom domain for serving files (e.g. CDN).
querystring_auth (bool) – Whether to generate presigned URLs with query parameters.

Raises:

ImportError – If aioboto3 is not installed.

async delete(name: str) → None[source]¶

Delete an object from the S3 bucket.

Parameters:: name (str) – The object key (path) to delete.
Returns:: None
Return type:: None
Raises:: botocore.exceptions.ClientError – If the delete operation fails.

get_name(name: str) → str[source]¶

Sanitize and normalize a file path before uploading to S3.

Removes unsafe path components (.. or .) and ensures each segment is a secure filename.

Parameters:: name (str) – Original file name or path.
Returns:: Sanitized file path.
Return type:: str

async get_path(name: str) → str[source]¶

Generate a URL for accessing an S3 object.

If custom_domain is set, returns a static URL using that domain. If querystring_auth is True, returns a presigned URL with temporary access.

Parameters:: name (str) – The object key (path) in the S3 bucket.
Returns:: A direct or presigned URL for the file.
Return type:: str

async get_size(name: str) → int[source]¶

Retrieve the size of an S3 object in bytes.

Parameters:: name (str) – The object key (path) in the S3 bucket.
Returns:: The file size in bytes, or 0 if the object does not exist.
Return type:: int
Raises:: botocore.exceptions.ClientError – If an unexpected S3 error occurs.

async open(name: str) → BytesIO[source]¶

Open an object from S3 and return it as an in-memory binary stream.

This method fetches the file contents asynchronously and returns a BytesIO object positioned at the start of the file.

Parameters:

name (str) – The object key (path) in the S3 bucket.

Returns:

A BytesIO object containing the file’s contents.

Return type:

BytesIO

Raises:

FileNotFoundError – If the object is not found.
botocore.exceptions.ClientError – If the object cannot be fetched.

async upload(file: BinaryIO, name: str) → str[source]¶

Upload a file object to the configured S3 bucket.

Parameters:

file (BinaryIO) – Binary file-like object to upload.
name (str) – Target object key (path) in the S3 bucket.

Returns:

The name or key of the uploaded object.

Return type:

str

Raises:

botocore.exceptions.ClientError – If the upload fails.

class async_storages.StorageFile(name: str, storage: BaseStorage)[source]¶

Bases: object

File object managed by a storage backend.

Parameters:

name (str) – The name or identifier of the stored file.
storage (BaseStorage) – The storage backend handling file operations.

async delete() → None[source]¶

Delete the file from the storage backend.

Returns:: None
Return type:: None

async get_path() → str[source]¶

Get a URL or path to access the file.

Returns:: A URL or file path string.
Return type:: str

async get_size() → int[source]¶

Get the size of the file in bytes.

Returns:: The file size in bytes.
Return type:: int

property name: str¶

Get the name of the file.

Returns:: The name of the file in storage.
Return type:: str

async upload(file: BinaryIO) → str[source]¶

Upload a file to the storage backend.

Parameters:: file (BinaryIO) – A binary file-like object to upload.
Returns:: The name or path of the uploaded file.
Return type:: str

class async_storages.StorageImage(name: str, storage: BaseStorage, width: int = 0, height: int = 0)[source]¶

Bases: StorageFile

Image file object managed by a storage backend. Extends StorageFile by including optional image metadata such as width and height.

Parameters:

name (str) – The name or identifier of the stored image file.
storage (BaseStorage) – The storage backend handling file operations.
width (int, optional) – The width of the image in pixels. Defaults to 0 if unknown.
height (int, optional) – The height of the image in pixels. Defaults to 0 if unknown.

async get_dimensions() → tuple[int, int][source]¶

Retrieve the dimensions of the image (width and height).

If the image metadata has not been loaded yet, this method asynchronously loads it from the storage backend before returning the values.

Returns:

A tuple containing the image width and height in pixels.

Return type:

tuple[int, int]

Raises:

OSError – If the image file cannot be opened or read from storage.
ValueError – If the image file is not a valid image or dimensions cannot be determined.