fastapi-sqla 2.10.1__tar.gz → 3.0.0__tar.gz

{fastapi_sqla-2.10.1 → fastapi_sqla-3.0.0}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: fastapi-sqla
-Version: 2.10.1
+Version: 3.0.0
 Summary: SQLAlchemy extension for FastAPI with support for pagination, asyncio, and pytest, ready for production.
 Home-page: https://github.com/dialoguemd/fastapi-sqla
 License: MIT
 Keywords: FastAPI,SQLAlchemy,asyncio,pytest,alembic
 Author: Hadrien David
 Author-email: hadrien.david@dialogue.co
-Requires-Python: >=3.7,<4.0
+Requires-Python: >=3.9,<4.0
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Web Environment
 Classifier: Framework :: AsyncIO
@@ -19,8 +19,6 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.7
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -43,7 +41,7 @@ Requires-Dist: asgi_lifespan (>=1.0.1,<2.0.0) ; extra == "tests"
 Requires-Dist: asyncpg (>=0.28.0,<0.29.0) ; extra == "asyncpg"
 Requires-Dist: black (>=22.8.0,<23.0.0) ; extra == "tests"
 Requires-Dist: boto3 (>=1.24.74,<2.0.0) ; extra == "aws-rds-iam"
-Requires-Dist: fastapi (>=0.61)
+Requires-Dist: fastapi (>=0.95.1)
 Requires-Dist: greenlet (>=1.1.3,<2.0.0) ; extra == "tests"
 Requires-Dist: httpx (>=0.23.0,<0.24.0) ; extra == "tests"
 Requires-Dist: isort (>=5.5.3,<6.0.0) ; extra == "tests"
@@ -90,7 +88,7 @@ unique `email`:
 
 ```python
 # main.py
-from fastapi import Depends, FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException
 from fastapi_sqla import Base, Item, Page, Paginate, Session, setup
 from pydantic import BaseModel, EmailStr
 from sqlalchemy import select
@@ -118,12 +116,12 @@ class UserModel(UserIn):
 
 
 @app.get("/users", response_model=Page[UserModel])
-def list_users(paginate: Paginate = Depends()):
+def list_users(paginate: Paginate):
     return paginate(select(User))
 
 
 @app.get("/users/{user_id}", response_model=Item[UserModel])
-def get_user(user_id: int, session: Session = Depends()):
+def get_user(user_id: int, session: Session):
     user = session.get(User, user_id)
     if user is None:
         raise HTTPException(404)
@@ -131,7 +129,7 @@ def get_user(user_id: int, session: Session = Depends()):
 
 
 @app.post("/users", response_model=Item[UserModel])
-def create_user(new_user: UserIn, session: Session = Depends()):
+def create_user(new_user: UserIn, session: Session):
     user = User(**new_user.model_dump())
     session.add(user)
     try:
@@ -173,6 +171,21 @@ The only required key is `sqlalchemy_url`, which provides the database URL, exam
 export sqlalchemy_url=postgresql://postgres@localhost
 ```
 
+### Multi-session support
+
+In order to configure multiple sessions for the application, 
+set the environment variables with this prefix format: `fastapi_sqla__MY_KEY__`.
+
+As with the default session, each matching key (after the prefix is stripped) 
+is treated as though it were the corresponding keyword argument to [`sqlalchemy.create_engine`]
+call.
+
+For example, to configure a session with the `read_only` key:
+
+```bash
+export fastapi_sqla__read_only__sqlalchemy_url=postgresql://postgres@localhost
+```
+
 ### `asyncio` support using [`asyncpg`]
 
 SQLAlchemy `>= 1.4` supports `asyncio`.
@@ -182,7 +195,7 @@ To enable `asyncio` support against a Postgres DB, install `asyncpg`:
 pip install asyncpg
 ```
 
-And define environment variable `sqlalchemy_url` with `postgres+asyncpg` scheme:
+And define the environment variable `sqlalchemy_url` with `postgres+asyncpg` scheme:
 
 ```bash
 export sqlalchemy_url=postgresql+asyncpg://postgres@localhost
@@ -216,23 +229,71 @@ class Entity(Base):
 
 Use [FastAPI dependency injection] to get a session as a parameter of a path operation
 function.
