Merge pull request #35 from igorbenav/34-dont-return-arrays-as-top-level-responses

34 dont return arrays as top level responses

Author: igorbenav

README.md

@@ -48,6 +48,7 @@
 - 👜 Easy client-side caching
 - 🚦 ARQ integration for task queue
 - ⚙️ Efficient querying (only queries what's needed)
+- ⎘ Out of the box pagination support
 - 👮 FastAPI docs behind authentication and hidden based on the environment
 - 🦾 Easily extendable
 - 🤸‍♂️ Flexible
@@ -65,7 +66,6 @@
 #### Features
 - [ ] Add a Rate Limiter decorator
 - [ ] Add mongoDB support
-- [x] Add support in schema_to_select for a list of column names
 
 #### Tests
 - [ ] Add Ruff linter
@@ -569,20 +569,48 @@ crud_users = CRUDUser(User)
 
 When actually using the crud in an endpoint, to get data you just pass the database connection and the attributes as kwargs:
 ```python
-# Here I'm getting the users with email == user.email
+# Here I'm getting the first user with email == user.email (email is unique in this case)
 user = await crud_users.get(db=db, email=user.email)
 ```
 
 To get a list of objects with the attributes, you should use the get_multi:
 ```python
-# Here I'm getting 100 users with the name David except for the first 3
+# Here I'm getting at most 10 users with the name 'User Userson' except for the first 3
 user = await crud_users.get_multi(
   db=db,
   offset=3,
   limit=100,
-  name="David"
+  name="User Userson"
 )
 ```
+> **Warning**
+> Note that get_multi returns a python `dict`.
+
+Which will return a python dict with the following structure:
+```javascript
+{
+  "data": [
+    {
+      "id": 4,
+      "name": "User Userson",
+      "username": "userson4",
+      "email": "[email protected]",
+      "profile_image_url": "https://profileimageurl.com"
+    },
+    {
+      "id": 5,
+      "name": "User Userson",
+      "username": "userson5",
+      "email": "[email protected]",
+      "profile_image_url": "https://profileimageurl.com"
+    }
+  ],
+  "total_count": 2,
+  "has_more": false,
+  "page": 1,
+  "items_per_page": 10
+}
+```
 
 To create, you pass a `CreateSchemaType` object with the attributes, such as a `UserCreate` pydantic schema:
 ```python
@@ -606,6 +634,15 @@ To just check if there is at least one row that matches a certain set of attribu
 crud_users.exists(db=db, email=user@example.com)
 ```
 
+You can also get the count of a certain object with the specified filter:
+```python
+# Here I'm getting the count of users with the name 'User Userson'
+user = await crud_users.count(
+  db=db,
+  name="User Userson"
+)
+```
+
 To update you pass an `object` which may be a `pydantic schema` or just a regular `dict`, and the kwargs.
 You will update with `objects` the rows that match your `kwargs`.
 ```python
@@ -696,7 +733,7 @@ async def sample_endpoint(request: Request, my_id: int):
 
 The way it works is:
 - the data is saved in redis with the following cache key: `sample_data:{my_id}`
-- then the the time to expire is set as 3600 seconds (that's the default)
+- then the time to expire is set as 3600 seconds (that's the default)
 
 Another option is not passing the `resource_id_name`, but passing the `resource_id_type` (default int):
 ```python

docker-compose.yml

@@ -37,6 +37,8 @@ services:
       - ./src/.env
     volumes:
       - postgres-data:/var/lib/postgresql/data
+    ports:
+      - "5432:5432"
 
   redis:
     image: redis:alpine

src/app/api/v1/posts.py

@@ -12,6 +12,7 @@
 from app.crud.crud_users import crud_users
 from app.api.exceptions import privileges_exception
 from app.core.cache import cache
+from app.core.models import PaginatedListResponse
 
 router = fastapi.APIRouter(tags=["posts"])
 
@@ -27,29 +28,45 @@ async def write_post(
     if db_user is None:
         raise HTTPException(status_code=404, detail="User not found")
 
-    if current_user.id != db_user.id:
+    if current_user.id != db_user["id"]:
         raise privileges_exception
 
     post_internal_dict = post.model_dump()
-    post_internal_dict["created_by_user_id"] = db_user.id
+    post_internal_dict["created_by_user_id"] = db_user["id"]
 
     post_internal = PostCreateInternal(**post_internal_dict)
     return await crud_posts.create(db=db, object=post_internal)
 
 
-@router.get("/{username}/posts", response_model=List[PostRead])
+@router.get("/{username}/posts", response_model=PaginatedListResponse[PostRead])
 @cache(key_prefix="{username}_posts", resource_id_name="username")
 async def read_posts(
     request: Request,
-    username: str, 
-    db: Annotated[AsyncSession, Depends(async_get_db)]
+    username: str,
+    db: Annotated[AsyncSession, Depends(async_get_db)],
+    page: int = 1,
+    items_per_page: int = 10
 ):
     db_user = await crud_users.get(db=db, schema_to_select=UserRead, username=username, is_deleted=False)
-    if db_user is None:
+    if not db_user:
         raise HTTPException(status_code=404, detail="User not found")
-    
-    posts = await crud_posts.get_multi(db=db, schema_to_select=PostRead, created_by_user_id=db_user.id, is_deleted=False)
-    return posts
+
+    posts_data = await crud_posts.get_multi(
+        db=db,
+        offset=(page - 1) * items_per_page,
+        limit=items_per_page,
+        schema_to_select=PostRead,
+        created_by_user_id=db_user["id"],
+        is_deleted=False
+    )
+
+    return {
+        "data": posts_data["data"],
+        "total_count": posts_data["total_count"],
+        "has_more": (page * items_per_page) < posts_data["total_count"],
+        "page": page,
+        "items_per_page": items_per_page
+    }
 
 
 @router.get("/{username}/post/{id}", response_model=PostRead)
@@ -64,10 +81,10 @@ async def read_post(
     if db_user is None:
         raise HTTPException(status_code=404, detail="User not found")
 
-    db_post = await crud_posts.get(db=db, schema_to_select=PostRead, id=id, created_by_user_id=db_user.id, is_deleted=False)
+    db_post = await crud_posts.get(db=db, schema_to_select=PostRead, id=id, created_by_user_id=db_user["id"], is_deleted=False)
     if db_post is None:
         raise HTTPException(status_code=404, detail="Post not found")
-
+    
     return db_post
 
 
@@ -89,7 +106,7 @@ async def patch_post(
     if db_user is None:
         raise HTTPException(status_code=404, detail="User not found")
 
-    if current_user.id != db_user.id:
+    if current_user.id != db_user["id"]:
         raise privileges_exception
 
     db_post = await crud_posts.get(db=db, schema_to_select=PostRead, id=id, is_deleted=False)

src/app/api/v1/users.py

@@ -11,6 +11,7 @@
 from app.core.security import get_password_hash
 from app.crud.crud_users import crud_users
 from app.api.exceptions import privileges_exception
+from app.core.models import PaginatedListResponse
 
 router = fastapi.APIRouter(tags=["users"])
 
@@ -36,10 +37,28 @@ async def write_user(
     return await crud_users.create(db=db, object=user_internal)
 
 
-@router.get("/users", response_model=List[UserRead])
-async def read_users(request: Request, db: Annotated[AsyncSession, Depends(async_get_db)]):
-    users = await crud_users.get_multi(db=db, schema_to_select=UserRead, is_deleted=False)
-    return users
+@router.get("/users", response_model=PaginatedListResponse[UserRead])
+async def read_users(
+    request: Request, 
+    db: Annotated[AsyncSession, Depends(async_get_db)],
+    page: int = 1,
+    items_per_page: int = 10
+):
+    users_data = await crud_users.get_multi(
+        db=db,
+        offset=(page - 1) * items_per_page,
+        limit=items_per_page,
+        schema_to_select=UserRead, 
+        is_deleted=False
+    )
+    
+    return {
+        "data": users_data["data"],
+        "total_count": users_data["total_count"],
+        "has_more": (page * items_per_page) < users_data["total_count"],
+        "page": page,
+        "items_per_page": items_per_page
+    }
 
 
 @router.get("/user/me/", response_model=UserRead)

src/app/core/cache.py

@@ -6,8 +6,8 @@
 import re
 
 from fastapi import Request, Response
+from fastapi.encoders import jsonable_encoder
 from redis.asyncio import Redis, ConnectionPool
-from sqlalchemy.orm import class_mapper, DeclarativeBase
 from fastapi import FastAPI
 from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
 
@@ -18,40 +18,6 @@
 pool: ConnectionPool | None = None
 client: Redis | None = None
 
-def _serialize_sqlalchemy_object(obj: DeclarativeBase) -> Dict[str, Any]:
-    """
-    Serialize a SQLAlchemy DeclarativeBase object to a dictionary.
-
-    Parameters
-    ----------
-    obj: DeclarativeBase
-        The SQLAlchemy DeclarativeBase object to be serialized.
-        
-    Returns
-    -------
-    Dict[str, Any] 
-        A dictionary containing the serialized attributes of the object.
-    
-    Note
-    ----
-        - Datetime objects are converted to ISO 8601 string format.
-        - UUID objects are converted to strings before serializing to JSON.
-    """
-    if isinstance(obj, DeclarativeBase):
-        data = {}
-        for column in class_mapper(obj.__class__).columns:
-            value = getattr(obj, column.name)
-
-            if isinstance(value, datetime):
-                value = value.isoformat()
-            
-            if isinstance(value, UUID):
-                value = str(value)
-
-            data[column.name] = value
-        return data
-
-
 def _infer_resource_id(kwargs: Dict[str, Any], resource_id_type: Union[type, str]) -> Union[None, int, str]:
     """
     Infer the resource ID from a dictionary of keyword arguments.
@@ -236,8 +202,8 @@ async def sample_endpoint(request: Request, resource_id: int):
     This decorator caches the response data of the endpoint function using a unique cache key.
     The cached data is retrieved for GET requests, and the cache is invalidated for other types of requests.
 
-    Note:
-        - For caching lists of objects, ensure that the response is a list of objects, and the decorator will handle caching accordingly.
+    Note
+    ----
         - resource_id_type is used only if resource_id is not passed.
     """
     def wrapper(func: Callable) -> Callable:
@@ -250,32 +216,26 @@ async def inner(request: Request, *args, **kwargs) -> Response:
 
             formatted_key_prefix = _format_prefix(key_prefix, kwargs)
             cache_key = f"{formatted_key_prefix}:{resource_id}"
-            
             if request.method == "GET":
                 if to_invalidate_extra:
                     raise InvalidRequestError
 
                 cached_data = await client.get(cache_key)
                 if cached_data:
+                    print("cache hit")
                     return json.loads(cached_data.decode())
-            
+                
             result = await func(request, *args, **kwargs)
 
             if request.method == "GET":
-                if to_invalidate_extra:
-                    raise InvalidRequestError
+                serializable_data = jsonable_encoder(result)
+                serialized_data = json.dumps(serializable_data)
 
-                if isinstance(result, list):
-                    serialized_data = json.dumps(
-                        [_serialize_sqlalchemy_object(obj) for obj in result]
-                    )
-                else:
-                    serialized_data = json.dumps(
-                        _serialize_sqlalchemy_object(result)
-                    )
-                
                 await client.set(cache_key, serialized_data)
                 await client.expire(cache_key, expiration)
+
+                serialized_data = json.loads(serialized_data)
+                
             else:
                 await client.delete(cache_key)
                 if to_invalidate_extra:

src/app/core/models.py

@@ -1,10 +1,22 @@
+from typing import TypeVar, Generic, List
 import uuid as uuid_pkg
 from datetime import datetime
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_serializer
 from sqlalchemy import text
 
-from app.core.database import Base
+ReadSchemaType = TypeVar("ReadSchemaType", bound=BaseModel)
+
+class ListResponse(BaseModel, Generic[ReadSchemaType]):
+    data: List[ReadSchemaType]
+
+
+class PaginatedListResponse(ListResponse[ReadSchemaType]):
+    total_count: int
+    has_more: bool
+    page: int | None = None
+    items_per_page: int | None = None
+
 
 class HealthCheck(BaseModel):
     name: str
@@ -47,7 +59,16 @@ class TimestampModel(BaseModel):
        }
     )
 
-    
+    @field_serializer("created_at")
+    def serialize_dt(self, created_at: datetime | None, _info):
+        return created_at.isoformat()
+
+    @field_serializer("updated_at")
+    def serialize_updated_at(self, updated_at: datetime | None, _info):
+        if updated_at is not None:
+            return updated_at.isoformat()
+
+
 class PersistentDeletion(BaseModel):
     deleted_at: datetime | None = Field(
         default=None,
@@ -58,3 +79,8 @@ class PersistentDeletion(BaseModel):
     )
 
     is_deleted: bool = False
+
+    @field_serializer('deleted_at')
+    def serialize_dates(self, deleted_at: datetime | None, _info):
+        if deleted_at is not None:
+            return deleted_at.isoformat()