refactor!: Simplify pagination API

BREAKING CHANGE: * Renamed `Paginated` to `Page`, `PaginatedResult` to `Paginate`;
                 * Removed `with_pagination`;

Author: hadrien

README.md

@@ -65,13 +65,7 @@ def example(session: Session = Depends()):
 
 ```python
 from fastapi import APIRouter, Depends
-from fastapi_sqla import (
-    Base,
-    Paginated,
-    PaginatedResult,
-    Session,
-    with_pagination,
-)
+from fastapi_sqla import Base, Page, Paginate, Session
 from pydantic import BaseModel
 
 router = APIRouter()
@@ -86,13 +80,10 @@ class User(BaseModel):
     name: str
 
 
-@router.get("/users", response_model=Paginated[User])
-def all_users(
-    session: Session = Depends(),
-    paginated_result: PaginatedResult = Depends(with_pagination),
-):
+@router.get("/users", response_model=Page[User])
+def all_users(session: Session = Depends(), paginate: Paginate = Depends()):
     query = session.query(UserEntity)
-    return paginated_result(query)
+    return paginate(query)
 ```
 
 By default:
@@ -109,13 +100,7 @@ To customize pagination, create a dependency using `fastapi_sqla.Pagination`
 
 ```python
 from fastapi import APIRouter, Depends
-from fastapi_sqla import (
-    Base,
-    Paginated,
-    PaginatedResult,
-    Pagination,
-    Session,
-)
+from fastapi_sqla import Base, Page, Pagination, Session
 from pydantic import BaseModel
 from sqlalchemy import func
 from sqlalchemy.orm import Query
@@ -136,20 +121,20 @@ def query_count(session: Session, query: Query):
     return query.statement.with_only_columns([func.count()]).scalar()
 
 
-with_custom_pagination = Pagination(
+Paginate = Pagination(
     min_page_size=5,
     max_page_size=500,
     query_count=query_count,
 )
 
 
-@router.get("/users", response_model=Paginated[User])
+@router.get("/users", response_model=Page[User])
 def all_users(
     session: Session = Depends(),
-    paginated_result: PaginatedResult = Depends(with_custom_pagination),
+    paginate: Paginate = Depends(),
 ):
     query = session.query(UserEntity)
-    return paginated_result(query)
+    return paginate(query)
 ```
 
 ## Pytest fixtures

fastapi_sqla/__init__.py

@@ -14,7 +14,7 @@
 from sqlalchemy.orm import Query as DbQuery
 from sqlalchemy.orm.session import Session as SqlaSession, sessionmaker
 
-__all__ = ["Base", "Session", "setup"]
+__all__ = ["Base", "Page", "Paginate", "Session", "setup"]
 
 logger = structlog.get_logger(__name__)
 
@@ -140,15 +140,12 @@ class Meta(BaseModel):
     page_number: int = Field(..., description="Current page number. Starts at 1.")
 
 
-class Paginated(Collection, Generic[T]):
-    """Paginated collection with information on current page and total items in meta."""
+class Page(Collection, Generic[T]):
+    """A page of the collection with info on current page and total items in meta."""
 
     meta: Meta
 
 
