FastSQLA 0.2.4__py3-none-any.whl → 0.4.4__py3-none-any.whl

fastsqla-0.4.4.dist-info/METADATA

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: FastSQLA
+Version: 0.4.4
+Summary: SQLAlchemy extension for FastAPI that supports asynchronous sessions and includes built-in pagination.
+Author-email: Hadrien David <h@driendavid.com>
+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: 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
+Requires-Dist: fastapi>=0.115.6
+Requires-Dist: sqlalchemy[asyncio]>=2.0.37
+Requires-Dist: structlog>=24.4.0
+Provides-Extra: docs
+Requires-Dist: mkdocs-glightbox>=0.4.0; extra == "docs"
+Requires-Dist: mkdocs-llmstxt>=0.2.0; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5.50; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.27.0; extra == "docs"
+Provides-Extra: sqlmodel
+Requires-Dist: sqlmodel>=0.0.22; extra == "sqlmodel"
+
+# FastSQLA
+
+_Async SQLAlchemy 2.0+ for FastAPI — boilerplate, pagination, and seamless session management._
+
+[![PyPI - Version](https://img.shields.io/pypi/v/FastSQLA?color=brightgreen)](https://pypi.org/project/FastSQLA/)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/hadrien/fastsqla/ci.yml?branch=main&logo=github&label=CI)](https://github.com/hadrien/FastSQLA/actions?query=branch%3Amain+event%3Apush)
+[![Codecov](https://img.shields.io/codecov/c/github/hadrien/fastsqla?token=XK3YT60MWK&logo=codecov)](https://codecov.io/gh/hadrien/FastSQLA)
+[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-brightgreen.svg)](https://conventionalcommits.org)
+[![GitHub License](https://img.shields.io/github/license/hadrien/fastsqla)](https://github.com/hadrien/FastSQLA/blob/main/LICENSE)
+[![🍁 With love from Canada](https://img.shields.io/badge/With%20love%20from%20Canada-ffffff?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSI2MDAiIGhlaWdodD0iNjAwIiB2aWV3Qm94PSItMjAxNSAtMjAwMCA0MDMwIDQwMzAiPjxwYXRoIGZpbGw9IiNmMDAiIGQ9Im0tOTAgMjAzMCA0NS04NjNhOTUgOTUgMCAwIDAtMTExLTk4bC04NTkgMTUxIDExNi0zMjBhNjUgNjUgMCAwIDAtMjAtNzNsLTk0MS03NjIgMjEyLTk5YTY1IDY1IDAgMCAwIDM0LTc5bC0xODYtNTcyIDU0MiAxMTVhNjUgNjUgMCAwIDAgNzMtMzhsMTA1LTI0NyA0MjMgNDU0YTY1IDY1IDAgMCAwIDExMS01N2wtMjA0LTEwNTIgMzI3IDE4OWE2NSA2NSAwIDAgMCA5MS0yN2wzMzItNjUyIDMzMiA2NTJhNjUgNjUgMCAwIDAgOTEgMjdsMzI3LTE4OS0yMDQgMTA1MmE2NSA2NSAwIDAgMCAxMTEgNTdsNDIzLTQ1NCAxMDUgMjQ3YTY1IDY1IDAgMCAwIDczIDM4bDU0Mi0xMTUtMTg2IDU3MmE2NSA2NSAwIDAgMCAzNCA3OWwyMTIgOTktOTQxIDc2MmE2NSA2NSAwIDAgMC0yMCA3M2wxMTYgMzIwLTg1OS0xNTFhOTUgOTUgMCAwIDAtMTExIDk4bDQ1IDg2M3oiLz48L3N2Zz4K)](https://montrealpython.org)
+
+**Documentation**: [https://hadrien.github.io/FastSQLA/](https://hadrien.github.io/FastSQLA/)
+
+**Github Repo:** [https://github.com/hadrien/fastsqla](https://github.com/hadrien/fastsqla)
+
+-----------------------------------------------------------------------------------------
+
+`FastSQLA` is an async [`SQLAlchemy 2.0+`](https://docs.sqlalchemy.org/en/20/)
+extension for [`FastAPI`](https://fastapi.tiangolo.com/) with built-in pagination,
+[`SQLModel`](http://sqlmodel.tiangolo.com/) support and more.
+
+It streamlines the configuration and asynchronous connection to relational databases by
+providing boilerplate and intuitive helpers. Additionally, it offers built-in
+customizable pagination and automatically manages the `SQLAlchemy` session lifecycle
+following [`SQLAlchemy`'s best practices](https://docs.sqlalchemy.org/en/20/orm/session_basics.html#when-do-i-construct-a-session-when-do-i-commit-it-and-when-do-i-close-it).
+
+
+## Features
+
+* Easy setup at app startup using
+  [`FastAPI` Lifespan](https://fastapi.tiangolo.com/advanced/events/#lifespan):
+
+    ```python
+    from fastapi import FastAPI
+    from fastsqla import lifespan
+
+    app = FastAPI(lifespan=lifespan)
+    ```
+
+* `SQLAlchemy` async session dependency:
+
+    ```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)
+        ...
+    ```
+
+* `SQLAlchemy` async session with an async context manager:
+
+    ```python
+    from fastsqla import open_session
+
+    async def background_job():
+        async with open_session() as session:
+            stmt = select(...)
+            result = await session.execute(stmt)
+            ...
+    ```
+
+* Built-in pagination:
+
+    ```python
+    ...
+    from fastsqla import Page, Paginate
+    from sqlalchemy import select
+    ...
+
+    @app.get("/heros", response_model=Page[HeroModel])
+    async def get_heros(paginate:Paginate):
+        return await paginate(select(Hero))
+    ```
+
+    <center>
+
+    👇 `/heros?offset=10&limit=10` 👇
+
+    </center>
+
+    ```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
+      }
+    }
+    ```
+
+* Pagination customization:
+    ```python
+    ...
+    from fastapi import Page, 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))
+    ```
+* Session lifecycle management: session is commited on request success or rollback on
+  failure.
+
+* [`SQLModel`](http://sqlmodel.tiangolo.com/) support:
+    ```python
+    ...
+    from fastsqla import Item, Page, Paginate, Session
+    from sqlmodel import Field, SQLModel
+    ...
+
+    class Hero(SQLModel, table=True):
+        id: int | None = Field(default=None, primary_key=True)
+        name: str
+        secret_identity: str
+        age: int
+
+
+    @app.get("/heroes", response_model=Page[Hero])
+    async def get_heroes(paginate: Paginate):
+        return await paginate(select(Hero))
+
+
+    @app.get("/heroes/{hero_id}", response_model=Item[Hero])
+    async def get_hero(session: Session, hero_id: int):
+        hero = await session.get(Hero, hero_id)
+        if hero is None:
+            raise HTTPException(status_code=HTTPStatus.NOT_FOUND)
+        return {"data": hero}
+    ```
+
+## Installing
+
+Using [uv](https://docs.astral.sh/uv/):
+```bash
+uv add fastsqla
+```
+
+Using [pip](https://pip.pypa.io/):
+```
+pip install fastsqla
+```
+
+## Quick Example
+
+### `example.py`
+
+Let's write some tiny app in `example.py`:
+
+```python
+# example.py
+from http import HTTPStatus
+
+from fastapi import FastAPI, HTTPException
+from fastsqla import Base, Item, Page, Paginate, Session, lifespan
+from pydantic import BaseModel, ConfigDict
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+from sqlalchemy.orm import Mapped, mapped_column
+
+
+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]
+    age: Mapped[int]
+
+
+class HeroBase(BaseModel):
+    name: str
+    secret_identity: str
+    age: int
+
+
+class HeroModel(HeroBase):
+    model_config = ConfigDict(from_attributes=True)
+    id: int
+
+
+@app.get("/heros", response_model=Page[HeroModel])
+async def list_heros(paginate: Paginate):
+    stmt = select(Hero)
+    return await paginate(stmt)
+
+
+@app.get("/heros/{hero_id}", response_model=Item[HeroModel])
+async def get_hero(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_hero(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}
+```
+
+### Database
+
+💡 This example uses an `SQLite` database for simplicity: `FastSQLA` is compatible with
+all asynchronous db drivers that `SQLAlchemy` is compatible with.
+
+Let's create an `SQLite` database using `sqlite3` and insert 12 rows in the `hero` table:
+
+```bash
+sqlite3 db.sqlite <<EOF
+-- Create Table hero
+CREATE TABLE hero (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    name            TEXT NOT NULL UNIQUE, -- Unique hero name (e.g., Superman)
+    secret_identity TEXT NOT NULL,        -- Secret identity (e.g., Clark Kent)
+    age             INTEGER NOT NULL      -- Age of the hero (e.g., 30)
+);
+
+-- Insert heroes with their name, secret identity, and age
+INSERT INTO hero (name, secret_identity, age) VALUES ('Superman',        'Clark Kent',       30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Batman',          'Bruce Wayne',      35);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Wonder Woman',    'Diana Prince',     30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Iron Man',        'Tony Stark',       45);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Spider-Man',      'Peter Parker',     25);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Captain America', 'Steve Rogers',     100);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Black Widow',     'Natasha Romanoff', 35);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Thor',            'Thor Odinson',     1500);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Scarlet Witch',   'Wanda Maximoff',   30);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Doctor Strange',  'Stephen Strange',  40);
+INSERT INTO hero (name, secret_identity, age) VALUES ('The Flash',       'Barry Allen',      28);
+INSERT INTO hero (name, secret_identity, age) VALUES ('Green Lantern',   'Hal Jordan',       35);
+EOF
+```
+
+### Run the app
+
+Let's install required dependencies:
+```bash
+pip install uvicorn aiosqlite fastsqla
+```
+Let's run the app:
+```
+sqlalchemy_url=sqlite+aiosqlite:///db.sqlite?check_same_thread=false \
+  uvicorn example:app
+```
+
+### Check the result
+
+Execute `GET /heros?offset=10&limit=10` using `curl`:
+```bash
+curl -X 'GET' -H 'accept: application/json' 'http://127.0.0.1:8000/heros?offset=10&limit=10'
+```
+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
+  }
+}
+```
+
+You can also check the generated openapi doc by opening your browser to
+[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs).
+
+![OpenAPI generated documentation of the example API](https://raw.githubusercontent.com/hadrien/FastSQLA/refs/heads/main/docs/images/example-openapi-generated-doc.png)
+
+## License
+
+This project is licensed under the terms of the [MIT license](https://github.com/hadrien/FastSQLA/blob/main/LICENSE).

fastsqla-0.4.4.dist-info/RECORD

@@ -0,0 +1,5 @@
+fastsqla.py,sha256=wO4KpgkA3jVOCtpbwORlaUuOu4YsEQoRslzg9wjDNBk,12364
+fastsqla-0.4.4.dist-info/METADATA,sha256=lyIlPmzzZ99nG1uKAmrpi1lH7Zpclod8LUTmNj0OOuo,12425
+fastsqla-0.4.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+fastsqla-0.4.4.dist-info/top_level.txt,sha256=Uh-1ssTtuSS4_SYCBeDoDVOxqWTrRAPEBZkuih5isSE,9
+fastsqla-0.4.4.dist-info/RECORD,,

{FastSQLA-0.2.4.dist-info → fastsqla-0.4.4.dist-info}/WHEEL

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

fastsqla.py

@@ -1,10 +1,10 @@
 import math
 import os
 from collections.abc import AsyncGenerator, Awaitable, Callable, Iterable
-from contextlib import asynccontextmanager
+from contextlib import _AsyncGeneratorContextManager, asynccontextmanager
 from typing import Annotated, Generic, TypeVar, TypedDict
 
-from fastapi import Depends, Query
+from fastapi import Depends, FastAPI, Query
 from pydantic import BaseModel, Field
 from sqlalchemy import Result, Select, func, select
 from sqlalchemy.ext.asyncio import (
@@ -17,6 +17,15 @@ from sqlalchemy.ext.declarative import DeferredReflection
 from sqlalchemy.orm import DeclarativeBase
 from structlog import get_logger
 
+logger = get_logger(__name__)
+
+try:
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
+except ImportError:
+    pass
+
+
 __all__ = [
     "Base",
     "Collection",
@@ -30,12 +39,38 @@ __all__ = [
     "open_session",
 ]
 
-SessionFactory = async_sessionmaker(expire_on_commit=False)
+SessionFactory = async_sessionmaker(expire_on_commit=False, class_=AsyncSession)
 
 logger = get_logger(__name__)
 
 
 class Base(DeclarativeBase, DeferredReflection):
+    """Inherit from `Base` to declare an `SQLAlchemy` model.
+
+    Example:
+    ```py
+    from fastsqla import Base
+    from sqlalchemy.orm import Mapped, mapped_column
+
+
+    class Hero(Base):
+        __tablename__ = "hero"
+        id: Mapped[int] = mapped_column(primary_key=True)
+        name: Mapped[str] = mapped_column(unique=True)
+        secret_identity: Mapped[str]
+        age: Mapped[int]
+    ```
+
+    To learn more on `SQLAlchemy` ORM & Declarative mapping:
+
+    * [ORM Quick Start](https://docs.sqlalchemy.org/en/20/orm/quickstart.html)
+    * [Declarative Mapping](https://docs.sqlalchemy.org/en/20/orm/mapping_styles.html#declarative-mapping)
+
+    !!! note
+
+        You don't need this if you use [`SQLModel`](http://sqlmodel.tiangolo.com/).
+    """
+
     __abstract__ = True
 
 
@@ -43,33 +78,151 @@ 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)
+def new_lifespan(
+    url: str | None = None, **kw
+) -> Callable[[FastAPI], _AsyncGeneratorContextManager[State, None]]:
+    """Create a new lifespan async context manager.
+
+    It expects the exact same parameters as
+    [`sqlalchemy.ext.asyncio.create_async_engine`][sqlalchemy.ext.asyncio.create_async_engine]
+
+    Example:
+
+    ```python
+    from fastapi import FastAPI
+    from fastsqla import new_lifespan
 
-    except KeyError as exc:
-        raise Exception(f"Missing {prefix}{exc.args[0]} in environ.") from exc
+    lifespan = new_lifespan(
+        "sqlite+aiosqlite:///app/db.sqlite", connect_args={"autocommit": False}
+    )
+
+    app = FastAPI(lifespan=lifespan)
+    ```
+
+    Args:
+        url (str): Database url.
+        kw (dict): Configuration parameters as expected by [`sqlalchemy.ext.asyncio.create_async_engine`][sqlalchemy.ext.asyncio.create_async_engine]
+    """
+
+    has_config = url is not None
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI) -> AsyncGenerator[State, None]:
+        if has_config:
+            prefix = ""
+            sqla_config = {**kw, **{"url": url}}
+
+        else:
+            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)
 
-    async with engine.begin() as conn:
-        await conn.run_sync(Base.prepare)
+        SessionFactory.configure(bind=engine)
 
-    SessionFactory.configure(bind=engine)
+        await logger.ainfo("Configured SQLAlchemy.")
 
-    await logger.ainfo("Configured SQLAlchemy.")
+        yield {"fastsqla_engine": engine}
 
-    yield {"fastsqla_engine": engine}
+        SessionFactory.configure(bind=None)
+        await engine.dispose()
 
-    SessionFactory.configure(bind=None)
-    await engine.dispose()
+        await logger.ainfo("Cleared SQLAlchemy config.")
 
-    await logger.ainfo("Cleared SQLAlchemy config.")
+    return lifespan
+
+
+lifespan = new_lifespan()
+"""Use `fastsqla.lifespan` to set up SQLAlchemy directly from environment variables.
+
+In an ASGI application, [lifespan events](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+are used to communicate startup & shutdown events.
+
+The [`lifespan`](https://fastapi.tiangolo.com/advanced/events/#lifespan) parameter of
+the `FastAPI` app can be assigned to a context manager, which is opened when the app
+starts and closed when the app stops.
+
+In order for `FastSQLA` to setup `SQLAlchemy` before the app is started, set
+`lifespan` parameter to `fastsqla.lifespan`:
+
+```python
+from fastapi import FastAPI
+from fastsqla import lifespan
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+If multiple lifespan contexts are required, create an async context manager function
+to handle them and set it as the app's lifespan:
+
+```python
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastsqla import lifespan as fastsqla_lifespan
+from this_other_library import another_lifespan
+
+
+@asynccontextmanager
+async def lifespan(app:FastAPI) -> AsyncGenerator[dict, None]:
+    async with AsyncExitStack() as stack:
+        yield {
+            **stack.enter_async_context(lifespan(app)),
+            **stack.enter_async_context(another_lifespan(app)),
+        }
+
+
+app = FastAPI(lifespan=lifespan)
+```
+
+To learn more about lifespan protocol:
+
+* [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html)
+* [Use Lifespan State instead of `app.state`](https://github.com/Kludex/fastapi-tips?tab=readme-ov-file#6-use-lifespan-state-instead-of-appstate)
+* [FastAPI lifespan documentation](https://fastapi.tiangolo.com/advanced/events/)
+"""
 
 
 @asynccontextmanager
 async def open_session() -> AsyncGenerator[AsyncSession, None]:
+    """Async context manager that opens a new `SQLAlchemy` or `SQLModel` async session.
+
+    To the contrary of the [`Session`][fastsqla.Session] dependency which can only be
+    used in endpoints, `open_session` can be used anywhere such as in background tasks.
+
+    On exit, it automatically commits the session if no errors occur inside the context,
+    or rolls back when an exception is raised.
+    In all cases, it closes the session and returns the associated connection to the
+    connection pool.
+
+
+    Returns:
+        When `SQLModel` is not installed, an async generator that yields an
+            [`SQLAlchemy AsyncSession`][sqlalchemy.ext.asyncio.AsyncSession].
+
+        When `SQLModel` is installed, an async generator that yields an
+            [`SQLModel AsyncSession`](https://github.com/fastapi/sqlmodel/blob/main/sqlmodel/ext/asyncio/session.py#L32)
+            which inherits from [`SQLAlchemy AsyncSession`][sqlalchemy.ext.asyncio.AsyncSession].
+
+
+    ```python
+    from fastsqla import open_session
+
+    async def example():
+        async with open_session() as session:
+            await session.execute(...)
+    ```
+
+    """
     session = SessionFactory()
     try:
         yield session
@@ -100,6 +253,61 @@ async def new_session() -> AsyncGenerator[AsyncSession, None]:
 
 
 Session = Annotated[AsyncSession, Depends(new_session)]
+"""Dependency used exclusively in endpoints to get an `SQLAlchemy` or `SQLModel` session.
+
+`Session` is a [`FastAPI` dependency](https://fastapi.tiangolo.com/tutorial/dependencies/)
+that provides an asynchronous `SQLAlchemy` session or `SQLModel` one if it's installed.
+By defining an argument with type `Session` in an endpoint, `FastAPI` will automatically
+inject an async session into the endpoint.
+
+At the end of request handling:
+
+* If no exceptions are raised, the session is automatically committed.
+* If an exception is raised, the session is automatically rolled back.
+* In all cases, the session is closed and the associated connection is returned to the
+  connection pool.
+
+Example:
+
+``` py title="example.py" hl_lines="6"
+from fastsqla import Item, Session
+...
+
+@app.get("/heros/{hero_id}", response_model=Item[HeroItem])
+async def get_items(
+    session: Session, # (1)!
+    item_id: int,
+):
+    hero = await session.get(Hero, hero_id)
+    return {"data": hero}
+```
+
+1.  Just define an argument with type `Session` to get an async session injected
+    in your endpoint.
+
+---
+
+**Recommendation**: Unless there is a good reason to do so, avoid committing the session
+manually, as `FastSQLA` handles it automatically.
+
+If you need data generated by the database server, such as auto-incremented IDs, flush
+the session instead:
+
+```python
+from fastsqla import Item, Session
+...
+
+
+@app.post("/heros", response_model=Item[HeroItem])
+async def create_item(session: Session, new_hero: HeroBase):
+    hero = Hero(**new_hero.model_dump())
+    session.add(hero)
+    await session.flush()
+    return {"data": hero}
+```
+
+Or use the [session context manager][fastsqla.open_session] instead.
+"""
 
 
 class Meta(BaseModel):
@@ -121,6 +329,23 @@ class Collection(BaseModel, Generic[T]):
 
 
 class Page(Collection[T]):
+    """Generic container that contains collection data and page metadata.
+
+    The `Page` model is used to return paginated data in paginated endpoints:
+
+    ```json
+    {
+        "data": list[T],
+        "meta": {
+            "offset": int,
+            "total_items": int,
+            "total_pages": int,
+            "page_number": int,
+        }
+    }
+    ```
+    """
+
     meta: Meta
 
 
@@ -193,4 +418,10 @@ def new_pagination(
 
 
 type PaginateType[T] = Callable[[Select], Awaitable[Page[T]]]
+
 Paginate = Annotated[PaginateType[T], Depends(new_pagination())]
+"""A dependency used in endpoints to paginate `SQLAlchemy` select queries.
+
+It adds **`offset`** and **`limit`** query parameters to the endpoint, which are used to
+paginate. The model returned by the endpoint is a [`Page`][fastsqla.Page] model.
+"""

FastSQLA-0.2.4.dist-info/LICENSE

@@ -1,21 +0,0 @@
-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

@@ -1,261 +0,0 @@
-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

@@ -1,6 +0,0 @@
-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,,