fastapi-async-storages 0.1.0__tar.gz

fastapi_async_storages-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.3
+Name: fastapi-async-storages
+Version: 0.1.0
+Summary: A powerful, extensible, and async-ready cloud object storage backend for FastAPI.
+Author: stabldev
+Author-email: stabldev <thestabldev@gmail.com>
+Requires-Dist: aioboto3>=15.4.0 ; extra == 's3'
+Requires-Python: >=3.12
+Provides-Extra: s3
+Description-Content-Type: text/markdown
+
+# fastapi-async-storages
+
+A powerful, extensible, and async-ready cloud object storage backend for FastAPI.
+
+> Drop-in, plug-and-play cloud storage for your FastAPI apps; with full async support.\
+> Inspired by [fastapi-storages](https://github.com/aminalaee/fastapi-storages), built on modern async patterns using [aioboto3](https://github.com/terricain/aioboto3).
+
+## Features
+
+* Fully asynchronous storage interface designed for FastAPI applications
+* Async S3 backend powered by [aioboto3](https://github.com/terricain/aioboto3)
+* [SQLAlchemy](https://sqlalchemy.org/) and [SQLModel](https://sqlmodel.tiangolo.com/) integration
+* Typed and extensible design
+* Supports FastAPI dependency injection
+
+## Installation
+
+```bash
+uv add fastapi-async-storages
+# for s3 support:
+uv add "fastapi-async-storages[s3]"
+```
+
+## Documentation
+
+Full documentation is available on:\
+https://fastapi-async-storages.readthedocs.io
+
+## Example: FastAPI
+
+```py
+from fastapi import FastAPI, UploadFile
+from sqlalchemy import Column, Integer
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker, declarative_base
+from async_storages import S3Storage
+from async_storages.integrations.sqlalchemy import FileType
+
+Base = declarative_base()
+
+app = FastAPI()
+storage = S3Storage(...)
+engine = create_async_engine("sqlite+aiosqlite:///test.db", echo=True)
+
+# create AsyncSession factory
+AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+class Example(Base):
+    __tablename__ = "example"
+
+    id = Column(Integer, primary_key=True)
+    file = Column(FileType(storage=storage))
+
+# create tables inside an async context
+@app.on_event("startup")
+async def startup():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+@app.post("/upload/")
+async def create_upload_file(file: UploadFile):
+    file_name = f"uploads/{file.filename}"
+    # upload before commit due to the sqlalchemy binding being sync
+    await storage.upload(file.file, file_name)
+
+    example = Example(file=file)
+    async with AsyncSessionLocal() as session:
+        session.add(example)
+        await session.commit()
+        return {"filename": example.file.name}
+```
+
+## License
+
+[MIT](LICENSE) © 2025 ^\_^ [`@stabldev`](https://github.com/stabldev)

fastapi_async_storages-0.1.0/README.md

@@ -0,0 +1,75 @@
+# fastapi-async-storages
+
+A powerful, extensible, and async-ready cloud object storage backend for FastAPI.
+
+> Drop-in, plug-and-play cloud storage for your FastAPI apps; with full async support.\
+> Inspired by [fastapi-storages](https://github.com/aminalaee/fastapi-storages), built on modern async patterns using [aioboto3](https://github.com/terricain/aioboto3).
+
+## Features
+
+* Fully asynchronous storage interface designed for FastAPI applications
+* Async S3 backend powered by [aioboto3](https://github.com/terricain/aioboto3)
+* [SQLAlchemy](https://sqlalchemy.org/) and [SQLModel](https://sqlmodel.tiangolo.com/) integration
+* Typed and extensible design
+* Supports FastAPI dependency injection
+
+## Installation
+
+```bash
+uv add fastapi-async-storages
+# for s3 support:
+uv add "fastapi-async-storages[s3]"
+```
+
+## Documentation
+
+Full documentation is available on:\
+https://fastapi-async-storages.readthedocs.io
+
+## Example: FastAPI
+
+```py
+from fastapi import FastAPI, UploadFile
+from sqlalchemy import Column, Integer
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
+from sqlalchemy.orm import sessionmaker, declarative_base
+from async_storages import S3Storage
+from async_storages.integrations.sqlalchemy import FileType
+
+Base = declarative_base()
+
+app = FastAPI()
+storage = S3Storage(...)
+engine = create_async_engine("sqlite+aiosqlite:///test.db", echo=True)
+
+# create AsyncSession factory
+AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+class Example(Base):
+    __tablename__ = "example"
+
+    id = Column(Integer, primary_key=True)
+    file = Column(FileType(storage=storage))
+
+# create tables inside an async context
+@app.on_event("startup")
+async def startup():
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.metadata.create_all)
+
+@app.post("/upload/")
+async def create_upload_file(file: UploadFile):
+    file_name = f"uploads/{file.filename}"
+    # upload before commit due to the sqlalchemy binding being sync
+    await storage.upload(file.file, file_name)
+
+    example = Example(file=file)
+    async with AsyncSessionLocal() as session:
+        session.add(example)
+        await session.commit()
+        return {"filename": example.file.name}
+```
+
+## License
+
+[MIT](LICENSE) © 2025 ^\_^ [`@stabldev`](https://github.com/stabldev)

fastapi_async_storages-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[project]
+name = "fastapi-async-storages"
+version = "0.1.0"
+description = "A powerful, extensible, and async-ready cloud object storage backend for FastAPI."
+readme = "README.md"
+authors = [
+    { name = "stabldev", email = "thestabldev@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = []
+
+[project.optional-dependencies]
+s3 = ["aioboto3>=15.4.0"]
+
+[dependency-groups]
+dev = [
+    "aiosqlite>=0.21.0",
+    "pillow>=12.0.0",
+    "pytest>=8.4.2",
+    "pytest-aioboto3>=0.6.0",
+    "pytest-asyncio>=1.2.0",
+    "sqlalchemy>=2.0.44",
+]
+docs = [
+    "furo>=2025.9.25",
+    "sphinx>=8.2.3",
+]
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "async_storages"
+
+[tool.pyright]
+reportMissingTypeStubs = "none"
+reportUnknownMemberType = "none"
+reportUnusedCallResult = "none"
+reportUnknownVariableType = "none"
+reportAny = "none"
+reportExplicitAny = "none"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[build-system]
+requires = ["uv_build>=0.8.20,<0.10.0"]
+build-backend = "uv_build"

fastapi_async_storages-0.1.0/src/async_storages/__init__.py

@@ -0,0 +1,5 @@
+from .base import BaseStorage, StorageFile, StorageImage
+from .s3 import S3Storage
+
+__version__ = "0.1.0"
+__all__ = ["BaseStorage", "StorageFile", "StorageImage", "S3Storage"]

fastapi_async_storages-0.1.0/src/async_storages/base.py

@@ -0,0 +1,202 @@
+# pyright: reportUnusedParameter=none
+from abc import ABC, abstractmethod
+import asyncio
+from io import BytesIO
+from PIL import Image
+from typing import BinaryIO
+
+
+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_path(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
+
+
+class StorageFile:
+    """
+    File object managed by a storage backend.
+
+    :param name: The name or identifier of the stored file.
+    :type name: str
+    :param storage: The storage backend handling file operations.
+    :type storage: BaseStorage
+    """
+
+    def __init__(self, name: str, storage: BaseStorage) -> None:
+        self._name: str = name
+        self._storage: BaseStorage = storage
+
+    @property
+    def name(self) -> str:
+        """
+        Get the name of the file.
+
+        :return: The name of the file in storage.
+        :rtype: str
+        """
+        return self._name
+
+    async def get_size(self) -> int:
+        """
+        Get the size of the file in bytes.
+
+        :return: The file size in bytes.
+        :rtype: int
+        """
+        return await self._storage.get_size(self._name)
+
+    async def get_path(self) -> str:
+        """
+        Get a URL or path to access the file.
+
+        :return: A URL or file path string.
+        :rtype: str
+        """
+        return await self._storage.get_path(self._name)
+
+    async def upload(self, file: BinaryIO) -> str:
+        """
+        Upload a file to the storage backend.
+
+        :param file: A binary file-like object to upload.
+        :type file: BinaryIO
+        :return: The name or path of the uploaded file.
+        :rtype: str
+        """
+        return await self._storage.upload(file=file, name=self._name)
+
+    async def delete(self) -> None:
+        """
+        Delete the file from the storage backend.
+
+        :return: None
+        :rtype: None
+        """
+        await self._storage.delete(self._name)
+
+
+class StorageImage(StorageFile):
+    """
+    Image file object managed by a storage backend.
+    Extends :class:`StorageFile` by including optional image metadata such as width and height.
+
+    :param name: The name or identifier of the stored image file.
+    :type name: str
+    :param storage: The storage backend handling file operations.
+    :type storage: BaseStorage
+    :param width: The width of the image in pixels. Defaults to ``0`` if unknown.
+    :type width: int, optional
+    :param height: The height of the image in pixels. Defaults to ``0`` if unknown.
+    :type height: int, optional
+    """
+
+    def __init__(
+        self, name: str, storage: BaseStorage, width: int = 0, height: int = 0
+    ) -> None:
+        super().__init__(name, storage)
+        self._width: int = width
+        self._height: int = height
+        self._meta_loaded: bool = bool(width and height)
+
+    async def _load_meta(self) -> None:
+        data = await self._storage.open(self.name)
+
+        def _extract_meta() -> tuple[int, int]:
+            with Image.open(data) as image:
+                return image.size
+
+        self._width, self._height = await asyncio.to_thread(_extract_meta)
+        self._meta_loaded = True
+
+    async def get_dimensions(self) -> tuple[int, int]:
+        """
+        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.
+
+        :return: A tuple containing the image width and height in pixels.
+        :rtype: tuple[int, int]
+        :raises OSError: If the image file cannot be opened or read from storage.
+        :raises ValueError: If the image file is not a valid image or dimensions cannot be determined.
+        """
+        if not self._meta_loaded:
+            await self._load_meta()
+        return self._width, self._height

fastapi_async_storages-0.1.0/src/async_storages/integrations/sqlalchemy.py

@@ -0,0 +1,75 @@
+from typing import Any, override
+from sqlalchemy.engine.interfaces import Dialect
+from sqlalchemy.types import TypeDecorator, TypeEngine, Unicode
+
+from async_storages import StorageFile, StorageImage
+from async_storages.base import BaseStorage
+
+
+class FileType(TypeDecorator[Any]):
+    """
+    SQLAlchemy column type for representing stored files.
+
+    This type integrates with :class:`~async_storages.base.BaseStorage`
+    to automatically wrap database values (file names) into
+    :class:`~async_storages.StorageFile` objects when queried.
+
+    :param storage: The storage backend used to manage file operations.
+    :type storage: BaseStorage
+    :param args: Additional positional arguments passed to ``TypeDecorator``.
+    :param kwargs: Additional keyword arguments passed to ``TypeDecorator``.
+    """
+
+    impl: TypeEngine[Any] | type[TypeEngine[Any]] = Unicode
+    cache_ok: bool | None = True
+
+    def __init__(self, storage: BaseStorage, *args: Any, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.storage: BaseStorage = storage
+
+    @override
+    def process_bind_param(self, value: Any, dialect: Dialect) -> str:
+        if value is None:
+            return value
+        if isinstance(value, str):
+            return value
+
+        name = getattr(value, "name", None)
+        if name:
+            return name
+        return str(value)
+
+    @override
+    def process_result_value(
+        self, value: Any | None, dialect: Dialect
+    ) -> StorageFile | None:
+        if value is None:
+            return None
+        return StorageFile(name=value, storage=self.storage)
+
+
+class ImageType(FileType):
+    """
+    SQLAlchemy column type for representing stored image files.
+
+    This type extends :class:`~.FileType` to automatically wrap
+    database values (image file names) into
+    :class:`~async_storages.StorageImage` objects when queried.
+
+    It integrates with a configured :class:`~async_storages.base.BaseStorage`
+    backend to provide convenient access to image operations such as
+    resizing, thumbnail generation, or metadata retrieval.
+
+    :param storage: The storage backend used to manage image file operations.
+    :type storage: BaseStorage
+    :param args: Additional positional arguments passed to ``FileType``.
+    :param kwargs: Additional keyword arguments passed to ``FileType``.
+    """
+
+    @override
+    def process_result_value(
+        self, value: Any | None, dialect: Dialect
+    ) -> StorageFile | None:
+        if value is None:
+            return None
+        return StorageImage(name=value, storage=self.storage)

fastapi_async_storages-0.1.0/src/async_storages/s3.py

@@ -0,0 +1,234 @@
+# pyright: reportPrivateLocalImportUsage=none
+from io import BytesIO
+import mimetypes
+from pathlib import Path
+from typing import Any, BinaryIO, override
+
+from async_storages.base import BaseStorage
+from async_storages.utils import secure_filename
+
+try:
+    import aioboto3
+    from botocore.exceptions import ClientError
+except ImportError:
+    raise ImportError(
+        "'aioboto3' is not installed. Install with 'fastapi-async-storages[s3]'."
+    )
+
+
+class S3Storage(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.
+
+    :param bucket_name: Name of the S3 bucket.
+    :type bucket_name: str
+    :param endpoint_url: The S3 endpoint hostname (without protocol).
+    :type endpoint_url: str
+    :param aws_access_key_id: AWS access key ID for authentication.
+    :type aws_access_key_id: str
+    :param aws_secret_access_key: AWS secret access key for authentication.
+    :type aws_secret_access_key: str
+    :param region_name: AWS region name (optional).
+    :type region_name: str or None
+    :param use_ssl: Whether to use HTTPS (True) or HTTP (False).
+    :type use_ssl: bool
+    :param default_acl: Default Access Control List (ACL) to apply when uploading files.
+    :type default_acl: str or None
+    :param custom_domain: Custom domain for serving files (e.g. CDN).
+    :type custom_domain: str or None
+    :param querystring_auth: Whether to generate presigned URLs with query parameters.
+    :type querystring_auth: bool
+    :raises ImportError: If ``aioboto3`` is not installed.
+    """
+
+    def __init__(
+        self,
+        bucket_name: str,
+        endpoint_url: str,
+        aws_access_key_id: str,
+        aws_secret_access_key: str,
+        region_name: str | None = None,
+        use_ssl: bool = True,
+        default_acl: str | None = None,
+        custom_domain: str | None = None,
+        querystring_auth: bool = False,
+    ) -> None:
+        assert not endpoint_url.startswith("http"), (
+            "Endpoint should not contain protocol"
+        )
+
+        self.bucket_name: str = bucket_name
+        self.endpoint_url: str = endpoint_url.rstrip("/")
+        self.aws_access_key_id: str = aws_access_key_id
+        self.aws_secret_access_key: str = aws_secret_access_key
+        self.region_name: str | None = region_name
+        self.use_ssl: bool = use_ssl
+        self.default_acl: str | None = default_acl
+        self.custom_domain: str | None = custom_domain
+        self.querystring_auth: bool = querystring_auth
+
+        self._http_scheme: str = "https" if self.use_ssl else "http"
+        self._url: str = f"{self._http_scheme}://{self.endpoint_url}"
+        self._session: "aioboto3.Session" = aioboto3.Session()
+
+    def _get_s3_client(self) -> Any:
+        return self._session.client(
+            "s3",
+            region_name=self.region_name,
+            use_ssl=self.use_ssl,
+            endpoint_url=self._url,
+            aws_access_key_id=self.aws_access_key_id,
+            aws_secret_access_key=self.aws_secret_access_key,
+        )
+
+    @override
+    def get_name(self, name: str) -> str:
+        """
+        Sanitize and normalize a file path before uploading to S3.
+
+        Removes unsafe path components (``..`` or ``.``) and ensures each
+        segment is a secure filename.
+
+        :param name: Original file name or path.
+        :type name: str
+        :return: Sanitized file path.
+        :rtype: str
+        """
+        parts = Path(name).parts
+        safe_parts: list[str] = []
+
+        for part in parts:
+            if part not in ("..", ".", ""):
+                safe_parts.append(secure_filename(part))
+
+        safe_path = Path(*safe_parts)
+        return str(safe_path)
+
+    @override
+    async def get_size(self, name: str) -> int:
+        """
+        Retrieve the size of an S3 object in bytes.
+
+        :param name: The object key (path) in the S3 bucket.
+        :type name: str
+        :return: The file size in bytes, or ``0`` if the object does not exist.
+        :rtype: int
+        :raises botocore.exceptions.ClientError: If an unexpected S3 error occurs.
+        """
+        name = self.get_name(name)
+
+        async with self._get_s3_client() as s3_client:
+            try:
+                res = await s3_client.head_object(Bucket=self.bucket_name, Key=name)
+                return int(res.get("ContentLength", 0))
+            except ClientError as e:
+                code = e.response.get("Error", {}).get("Code")
+                status = e.response.get("ResponseMetadata", {}).get("HTTPStatusCode")
+
+                if code in ("NoSuchKey", "NotFound") or status == 404:
+                    return 0
+                raise
+
+    @override
+    async def get_path(self, name: str) -> str:
+        """
+        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.
+
+        :param name: The object key (path) in the S3 bucket.
+        :type name: str
+        :return: A direct or presigned URL for the file.
+        :rtype: str
+        """
+        if self.custom_domain:
+            return f"{self._http_scheme}://{self.custom_domain}/{name}"
+        elif self.querystring_auth:
+            async with self._get_s3_client() as s3_client:
+                params = {"Bucket": self.bucket_name, "Key": name}
+                return await s3_client.generate_presigned_url(
+                    "get_object", Params=params
+                )
+        else:
+            url = f"{self._http_scheme}://{self.endpoint_url}/{self.bucket_name}/{name}"
+            return url
+
+    @override
+    async def open(self, name: str) -> BytesIO:
+        """
+        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.
+
+        :param name: The object key (path) in the S3 bucket.
+        :type name: str
+        :return: A BytesIO object containing the file's contents.
+        :rtype: BytesIO
+        :raises FileNotFoundError: If the object is not found.
+        :raises botocore.exceptions.ClientError: If the object cannot be fetched.
+        """
+        name = self.get_name(name)
+
+        async with self._get_s3_client() as s3_client:
+            try:
+                response = await s3_client.get_object(Bucket=self.bucket_name, Key=name)
+            except ClientError as e:
+                code = e.response.get("Error", {}).get("Code")
+                if code in ("NoSuchKey", "NotFound"):
+                    raise FileNotFoundError(
+                        f"Object not found in bucket: {name}"
+                    ) from e
+                raise
+
+            async with response["Body"] as stream:
+                data = await stream.read()
+        return BytesIO(data)
+
+    @override
+    async def upload(self, file: BinaryIO, name: str) -> str:
+        """
+        Upload a file object to the configured S3 bucket.
+
+        :param file: Binary file-like object to upload.
+        :type file: BinaryIO
+        :param name: Target object key (path) in the S3 bucket.
+        :type name: str
+        :return: The name or key of the uploaded object.
+        :rtype: str
+        :raises botocore.exceptions.ClientError: If the upload fails.
+        """
+        name = self.get_name(name)
+        content_type, _ = mimetypes.guess_type(name)
+        extra_args = {"ContentType": content_type or "application/octet-stream"}
+        if self.default_acl:
+            extra_args["ACL"] = self.default_acl
+
+        async with self._get_s3_client() as s3_client:
+            file.seek(0)
+            await s3_client.put_object(
+                Bucket=self.bucket_name, Key=name, Body=file, **extra_args
+            )
+        return name
+
+    @override
+    async def delete(self, name: str) -> None:
+        """
+        Delete an object from the S3 bucket.
+
+        :param name: The object key (path) to delete.
+        :type name: str
+        :return: None
+        :rtype: None
+        :raises botocore.exceptions.ClientError: If the delete operation fails.
+        """
+        async with self._get_s3_client() as s3_client:
+            try:
+                await s3_client.delete_object(Bucket=self.bucket_name, Key=name)
+            except ClientError as e:
+                if e.response.get("Error", {}).get("Code") != "NoSuchKey":
+                    raise

fastapi_async_storages-0.1.0/src/async_storages/utils.py

@@ -0,0 +1,16 @@
+import os
+import re
+
+_filename_ascii_strip_re = re.compile(r"[^A-Za-z0-9_.-]")
+
+
+# https://werkzeug.palletsprojects.com/en/stable/utils/#werkzeug.utils.secure_filename
+# https://github.com/pallets/werkzeug/blob/504a8c4fbda9b8b2fd09e817544ffd228f23458e/src/werkzeug/utils.py#L195
+def secure_filename(filename: str) -> str:
+    for sep in os.path.sep, os.path.altsep:
+        if sep:
+            filename = filename.replace(sep, " ")
+
+    normalized_filename = _filename_ascii_strip_re.sub("", "_".join(filename.split()))
+    filename = str(normalized_filename).strip("._")
+    return filename