diff --git a/docs/source/async_storages.integrations.rst b/docs/source/async_storages.integrations.rst index 35bd434..145edc7 100644 --- a/docs/source/async_storages.integrations.rst +++ b/docs/source/async_storages.integrations.rst @@ -1,5 +1,5 @@ async_storages.integrations -========================= +=========================== .. autoclass:: async_storages.integrations.sqlalchemy.FileType :exclude-members: cache_ok, impl, process_bind_param, process_result_value diff --git a/docs/source/async_storages.rst b/docs/source/async_storages.rst index 6975e75..0a7f276 100644 --- a/docs/source/async_storages.rst +++ b/docs/source/async_storages.rst @@ -1,5 +1,5 @@ async_storages -============= +============== .. automodule:: async_storages :members: diff --git a/src/async_storages/__init__.py b/src/async_storages/__init__.py index f148927..54c1f4a 100644 --- a/src/async_storages/__init__.py +++ b/src/async_storages/__init__.py @@ -1,5 +1,5 @@ -from .base import StorageFile, StorageImage +from .base import BaseStorage, StorageFile, StorageImage from .s3 import S3Storage __version__ = "0.1.0" -__all__ = ["StorageFile", "StorageImage", "S3Storage"] +__all__ = ["BaseStorage", "StorageFile", "StorageImage", "S3Storage"] diff --git a/src/async_storages/base.py b/src/async_storages/base.py index 959bdff..f4170c8 100644 --- a/src/async_storages/base.py +++ b/src/async_storages/base.py @@ -7,28 +7,85 @@ class BaseStorage(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 def get_name(self, name: str) -> str: + """ + Normalize or sanitize a given file name or path. + + :param name: Original file name or path. + :type name: str + :return: A sanitized and valid file name or path for storage. + :rtype: str + """ pass @abstractmethod async def get_size(self, name: str) -> int: + """ + Retrieve the size of a stored file in bytes. + + :param name: Original file name or path. + :type name: str + :return: File size in bytes. + :rtype: int + """ pass @abstractmethod async def get_url(self, name: str) -> str: + """ + Generate a URL or path to access the stored file. + + :param name: Original file name or path. + :type name: str + :return: A URL or accessible path to the file. + :rtype: str + """ pass @abstractmethod async def open(self, name: str) -> BytesIO: + """ + Open and return a stored file as an in-memory binary stream. + + :param name: Original file name or path. + :type name: str + :return: A ``BytesIO`` object containing the file's binary data. + :rtype: BytesIO + """ pass @abstractmethod async def upload(self, file: BinaryIO, name: str) -> str: + """ + Upload a binary file to the storage backend. + + :param file: A binary file-like object to upload. + :type file: BinaryIO + :param name: Original file name or path. + :type name: str + :return: The final stored file name or path. + :rtype: str + """ pass @abstractmethod async def delete(self, name: str) -> None: + """ + Delete a stored file from the backend. + + :param name: Original file name or path. + :return: None + :rtype: None + """ pass