Merge branch 'main' into pjh/convert-backend-protocols-to-callables

Author: pjhartzell

.github/workflows/python-publish.yml

@@ -1,37 +1,36 @@
-name: Build Python Package
+name: PR Checks
 
 on:
-  push:
-    branches:
-      - main
   pull_request:
-    branches:
-      - main
-  release:
-    types:
-      - published
+    branches: ["main"]
 
 jobs:
-  build-package:
+  test:
     runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/stapi-fastapi
-    permissions:
-      id-token: write
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python
-        uses: actions/setup-python@v5
+      - uses: actions/setup-python@v5
         with:
-          python-version: "3.x"
-      - name: Install dependencies
+          python-version: ${{ matrix.python-version }}
+      - name: Cache dependencies
+        uses: actions/cache@v3
+        with:
+          path: |
+            ~/.cache/pip
+            .venv
+          key: ${{ runner.os }}-pip-${{ matrix.python-version }}-${{ hashFiles('poetry.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-pip-${{ matrix.python-version }}-
+            ${{ runner.os }}-pip-
+      - name: Install
+        run: |
+          python -m pip install poetry==1.7.1
+          poetry install --with=dev
+      - name: Lint
         run: |
-          python -m pip install --upgrade pip
-          pip install build
-          pip install .
-      - name: Build package
-        run: python -m build
-      - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@release/v1
-        if: startsWith(github.ref, 'refs/tags')
+          poetry run pre-commit run --all-files
+      - name: Test
+        run: poetry run pytest

README.md

@@ -8,6 +8,21 @@ guaranteed to be not correct.
 STAPI FastAPI provides an `fastapi.APIRouter` which must be included in
 `fastapi.FastAPI` instance.
 
+### Pagination
+
+4 endpoints currently offer pagination:
+`GET`: `'/orders`, `/products`, `/orders/{order_id}/statuses`
+`POST`: `/opportunities`.
+
+Pagination is token based and follows recommendations in the [STAC API pagination].
+Limit and token are passed in as query params for `GET` endpoints, and via the body as
+separate key/value pairs for `POST` requests.
+
+If pagination is available and more records remain the response object will contain a
+`next` link object that can be used to get the next page of results. No `next` `Link`
+returned indicates there are no further records available.
+
+`limit` defaults to 10 and maxes at 100.
 
 ## ADRs
 
@@ -59,3 +74,4 @@ With the `uvicorn` defaults the app should be accessible at
 
 [STAPI spec]: https://github.com/stapi-spec/stapi-spec
 [poetry]: https://python-poetry.org/
+[STAC API pagination]: https://github.com/radiantearth/stac-api-spec/blob/release/v1.0.0/item-search/examples.md#paging-examples

src/stapi_fastapi/backends/product_backend.py

@@ -3,15 +3,16 @@
 from typing import Any, Callable, Coroutine
 
 from fastapi import Request
+from returns.maybe import Maybe
 from returns.result import ResultE
 
 from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
 from stapi_fastapi.models.order import Order, OrderPayload
 from stapi_fastapi.routers.product_router import ProductRouter
 
 SearchOpportunities = Callable[
-    [ProductRouter, OpportunityRequest, Request],
-    Coroutine[Any, Any, ResultE[list[Opportunity]]],
+    [ProductRouter, OpportunityRequest, Request, str | None, int],
+    Coroutine[Any, Any, ResultE[tuple[list[Opportunity], Maybe[str]]]],
 ]
 """
 Type alias for an async function that searches for ordering opportunities for the given
@@ -21,13 +22,19 @@
     product_router (ProductRouter): The product router.
     search (OpportunityRequest): The search parameters.
     request (Request): FastAPI's Request object.
+    next (str | None): A pagination token.
+    limit (int): The maximum number of opportunities to return in a page.
 
 Returns:
-    - Should return returns.result.Success[list[Opportunity]]
+    A tuple containing a list of opportunities and a pagination token.
+
+    - Should return returns.result.Success[tuple[list[Opportunity], returns.maybe.Some[str]]] if including a pagination token
+    - Should return returns.result.Success[tuple[list[Opportunity], returns.maybe.Nothing]] if not including a pagination token
     - Returning returns.result.Failure[Exception] will result in a 500.
 
-Backends must validate search constraints and return
-returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
+Note:
+    Backends must validate search constraints and return
+    returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
 """
 
 CreateOrder = Callable[
@@ -45,6 +52,7 @@
     - Should return returns.result.Success[Order]
     - Returning returns.result.Failure[Exception] will result in a 500.
 
-Backends must validate order payload and return
-returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
+Note:
+    Backends must validate order payload and return
+    returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
 """

src/stapi_fastapi/backends/root_backend.py

@@ -6,19 +6,26 @@
 
 from stapi_fastapi.models.order import (
     Order,
-    OrderCollection,
     OrderStatus,
 )
 
-GetOrders = Callable[[Request], Coroutine[Any, Any, ResultE[OrderCollection]]]
+GetOrders = Callable[
+    [Request, str | None, int],
+    Coroutine[Any, Any, ResultE[tuple[list[Order], Maybe[str]]]],
+]
 """
 Type alias for an async function that returns a list of existing Orders.
 
 Args:
     request (Request): FastAPI's Request object.
+    next (str | None): A pagination token.
+    limit (int): The maximum number of orders to return in a page.
 
 Returns:
-    - Should return returns.result.Success[OrderCollection]
+    A tuple containing a list of orders and a pagination token.
+
+    - Should return returns.result.Success[tuple[list[Order], returns.maybe.Some[str]]] if including a pagination token
+    - Should return returns.result.Success[tuple[list[Order], returns.maybe.Nothing]] if not including a pagination token
     - Returning returns.result.Failure[Exception] will result in a 500.
 """
 
@@ -37,21 +44,33 @@
     - Returning returns.result.Failure[Exception] will result in a 500.
 """
 
+# async def get_order_statuses(
+#     self, order_id: str, request: Request, next: str | None, limit: int
+# ) -> ResultE[tuple[list[T], Maybe[str]]]:
+#     """
+#     Get statuses for order with `order_id` and return pagination token if applicable
 
 T = TypeVar("T", bound=OrderStatus)
 
 
-GetOrderStatuses = Callable[[str, Request], Coroutine[Any, Any, ResultE[list[T]]]]
+GetOrderStatuses = Callable[
+    [str, Request, str | None, int],
+    Coroutine[Any, Any, ResultE[tuple[list[T], Maybe[str]]]],
+]
 """
 Type alias for an async function that gets statuses for the order with `order_id`.
 
 Args:
     order_id (str): The order ID.
     request (Request): FastAPI's Request object.
+    next (str | None): A pagination token.
+    limit (int): The maximum number of statuses to return in a page.
 
 Returns:
-    - Should return returns.result.Success[list[OrderStatus]] if order is found.
-    - Should return returns.result.Failure[Exception] if the order is not found or if
-    access is denied.
+    A tuple containing a list of order statuses and a pagination token.
+
+    - Should return returns.result.Success[tuple[list[OrderStatus], returns.maybe.Some[str]] if order is found and including a pagination token.
+    - Should return returns.result.Success[tuple[list[OrderStatus], returns.maybe.Nothing]] if order is found and not including a pagination token.
+    - Should return returns.result.Failure[Exception] if the order is not found or if access is denied.
     - Returning returns.result.Failure[Exception] will result in a 500.
 """

src/stapi_fastapi/routers/product_router.py

@@ -2,10 +2,11 @@
 
 import logging
 import traceback
-from typing import TYPE_CHECKING, Self
+from typing import TYPE_CHECKING, Annotated, Self
 
-from fastapi import APIRouter, HTTPException, Request, Response, status
+from fastapi import APIRouter, Body, HTTPException, Request, Response, status
 from geojson_pydantic.geometries import Geometry
+from returns.maybe import Some
 from returns.result import Failure, Success
 
 from stapi_fastapi.constants import TYPE_JSON
@@ -161,27 +162,29 @@ def get_product(self, request: Request) -> Product:
         )
 
     async def search_opportunities(
-        self, search: OpportunityRequest, request: Request
+        self,
+        search: OpportunityRequest,
+        request: Request,
+        next: Annotated[str | None, Body()] = None,
+        limit: Annotated[int, Body()] = 10,
     ) -> OpportunityCollection:
         """
         Explore the opportunities available for a particular set of constraints
         """
-        match await self.product.search_opportunities(self, search, request):
-            case Success(features):
-                return OpportunityCollection(
-                    features=features,
-                    links=[
-                        Link(
-                            href=str(
-                                request.url_for(
-                                    f"{self.root_router.name}:{self.product.id}:create-order",
-                                ),
-                            ),
-                            rel="create-order",
-                            type=TYPE_JSON,
-                        ),
-                    ],
-                )
+        links: list[Link] = []
+        match await self.product._search_opportunities(
+            self, search, request, next, limit
+        ):
+            case Success((features, Some(pagination_token))):
+                links.append(self.order_link(request))
+                body = {
+                    "search": search.model_dump(mode="json"),
+                    "next": pagination_token,
+                    "limit": limit,
+                }
+                links.append(self.pagination_link(request, body))
+            case Success((features, Nothing)):  # noqa: F841
+                links.append(self.order_link(request))
             case Failure(e) if isinstance(e, ConstraintsException):
                 raise e
             case Failure(e):
@@ -195,6 +198,7 @@ async def search_opportunities(
                 )
             case x:
                 raise AssertionError(f"Expected code to be unreachable {x}")
+        return OpportunityCollection(features=features, links=links)
 
     def get_product_constraints(self: Self) -> JsonSchemaModel:
         """
@@ -237,3 +241,24 @@ async def create_order(
                 )
             case x:
                 raise AssertionError(f"Expected code to be unreachable {x}")
+
+    def order_link(self, request: Request):
+        return Link(
+            href=str(
+                request.url_for(
+                    f"{self.root_router.name}:{self.product.id}:create-order",
+                ),
+            ),
+            rel="create-order",
+            type=TYPE_JSON,
+            method="POST",
+        )
+
+    def pagination_link(self, request: Request, body: dict[str, str | dict]):
+        return Link(
+            href=str(request.url.remove_query_params(keys=["next", "limit"])),
+            rel="next",
+            type=TYPE_JSON,
+            method="POST",
+            body=body,
+        )