Add Search, rework bulk upsert

Author: pavdwest

README.md

@@ -25,37 +25,30 @@ TODO
 
     ```git clone git@github.com:pavdwest/docker_litestar_piccolo_pg.git```
 
-2. Enter app directory:
+2. Create .env file and populate with your own secrets:
 
-    ```cd docker_litestar_piccolo_pg/services/backend/app```
-
-3. Create & activate virtual environment:
-
-    ```uv venv .venv && source .venv/bin/activate```
+    ```cp docker_litestar_piccolo_pg/.env.example docker_litestar_piccolo_pg/.env```
 
-4. Install dependencies for local development/intellisense:
+3. Enter app directory:
 
-    ```uv sync```
-
-5. Add .env file and populate with your secrets:
-
-    ```cd ../../..```
+    ```cd docker_litestar_piccolo_pg/services/backend/app```
 
-    ```cp ./.env.example ./.env```
+4. Create & activate virtual environment (only required for local development):
 
+    ```uv venv .venv && source .venv/bin/activate && uv sync```
 
-6. Run stack (we attach only to the backend to ignore other containers' log spam):
+5. Run stack (we attach only to the backend to ignore other containers' log spam):
 
     ```docker compose up --build --attach backend```
 
-7. Everything's running:
+6. Everything's running:
 
     [http://127.0.0.1:8000/schema](http://127.0.0.1:8000/schema)
 
-8. Run migrations with Piccolo migrations:
+7. Run migrations with Piccolo migrations:
 
     TODO
 
-9. Run tests:
+8. Run tests:
 
     `docker compose exec backend pytest`

docker-compose.yml

@@ -1,6 +1,6 @@
 services:
   database-host:
-    image: postgres:16-alpine
+    image: postgres:17-alpine
     restart: unless-stopped
     environment:
       POSTGRES_INITDB_ARGS: --auth-host=scram-sha-256

services/backend/app/pyproject.toml

@@ -14,6 +14,7 @@ dependencies = [
     "sqlalchemy-utils>=0.41.2",
     "psycopg2-binary>=2.9.10",
     "pytest-asyncio>=0.25.3",
+    "polars>=1.22.0",
 ]
 
 [dependency-groups]

services/backend/app/src/app.py

@@ -1,4 +1,5 @@
 from typing import Sequence
+import socket
 
 from litestar import Litestar
 from litestar.openapi import OpenAPIConfig
@@ -11,7 +12,6 @@
 )
 from litestar_granian import GranianPlugin
 
-from src.config import PROJECT_NAME
 from src.versions import AppVersion
 from src.controllers.all import CONTROLLERS
 
@@ -20,15 +20,15 @@ def create_app(lifespan: Sequence) -> Litestar:
     app = Litestar(
         lifespan=lifespan,
         openapi_config=OpenAPIConfig(
-            title=f"{PROJECT_NAME} API v{AppVersion.BETA}",
-            description="Powered by LiteStar",
+            title="Project API",
+            description="Powered by LiteStar: <a href='/schema/openapi.json'>schema.json</a>",
             version=f"{AppVersion.BETA}",
             render_plugins=[
                 RapidocRenderPlugin(path="rapidoc"),
                 ScalarRenderPlugin(path="scalar"),
-                SwaggerRenderPlugin(path="swagger"),
                 StoplightRenderPlugin(path="stoplight"),
                 RedocRenderPlugin(path="redoc"),
+                SwaggerRenderPlugin(path="swagger"),
             ],
         ),
         plugins=[GranianPlugin()],

services/backend/app/src/constants.py

@@ -0,0 +1,2 @@
+STRING_SHORT_LENGTH = 256
+STRING_LONG_LENGTH = 4096

services/backend/app/src/controllers/crud.py

@@ -5,6 +5,8 @@
 from litestar.exceptions import HTTPException
 from msgspec import Struct
 from litestar.openapi import ResponseSpec
+from enum import StrEnum
+import operator
 
 from src.models.base import AppModel
 from src.controllers.base import AppController
@@ -13,13 +15,26 @@
     AppReadDTO,
     AppUpdateDTO,
     AppUpdateWithIdDTO,
+    AppSearchDTO,
     AppBulkActionResultDTO,
     AppReadAllPaginationDetailsDTO,
     IntID,
+    IntPositive,
     IntNonNegative,
     IntMaxLimit,
 )
-from src.responses import ConflictResponse
+from src.response_specs import ConflictResponse
+
+
+class JoinOperator(StrEnum):
+    AND: str = "and"
+    OR: str = "or"
+
+    def operator_mapping(self):
+        if self == JoinOperator.AND:
+            return operator.and_
+        elif self == JoinOperator.OR:
+            return operator.or_
 
 
 class CrudController(AppController): ...
@@ -31,6 +46,7 @@ def generate_crud_controller(
     ReadDTO: type[AppReadDTO],
     UpdateDTO: type[AppUpdateDTO],
     UpdateWithIdDTO: type[AppUpdateWithIdDTO],
+    SearchDTO: type[AppSearchDTO],
     api_version_prefix: str,
     exclude_from_auth: bool = False,
     read_all_limit_default: int = 100,
@@ -62,7 +78,6 @@ def generate_crud_controller(
             status_codes.HTTP_409_CONFLICT: ResponseSpec(
                 data_container=ConflictResponse,
                 description=f"Cannot create a {Model.humanise()} because one with the same primary key already exists.",
-                examples=ConflictResponse.examples,
             )
         },
     )
@@ -247,4 +262,26 @@ async def delete_all(
         await Model.delete_all(force=True)
     setattr(controller_class, "delete_all", delete_all)
 
+
+    @post(
+        "/search",
+        description=f"Search for {pluralize(Model.humanise())}.",
+        exclude_from_auth=exclude_from_auth,
+        status_code=status_codes.HTTP_200_OK,
+    )
+    async def search(
+        self,
+        data: SearchDTO,  # type: ignore
+        join_operator: JoinOperator = JoinOperator.AND,
+        offset: IntNonNegative = 0,
+        limit: IntMaxLimit = read_all_limit_default,
+    ) -> list[ReadDTO]: # type: ignore
+        return await Model.search(
+            data,
+            join_operator.operator_mapping(),
+            offset,
+            read_all_limit_default
+        )
+    setattr(controller_class, "search", search)
+
     return controller_class

services/backend/app/src/dtos.py

@@ -1,21 +1,20 @@
-from datetime import datetime
-from typing import Annotated
+from datetime import datetime, timedelta
+from typing import Annotated, Optional
 from functools import lru_cache
 
 from litestar.params import Parameter
 from msgspec import Struct, structs
 
-from src.models.constants import STRING_SHORT_LENGTH, STRING_LONG_LENGTH
+from src.constants import STRING_SHORT_LENGTH, STRING_LONG_LENGTH
 
 
 # Some commonly used constraints
-IntID = Annotated[int, Parameter(ge=1, le=2**63 - 1)]
-StringShort = Annotated[str, Parameter(min_length=1, max_length=STRING_SHORT_LENGTH)]
-StringLong = Annotated[str, Parameter(min_length=1, max_length=STRING_LONG_LENGTH)]
+IntID = Annotated[int, Parameter(ge=1)]
+StringShort = Annotated[str, Parameter(max_length=STRING_SHORT_LENGTH)]
+StringLong = Annotated[str, Parameter(max_length=STRING_LONG_LENGTH)]
 IntPositive = Annotated[int, Parameter(ge=1)]
 IntNonNegative = Annotated[int, Parameter(ge=0)]
 IntMaxLimit = Annotated[int, Parameter(ge=1, le=200)]
-DatetimeMin = Annotated[datetime, Parameter(ge=datetime(1970, 1, 1))]
 
 
 # Abstract
@@ -32,23 +31,23 @@ def dict_ordered(self):
 
 
 class AppReadDTO(AppDTO):
-    id: IntID
-    created_at: DatetimeMin
-    updated_at: DatetimeMin
+    id: IntPositive
+    created_at: datetime
+    updated_at: datetime
     is_active: bool
 
 
 class AppCreateDTO(AppDTO):
-    is_active: bool = True
+    is_active: Optional[bool] = True
 
 
 class AppUpdateDTO(AppDTO):
-    is_active: bool = True
+    is_active: Optional[bool] = None
 
 
 class AppUpdateWithIdDTO(AppDTO):
-    id: IntID
-    is_active: bool = True
+    id: IntPositive
+    is_active: Optional[bool] = None
 
     @classmethod
     @lru_cache(maxsize=1)
@@ -67,12 +66,20 @@ class AppDeleteAllDTO(AppDTO):
 
 
 class AppDeleteResponseDTO(AppDTO):
-    id: IntID
+    id: IntPositive
 
 
 class AppDeleteAllResponseDTO(AppDTO):
     count: IntNonNegative
 
 
 class AppBulkActionResultDTO(AppDTO):
-    ids: list[IntID]
+    ids: list[IntPositive]
+
+
+class AppSearchDTO(AppDTO, kw_only=True):
+    created_at_min: Optional[datetime] = None
+    created_at_max: Optional[datetime] = None
+    updated_at_min: Optional[datetime] = None
+    updated_at_max: Optional[datetime] = None
+    is_active: Optional[bool] = None