-SQLAlchemy session is committed before response is returned or rollbacked if any
+
+The SQLAlchemy session is committed before the response is returned or rollbacked if any
 exception occurred:
 
 ```python
+from fastapi import APIRouter
+from fastapi_sqla import AsyncSession, Session
+
+router = APIRouter()
+
+
+@router.get("/example")
+def example(session: Session):
+    return session.execute("SELECT now()").scalar()
+
+
+@router.get("/async_example")
+async def async_example(session: AsyncSession):
+    return await session.scalar("SELECT now()")
+```
+
+In order to get a session configured with a custom key:
+
+```python
+from typing import Annotated
+
 from fastapi import APIRouter, Depends
-from fastapi_sqla import Session, AsyncSession
+from fastapi_sqla import (
+    AsyncSessionDependency,
+    SessionDependency,
+    SqlaAsyncSession,
+    SqlaSession,
+)
 
 router = APIRouter()
 
 
+# Preferred
+
+ReadOnlySession = Annotated[SqlaSession, Depends(SessionDependency(key="read_only"))]
+AsyncReadOnlySession = Annotated[
+    SqlaAsyncSession, Depends(AsyncSessionDependency(key="read_only"))
+]
+
 @router.get("/example")
-def example(session: Session = Depends()):
+def example(session: ReadOnlySession):
     return session.execute("SELECT now()").scalar()
 
 
 @router.get("/async_example")
-async def async_example(session: AsyncSession = Depends()):
+async def async_example(session: AsyncReadOnlySession):
+    return await session.scalar("SELECT now()")
+
+
+# Alternative
+
+@router.get("/example/alt")
+def example_alt(session: SqlaSession = Depends(SessionDependency(key="read_only"))):
+    return session.execute("SELECT now()").scalar()
+
+
+@router.get("/async_example/alt")
+async def async_example_alt(
+    session: SqlaAsyncSession = Depends(AsyncSessionDependency(key="read_only")),
+):
     return await session.scalar("SELECT now()")
 ```
 
@@ -240,12 +301,12 @@ async def async_example(session: AsyncSession = Depends()):
 
 When needing a session outside of a path operation, like when using
 [FastAPI background tasks], use `fastapi_sqla.open_session` context manager.
-SQLAlchemy session is committed when exiting context or rollbacked if any exception
+The SQLAlchemy session is committed when exiting context or rollbacked if any exception
 occurred:
 
 ```python
 from fastapi import APIRouter, BackgroundTasks
-from fastapi_sqla import open_session, open_async_session
+from fastapi_sqla import open_async_session, open_session
 
 router = APIRouter()
 
@@ -260,16 +321,23 @@ def run_bg():
     with open_session() as session:
         session.execute("SELECT now()").scalar()
 
+def run_bg_with_key():
+    with open_session(key="read_only") as session:
+        session.execute("SELECT now()").scalar()
 
 async def run_async_bg():
     async with open_async_session() as session:
         await session.scalar("SELECT now()")
+
+async def run_async_bg_with_key():
+    async with open_async_session(key="read_only") as session:
+        await session.scalar("SELECT now()")
 ```
 
 ## Pagination
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, Paginate
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -290,7 +358,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: Paginate):
     return paginate(select(User))
 ```
 
@@ -327,7 +395,7 @@ To paginate a query which doesn't return [scalars], specify `scalars=False` when
 `paginate`:
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, Paginate
 from pydantic import BaseModel
 from sqlalchemy import func, select
@@ -352,7 +420,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: Paginate):
     query = (
         select(User.id, User.name, func.count(Note.id).label("notes_count"))
         .join(Note)
@@ -388,15 +456,15 @@ class UserModel(BaseModel):
     name: str
 
 
-def query_count(session: Session = Depends()) -> int:
+def query_count(session: Session) -> int:
     return session.execute(select(func.count()).select_from(User)).scalar()
 
 
-Paginate = Pagination(min_page_size=5, max_page_size=500, query_count=query_count)
+CustomPaginate = Pagination(min_page_size=5, max_page_size=500, query_count=query_count)
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: CustomPaginate = Depends()):
     return paginate(select(User))
 ```
 