-PaginatedResult = Callable[[DbQuery], Paginated[T]]
-
-
 def _query_count(session: Session, query: DbQuery) -> int:
     """Default function used to count items returned by a query.
 
@@ -160,21 +157,24 @@ def _query_count(session: Session, query: DbQuery) -> int:
     return query.count()
 
 
+PaginateSignature = Callable[[DbQuery], Page[T]]
+
+
 def Pagination(
     min_page_size: int = 10,
     max_page_size: int = 100,
     query_count: Callable[[Session, DbQuery], int] = _query_count,
-) -> Callable[[Session, int, int], PaginatedResult]:
+) -> Callable[[Session, int, int], PaginateSignature]:
     def dependency(
         session: Session = Depends(),
         offset: int = Query(0, ge=0),
         limit: int = Query(min_page_size, ge=1, le=max_page_size),
-    ) -> PaginatedResult:
-        def paginated_result(query: DbQuery) -> Paginated[T]:
+    ) -> PaginateSignature:
+        def paginate(query: DbQuery) -> Page[T]:
             total_items = query_count(session, query)
             total_pages = math.ceil(total_items / limit)
             page_number = offset / limit + 1
-            return Paginated[T](
+            return Page[T](
                 data=query.offset(offset).limit(limit).all(),
                 meta={
                     "offset": offset,
@@ -184,9 +184,9 @@ def paginated_result(query: DbQuery) -> Paginated[T]:
                 },
             )
 
-        return paginated_result
+        return paginate
 
     return dependency
 
 
-with_pagination = Pagination()
+Paginate: PaginateSignature = Pagination()

tests/test_pagination.py

@@ -33,7 +33,8 @@ def setup_tear_down(engine):
     note = Table("note", metadata, autoload=True, autoload_with=engine)
     user_params = [{"id": i, "name": faker.name()} for i in range(1, 43)]
     note_params = [
-        {"user_id": i % 42 + 1, "id": math.ceil(i / 42)} for i in range(0, 84)
+        {"user_id": i % 42 + 1, "id": math.ceil(i / 42), "content": faker.text()}
+        for i in range(0, 84)
     ]
     engine.execute(user.insert(), *user_params)
     engine.execute(note.insert(), *note_params)
@@ -74,10 +75,10 @@ class Note(Base):
     [(0, 5, 9, 1), (10, 10, 5, 2), (40, 10, 5, 5)],
 )
 def test_pagination(session, user_cls, offset, limit, total_pages, page_number):
-    from fastapi_sqla import with_pagination
+    from fastapi_sqla import Paginate
 
     query = session.query(user_cls).options(joinedload("notes"))
-    result = with_pagination(session, offset, limit)(query)
+    result = Paginate(session, offset, limit)(query)
 
     assert result.meta.total_items == 42
     assert result.meta.offset == offset
@@ -99,9 +100,9 @@ def test_Pagination_with_custom_count(
         .statement.with_only_columns([func.count()])
         .scalar()
     )
-    with_pagination = Pagination(query_count=query_count)
+    pagination = Pagination(query_count=query_count)
     query = session.query(user_cls).options(joinedload("notes"))
-    result = with_pagination(session, offset, limit)(query)
+    result = pagination(session, offset, limit)(query)
 
     assert result.meta.total_items == 42
     assert result.meta.offset == offset
@@ -112,8 +113,7 @@ def test_Pagination_with_custom_count(
 @fixture
 def app(user_cls, note_cls):
     from sqlalchemy.orm import joinedload
-
-    from fastapi_sqla import Paginated, Session, setup, with_pagination
+    from fastapi_sqla import Page, Paginate, Session, setup
 
     app = FastAPI()
     setup(app)
@@ -122,19 +122,21 @@ class Note(BaseModel):
         id: int
         content: str
 
+        class Config:
+            orm_mode = True
+
     class User(BaseModel):
         id: int
         name: str
         notes: List[Note]
 
-    @app.get("/users")
-    def all_users(
-        session: Session = Depends(),
-        paginated_result=Depends(with_pagination),
-        reponse_model=Paginated[User],
-    ):
+        class Config:
+            orm_mode = True
+
+    @app.get("/users", response_model=Page[User])
+    def all_users(session: Session = Depends(), paginate: Paginate = Depends()):
         query = session.query(user_cls).options(joinedload("notes"))
-        return paginated_result(query)
+        return paginate(query)
 
     return app
 
@@ -156,7 +158,7 @@ async def client(app):
 async def test_functional(client, offset, items_number):
     result = await client.get("/users", params={"offset": offset})
 
-    assert result.status_code == 200
+    assert result.status_code == 200, result.json()
     users = result.json()["data"]
     assert len(users) == items_number
     user_ids = [u["id"] for u in users]