FastSQLA 0.2.4__py3-none-any.whl

FastSQLA-0.2.4.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Hadrien David
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

FastSQLA-0.2.4.dist-info/METADATA

@@ -0,0 +1,261 @@
+Metadata-Version: 2.2
+Name: FastSQLA
+Version: 0.2.4
+Summary: SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination.
+Author-email: Hadrien David <bonjour@hadriendavid.com>
+License: MIT License
+Project-URL: Homepage, https://github.com/hadrien/fastsqla
+Project-URL: Documentation, https://github.com/hadrien/fastsqla
+Project-URL: Repository, https://github.com/hadrien/fastsqla
+Project-URL: Issues, https://github.com/hadrien/fastsqla/issues
+Project-URL: Changelog, https://github.com/hadrien/fastsqla/releases
+Keywords: FastAPI,SQLAlchemy,AsyncIO
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: SQL
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.6
+Requires-Dist: sqlalchemy[asyncio]>=2.0.37
+Requires-Dist: structlog>=24.4.0
+
+# 🚀 FastSQLA
+
+[![PyPI - Version](https://img.shields.io/pypi/v/FastSQLA?color=brightgreen)](https://pypi.org/project/FastSQLA/)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg)](https://conventionalcommits.org)
+[![codecov](https://codecov.io/gh/hadrien/fastsqla/graph/badge.svg?token=XK3YT60MWK)](https://codecov.io/gh/hadrien/fastsqla)
+
+`FastSQLA` is an [`SQLAlchemy`] extension for [`FastAPI`].
+It supports asynchronous `SQLAlchemy` sessions and includes built-in custimizable
+pagination.
+
+## Features
+
+<details>
+    <summary>Automatic SQLAlchemy configuration at app startup.</summary>
+
+  Using [`FastAPI` Lifespan](https://fastapi.tiangolo.com/advanced/events/#lifespan):
+```python
+from fastapi import FastAPI
+from fastsqla import lifespan
+
+app = FastAPI(lifespan=lifespan)
+```
+</details>
+<details>
+    <summary>Async SQLAlchemy session as a FastAPI dependency.</summary>
+
+```python
+...
+from fastsqla import Session
+from sqlalchemy import select
+...
+
+@app.get("/heros")
+async def get_heros(session:Session):
+    stmt = select(...)
+    result = await session.execute(stmt)
+    ...
+```
+</details>
+<details>
+    <summary>Built-in pagination.</summary>
+
+```python
+...
+from fastsqla import Page, Paginate
+from sqlalchemy import select
+...
+
+@app.get("/heros", response_model=Page[HeroModel])
+async def get_heros(paginate:Paginate):
+    return paginate(select(Hero))
+```
+</details>
+<details>
+    <summary>Allows pagination customization.</summary>
+
+```python
+...
+from fastapi import new_pagination
+...
+
+Paginate = new_pagination(min_page_size=5, max_page_size=500)
+
+@app.get("/heros", response_model=Page[HeroModel])
+async def get_heros(paginate:Paginate):
+    return paginate(select(Hero))
+```
+</details>
+
+And more ...
+<!-- <details><summary></summary></details> -->
+
+## Installing
+
+Using [uv](https://docs.astral.sh/uv/):
+```bash
+uv add fastsqla
+```
+
+Using [pip](https://pip.pypa.io/):
+```
+pip install fastsqla
+```
+
+## Quick Example
+
+```python
+# example.py
+from http import HTTPStatus
+
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Mapped, mapped_column
+
+from fastsqla import Base, Item, Page, Paginate, Session, lifespan
+
+app = FastAPI(lifespan=lifespan)
+
+
+class Hero(Base):
+    __tablename__ = "hero"
+    id: Mapped[int] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(unique=True)
+    secret_identity: Mapped[str]
+
+
+class HeroBase(BaseModel):
+    name: str
+    secret_identity: str
+
+
+class HeroModel(HeroBase):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+
+
+@app.get("/heros", response_model=Page[HeroModel])
+async def list_users(paginate: Paginate):
+    return await paginate(select(Hero))
+
+
+@app.get("/heros/{hero_id}", response_model=Item[HeroModel])
+async def get_user(hero_id: int, session: Session):
+    hero = await session.get(Hero, hero_id)
+    if hero is None:
+        raise HTTPException(HTTPStatus.NOT_FOUND, "Hero not found")
+    return {"data": hero}
+
+
+@app.post("/heros", response_model=Item[HeroModel])
+async def create_user(new_hero: HeroBase, session: Session):
+    hero = Hero(**new_hero.model_dump())
+    session.add(hero)
+    try:
+        await session.flush()
+    except IntegrityError:
+        raise HTTPException(HTTPStatus.CONFLICT, "Duplicate hero name")
+    return {"data": hero}
+```
+
+> [!NOTE]
+> Sqlite is used for the sake of the example.
+> FastSQLA is compatible with all async db drivers that SQLAlchemy is compatible with.
+
+<details>
+    <summary>Create an <code>sqlite3</code> db:</summary>
+
+```bash
+sqlite3 db.sqlite <<EOF
+CREATE TABLE hero (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    name            TEXT NOT NULL UNIQUE, -- Hero name (e.g., Superman)
+    secret_identity TEXT NOT NULL         -- Secret identity (e.g., Clark Kent)
+);
+
+-- Insert heroes with hero name and secret identity
+INSERT INTO hero (name, secret_identity) VALUES ('Superman', 'Clark Kent');
+INSERT INTO hero (name, secret_identity) VALUES ('Batman', 'Bruce Wayne');
+INSERT INTO hero (name, secret_identity) VALUES ('Wonder Woman', 'Diana Prince');
+INSERT INTO hero (name, secret_identity) VALUES ('Iron Man', 'Tony Stark');
+INSERT INTO hero (name, secret_identity) VALUES ('Spider-Man', 'Peter Parker');
+INSERT INTO hero (name, secret_identity) VALUES ('Captain America', 'Steve Rogers');
+INSERT INTO hero (name, secret_identity) VALUES ('Black Widow', 'Natasha Romanoff');
+INSERT INTO hero (name, secret_identity) VALUES ('Thor', 'Thor Odinson');
+INSERT INTO hero (name, secret_identity) VALUES ('Scarlet Witch', 'Wanda Maximoff');
+INSERT INTO hero (name, secret_identity) VALUES ('Doctor Strange', 'Stephen Strange');
+INSERT INTO hero (name, secret_identity) VALUES ('The Flash', 'Barry Allen');
+INSERT INTO hero (name, secret_identity) VALUES ('Green Lantern', 'Hal Jordan');
+EOF
+```
+
+</details>
+
+<details>
+    <summary>Install dependencies & run the app</summary>
+
+```bash
+pip install uvicorn aiosqlite fastsqla
+sqlalchemy_url=sqlite+aiosqlite:///db.sqlite?check_same_thread=false uvicorn example:app
+```
+
+</details>
+
+Execute `GET /heros?offset=10`:
+
+```bash
+curl -X 'GET' \
+'http://127.0.0.1:8000/heros?offset=10&limit=10' \
+-H 'accept: application/json'
+```
+Returns:
+```json
+{
+  "data": [
+    {
+      "name": "The Flash",
+      "secret_identity": "Barry Allen",
+      "id": 11
+    },
+    {
+      "name": "Green Lantern",
+      "secret_identity": "Hal Jordan",
+      "id": 12
+    }
+  ],
+  "meta": {
+    "offset": 10,
+    "total_items": 12,
+    "total_pages": 2,
+    "page_number": 2
+  }
+}
+```
+
+[`FastAPI`]: https://fastapi.tiangolo.com/
+[`SQLAlchemy`]: http://sqlalchemy.org/

FastSQLA-0.2.4.dist-info/RECORD

@@ -0,0 +1,6 @@
+fastsqla.py,sha256=FRN1RhVQPlD7hMNZG7wvSWZ7qdfXaqjmB3pXVa3z6Yw,5188
+FastSQLA-0.2.4.dist-info/LICENSE,sha256=uNKcyfhTq0YUZxgSDiDGBHoJfflKjGWecSfWxpYe_O4,1070
+FastSQLA-0.2.4.dist-info/METADATA,sha256=b0Lb3jCdUsQEEOLdW881z5nlLtfXNwaH3ir8PQRcSuw,7658
+FastSQLA-0.2.4.dist-info/WHEEL,sha256=In9FTNxeP60KnTkGw7wk6mJPYd_dQSjEZmXdBdMCI-8,91
+FastSQLA-0.2.4.dist-info/top_level.txt,sha256=Uh-1ssTtuSS4_SYCBeDoDVOxqWTrRAPEBZkuih5isSE,9
+FastSQLA-0.2.4.dist-info/RECORD,,

FastSQLA-0.2.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (75.8.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

FastSQLA-0.2.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastsqla

fastsqla.py

@@ -0,0 +1,196 @@
+import math
+import os
+from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
+from contextlib import asynccontextmanager
+from typing import Annotated, Generic, TypeVar, TypedDict
+
+from fastapi import Depends, Query
+from pydantic import BaseModel, Field
+from sqlalchemy import Result, Select, func, select
+from sqlalchemy.ext.asyncio import (
+    AsyncEngine,
+    AsyncSession,
+    async_engine_from_config,
+    async_sessionmaker,
+)
+from sqlalchemy.ext.declarative import DeferredReflection
+from sqlalchemy.orm import DeclarativeBase
+from structlog import get_logger
+
+__all__ = [
+    "Base",
+    "Collection",
+    "Item",
+    "Page",
+    "Paginate",
+    "PaginateType",
+    "Session",
+    "lifespan",
+    "new_pagination",
+    "open_session",
+]
+
+SessionFactory = async_sessionmaker(expire_on_commit=False)
+
+logger = get_logger(__name__)
+
+
+class Base(DeclarativeBase, DeferredReflection):
+    __abstract__ = True
+
+
+class State(TypedDict):
+    fastsqla_engine: AsyncEngine
+
+
+@asynccontextmanager
+async def lifespan(_) -> AsyncGenerator[State, None]:
+    prefix = "sqlalchemy_"
+    sqla_config = {k.lower(): v for k, v in os.environ.items()}
+    try:
+        engine = async_engine_from_config(sqla_config, prefix=prefix)
+
+    except KeyError as exc:
+        raise Exception(f"Missing {prefix}{exc.args[0]} in environ.") from exc
+
+    async with engine.begin() as conn:
+        await conn.run_sync(Base.prepare)
+
+    SessionFactory.configure(bind=engine)
+
+    await logger.ainfo("Configured SQLAlchemy.")
+
+    yield {"fastsqla_engine": engine}
+
+    SessionFactory.configure(bind=None)
+    await engine.dispose()
+
+    await logger.ainfo("Cleared SQLAlchemy config.")
+
+
+@asynccontextmanager
+async def open_session() -> AsyncGenerator[AsyncSession, None]:
+    session = SessionFactory()
+    try:
+        yield session
+
+    except Exception:
+        await logger.awarning("context failed: rolling back session.")
+        await session.rollback()
+        raise
+
+    else:
+        await logger.adebug("context succeeded: committing session.")
+        try:
+            await session.commit()
+
+        except Exception:
+            await logger.aexception("commit failed: rolling back session")
+            await session.rollback()
+            raise
+
+    finally:
+        await logger.adebug("closing session.")
+        await session.close()
+
+
+async def new_session() -> AsyncGenerator[AsyncSession, None]:
+    async with open_session() as session:
+        yield session
+
+
+Session = Annotated[AsyncSession, Depends(new_session)]
+
+
+class Meta(BaseModel):
+    offset: int = Field(description="Current page offset.")
+    total_items: int = Field(description="Total number of items.")
+    total_pages: int = Field(description="Total number of pages.")
+    page_number: int = Field(description="Current page number. Starts at 1.")
+
+
+T = TypeVar("T")
+
+
+class Item(BaseModel, Generic[T]):
+    data: T
+
+
+class Collection(BaseModel, Generic[T]):
+    data: list[T]
+
+
+class Page(Collection[T]):
+    meta: Meta
+
+
+async def _query_count(session: Session, stmt: Select) -> int:
+    result = await session.execute(select(func.count()).select_from(stmt.subquery()))
+    return result.scalar()  # type: ignore
+
+
+async def _paginate(
+    session: Session,
+    stmt: Select,
+    total_items: int,
+    offset: int,
+    limit: int,
+    result_processor: Callable[[Result], Iterable],
+):
+    total_pages = math.ceil(total_items / limit)
+    page_number = math.floor(offset / limit + 1)
+    result = await session.execute(stmt.offset(offset).limit(limit))
+    data = result_processor(result)
+    return Page(
+        data=data,  # type:ignore
+        meta=Meta(
+            offset=offset,
+            total_items=total_items,
+            total_pages=total_pages,
+            page_number=page_number,
+        ),
+    )
+
+
+def new_pagination(
+    min_page_size: int = 10,
+    max_page_size: int = 100,
+    query_count_dependency: Callable[..., Awaitable[int]] | None = None,
+    result_processor: Callable[[Result], Iterable] = lambda result: iter(
+        result.unique().scalars()
+    ),
+):
+    def default_dependency(
+        session: Session,
+        offset: int = Query(0, ge=0),
+        limit: int = Query(min_page_size, ge=1, le=max_page_size),
+    ) -> PaginateType[T]:
+        async def paginate(stmt: Select) -> Page:
+            total_items = await _query_count(session, stmt)
+            return await _paginate(
+                session, stmt, total_items, offset, limit, result_processor
+            )
+
+        return paginate
+
+    def dependency(
+        session: Session,
+        offset: int = Query(0, ge=0),
+        limit: int = Query(min_page_size, ge=1, le=max_page_size),
+        total_items: int = Depends(query_count_dependency),
+    ) -> PaginateType[T]:
+        async def paginate(stmt: Select) -> Page:
+            return await _paginate(
+                session, stmt, total_items, offset, limit, result_processor
+            )
+
+        return paginate
+
+    if query_count_dependency:
+        return dependency
+    else:
+        return default_dependency
+
+
+type PaginateType[T] = Callable[[Select], Awaitable[Page[T]]]
+Paginate = Annotated[PaginateType[T], Depends(new_pagination())]