@@ -405,7 +473,7 @@ def all_users(paginate: Paginate = Depends()):
 When using the asyncio support, use the `AsyncPaginate` dependency:
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, AsyncPaginate
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -426,7 +494,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-async def all_users(paginate: AsyncPaginate = Depends()):
+async def all_users(paginate: AsyncPaginate):
     return await paginate(select(User))
 ```
 
@@ -450,16 +518,85 @@ class UserModel(BaseModel):
     name: str
 
 
-async def query_count(session: AsyncSession = Depends()) -> int:
+async def query_count(session: AsyncSession) -> int:
     result = await session.execute(select(func.count()).select_from(User))
     return result.scalar()
 
 
-Paginate = AsyncPagination(min_page_size=5, max_page_size=500, query_count=query_count)
+CustomPaginate = AsyncPagination(min_page_size=5, max_page_size=500, query_count=query_count)
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: CustomPaginate = Depends()):
+async def all_users(paginate: CustomPaginate = Depends()):
+    return await paginate(select(User))
+```
+
+### Multi-session support
+
+Pagination supports multiple sessions as well. To paginate using a session 
+configured with a custom key:
+
+```python
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from fastapi_sqla import (
+    AsyncPaginateSignature,
+    AsyncPagination,
+    Base,
+    Page,
+    PaginateSignature,
+    Pagination,
+)
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+router = APIRouter()
+
+
+class User(Base):
+    __tablename__ = "user"
+
+
+class UserModel(BaseModel):
+    id: int
+    name: str
+
+
+# Preferred
+
+ReadOnlyPaginate = Annotated[
+    PaginateSignature, Depends(Pagination(session_key="read_only"))
+]
+AsyncReadOnlyPaginate = Annotated[
+    AsyncPaginateSignature, Depends(AsyncPagination(session_key="read_only"))
+]
+
+@router.get("/users", response_model=Page[UserModel])
+def all_users(paginate: ReadOnlyPaginate):
+    return paginate(select(User))
+
+@router.get("/async_users", response_model=Page[UserModel])
+async def async_all_users(paginate: AsyncReadOnlyPaginate):
+    return await paginate(select(User))
+
+
+# Alternative
+
+@router.get("/users/alt", response_model=Page[UserModel])
+def all_users_alt(
+    paginate: PaginateSignature = Depends(
+        Pagination(session_key="read_only")
+    ),
+):
+    return paginate(select(User))
+
+@router.get("/async_users/alt", response_model=Page[UserModel])
+async def async_all_users_alt(
+    paginate: AsyncPaginateSignature = Depends(
+        AsyncPagination(session_key="read_only")
+    ),
+):
     return await paginate(select(User))
 ```
 

{fastapi_sqla-2.10.1 → fastapi_sqla-3.0.0}/README.md

@@ -27,7 +27,7 @@ unique `email`:
 
 ```python
 # main.py
-from fastapi import Depends, FastAPI, HTTPException
+from fastapi import FastAPI, HTTPException
 from fastapi_sqla import Base, Item, Page, Paginate, Session, setup
 from pydantic import BaseModel, EmailStr
 from sqlalchemy import select
@@ -55,12 +55,12 @@ class UserModel(UserIn):
 
 
 @app.get("/users", response_model=Page[UserModel])
-def list_users(paginate: Paginate = Depends()):
+def list_users(paginate: Paginate):
     return paginate(select(User))
 
 
 @app.get("/users/{user_id}", response_model=Item[UserModel])
-def get_user(user_id: int, session: Session = Depends()):
+def get_user(user_id: int, session: Session):
     user = session.get(User, user_id)
     if user is None:
         raise HTTPException(404)
@@ -68,7 +68,7 @@ def get_user(user_id: int, session: Session = Depends()):
 
 
 @app.post("/users", response_model=Item[UserModel])
-def create_user(new_user: UserIn, session: Session = Depends()):
+def create_user(new_user: UserIn, session: Session):
     user = User(**new_user.model_dump())
     session.add(user)
     try:
@@ -110,6 +110,21 @@ The only required key is `sqlalchemy_url`, which provides the database URL, exam
 export sqlalchemy_url=postgresql://postgres@localhost
 ```
 
