chore: export BaseStorage from module

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

docs/source/async_storages.rst

@@ -1,5 +1,5 @@
 async_storages
-=============
+==============
 
 .. automodule:: async_storages
     :members:

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"]

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