+### Multi-session support
+
+In order to configure multiple sessions for the application, 
+set the environment variables with this prefix format: `fastapi_sqla__MY_KEY__`.
+
+As with the default session, each matching key (after the prefix is stripped) 
+is treated as though it were the corresponding keyword argument to [`sqlalchemy.create_engine`]
+call.
+
+For example, to configure a session with the `read_only` key:
+
+```bash
+export fastapi_sqla__read_only__sqlalchemy_url=postgresql://postgres@localhost
+```
+
 ### `asyncio` support using [`asyncpg`]
 
 SQLAlchemy `>= 1.4` supports `asyncio`.
@@ -119,7 +134,7 @@ To enable `asyncio` support against a Postgres DB, install `asyncpg`:
 pip install asyncpg
 ```
 
-And define environment variable `sqlalchemy_url` with `postgres+asyncpg` scheme:
+And define the environment variable `sqlalchemy_url` with `postgres+asyncpg` scheme:
 
 ```bash
 export sqlalchemy_url=postgresql+asyncpg://postgres@localhost
@@ -153,23 +168,71 @@ class Entity(Base):
 
 Use [FastAPI dependency injection] to get a session as a parameter of a path operation
 function.
-SQLAlchemy session is committed before response is returned or rollbacked if any
+
+The SQLAlchemy session is committed before the response is returned or rollbacked if any
 exception occurred:
 
 ```python
+from fastapi import APIRouter
+from fastapi_sqla import AsyncSession, Session
+
+router = APIRouter()
+
+
+@router.get("/example")
+def example(session: Session):
+    return session.execute("SELECT now()").scalar()
+
+
+@router.get("/async_example")
+async def async_example(session: AsyncSession):
+    return await session.scalar("SELECT now()")
+```
+
+In order to get a session configured with a custom key:
+
+```python
+from typing import Annotated
+
 from fastapi import APIRouter, Depends
-from fastapi_sqla import Session, AsyncSession
+from fastapi_sqla import (
+    AsyncSessionDependency,
+    SessionDependency,
+    SqlaAsyncSession,
+    SqlaSession,
+)
 
 router = APIRouter()
 
 
+# Preferred
+
+ReadOnlySession = Annotated[SqlaSession, Depends(SessionDependency(key="read_only"))]
+AsyncReadOnlySession = Annotated[
+    SqlaAsyncSession, Depends(AsyncSessionDependency(key="read_only"))
+]
+
 @router.get("/example")
-def example(session: Session = Depends()):
+def example(session: ReadOnlySession):
     return session.execute("SELECT now()").scalar()
 
 
 @router.get("/async_example")
-async def async_example(session: AsyncSession = Depends()):
+async def async_example(session: AsyncReadOnlySession):
+    return await session.scalar("SELECT now()")
+
+
+# Alternative
+
+@router.get("/example/alt")
+def example_alt(session: SqlaSession = Depends(SessionDependency(key="read_only"))):
+    return session.execute("SELECT now()").scalar()
+
+
+@router.get("/async_example/alt")
+async def async_example_alt(
+    session: SqlaAsyncSession = Depends(AsyncSessionDependency(key="read_only")),
+):
     return await session.scalar("SELECT now()")
 ```
 
@@ -177,12 +240,12 @@ async def async_example(session: AsyncSession = Depends()):
 
 When needing a session outside of a path operation, like when using
 [FastAPI background tasks], use `fastapi_sqla.open_session` context manager.
-SQLAlchemy session is committed when exiting context or rollbacked if any exception
+The SQLAlchemy session is committed when exiting context or rollbacked if any exception
 occurred:
 
 ```python
 from fastapi import APIRouter, BackgroundTasks
-from fastapi_sqla import open_session, open_async_session
+from fastapi_sqla import open_async_session, open_session
 
 router = APIRouter()
 
@@ -197,16 +260,23 @@ def run_bg():
     with open_session() as session:
         session.execute("SELECT now()").scalar()
 
+def run_bg_with_key():
+    with open_session(key="read_only") as session:
+        session.execute("SELECT now()").scalar()
 
 async def run_async_bg():
     async with open_async_session() as session:
         await session.scalar("SELECT now()")
+
+async def run_async_bg_with_key():
+    async with open_async_session(key="read_only") as session:
+        await session.scalar("SELECT now()")
 ```
 
 ## Pagination
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, Paginate
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -227,7 +297,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: Paginate):
     return paginate(select(User))
 ```
 
@@ -264,7 +334,7 @@ To paginate a query which doesn't return [scalars], specify `scalars=False` when
 `paginate`:
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, Paginate
 from pydantic import BaseModel
 from sqlalchemy import func, select
@@ -289,7 +359,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: Paginate):
     query = (
         select(User.id, User.name, func.count(Note.id).label("notes_count"))
         .join(Note)
@@ -325,15 +395,15 @@ class UserModel(BaseModel):
     name: str
 
 
-def query_count(session: Session = Depends()) -> int:
+def query_count(session: Session) -> int:
     return session.execute(select(func.count()).select_from(User)).scalar()
 
 
-Paginate = Pagination(min_page_size=5, max_page_size=500, query_count=query_count)
+CustomPaginate = Pagination(min_page_size=5, max_page_size=500, query_count=query_count)
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: Paginate = Depends()):
+def all_users(paginate: CustomPaginate = Depends()):
     return paginate(select(User))
 ```
 
@@ -342,7 +412,7 @@ def all_users(paginate: Paginate = Depends()):
 When using the asyncio support, use the `AsyncPaginate` dependency:
 
 ```python
-from fastapi import APIRouter, Depends
+from fastapi import APIRouter
 from fastapi_sqla import Base, Page, AsyncPaginate
 from pydantic import BaseModel
 from sqlalchemy import select
@@ -363,7 +433,7 @@ class UserModel(BaseModel):
 
 
 @router.get("/users", response_model=Page[UserModel])
-async def all_users(paginate: AsyncPaginate = Depends()):
+async def all_users(paginate: AsyncPaginate):
     return await paginate(select(User))
 ```
 
@@ -387,16 +457,85 @@ class UserModel(BaseModel):
     name: str
 
 
-async def query_count(session: AsyncSession = Depends()) -> int:
+async def query_count(session: AsyncSession) -> int:
     result = await session.execute(select(func.count()).select_from(User))
     return result.scalar()
 
 
-Paginate = AsyncPagination(min_page_size=5, max_page_size=500, query_count=query_count)
+CustomPaginate = AsyncPagination(min_page_size=5, max_page_size=500, query_count=query_count)
 
 
 @router.get("/users", response_model=Page[UserModel])
-def all_users(paginate: CustomPaginate = Depends()):
+async def all_users(paginate: CustomPaginate = Depends()):
+    return await paginate(select(User))
+```
+
+### Multi-session support
+
+Pagination supports multiple sessions as well. To paginate using a session 
+configured with a custom key:
+
+```python
+from typing import Annotated
+
+from fastapi import APIRouter, Depends
+from fastapi_sqla import (
+    AsyncPaginateSignature,
+    AsyncPagination,
+    Base,
+    Page,
+    PaginateSignature,
+    Pagination,
+)
+from pydantic import BaseModel
+from sqlalchemy import func, select
+
+router = APIRouter()
+
+
+class User(Base):
+    __tablename__ = "user"
+
+
+class UserModel(BaseModel):
+    id: int
+    name: str
+
+
+# Preferred
+
+ReadOnlyPaginate = Annotated[
+    PaginateSignature, Depends(Pagination(session_key="read_only"))
+]
+AsyncReadOnlyPaginate = Annotated[
+    AsyncPaginateSignature, Depends(AsyncPagination(session_key="read_only"))
+]
+
+@router.get("/users", response_model=Page[UserModel])
+def all_users(paginate: ReadOnlyPaginate):
+    return paginate(select(User))
+
+@router.get("/async_users", response_model=Page[UserModel])
+async def async_all_users(paginate: AsyncReadOnlyPaginate):
+    return await paginate(select(User))
+
+
+# Alternative
+
+@router.get("/users/alt", response_model=Page[UserModel])
+def all_users_alt(
+    paginate: PaginateSignature = Depends(
+        Pagination(session_key="read_only")
+    ),
+):
+    return paginate(select(User))
+
+@router.get("/async_users/alt", response_model=Page[UserModel])
+async def async_all_users_alt(
+    paginate: AsyncPaginateSignature = Depends(
+        AsyncPagination(session_key="read_only")
+    ),
+):
     return await paginate(select(User))
 ```