Merge branch 'main' into pv/add-additional-status-codes

Author: Phil Varner

.github/workflows/pr.yml

@@ -9,23 +9,28 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.12"]
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
-      - run: pipx install poetry==1.7.1
       - uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: poetry
-      - name: Install dependencies
-        run: poetry install --with=dev
-      - name: Lint code
-        if: ${{ matrix.python-version == 3.12 }}
+      - 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 pre-commit
-          pre-commit run --all-files
-      - name: Type-check code
-        if: ${{ matrix.python-version == 3.12 }}
-        run: poetry run mypy src
-      - name: Run tests
-        run: poetry run nox
+          poetry run pre-commit run --all-files
+      - name: Test
+        run: poetry run pytest

CHANGELOG.md

@@ -5,13 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
-## Unreleased
+## [unreleased]
 
 ### Added
 
+- Added token-based pagination to `GET /orders`, `GET /products`,
+  `GET /orders/{order_id}/statuses`, and `POST /products/{product_id}/opportunities`.
 - Optional and Extension STAPI Status Codes "scheduled", "held", "processing", "reserved", "tasked",
   and "user_cancelled"
 
+### Changed
+
+- Replaced the root and product backend Protocol classes with Callable type aliases to
+  enable future changes to make product opportunity searching, product ordering, and/or
+  asynchronous (stateful) product opportunity searching optional.
+- Backend methods that support pagination now return tuples to include the pagination
+  token.
+- Moved `OrderCollection` construction from the root backend to the `RootRouter`
+  `get_orders` method.
+- Renamed `OpportunityRequest` to `OpportunityPayload` so that would not be confused as
+  being a subclass of the Starlette/FastAPI Request class.
+
+### Fixed
+
+- Opportunities Search result now has the search body in the `create-order` link.
+
 ## [v0.5.0] - 2025-01-08
 
 ### Added
@@ -70,7 +88,6 @@ none
 
 none
 
-
 ## [v0.3.0] - 2024-12-6
 
 ### Added
@@ -81,7 +98,7 @@ none
 
 - OrderStatusCode and ProviderRole are now StrEnum instead of (str, Enum)
 - All types using `Result[A, Exception]` have been replace with the equivalent type `ResultE[A]`
-- Order and OrderCollection extend _GeoJsonBase instead of Feature and FeatureCollection, to allow for tighter
+- Order and OrderCollection extend \_GeoJsonBase instead of Feature and FeatureCollection, to allow for tighter
   constraints on fields
 
 ### Deprecated
@@ -146,7 +163,7 @@ Initial release
 - Add link `create-order` to OpportunityCollection
 
 [unreleased]: https://github.com/stapi-spec/stapi-fastapi/compare/v0.5.0...main
-[v0.4.0]: https://github.com/stapi-spec/stapi-fastapi/tree/v0.5.0
+[v0.5.0]: https://github.com/stapi-spec/stapi-fastapi/tree/v0.5.0
 [v0.4.0]: https://github.com/stapi-spec/stapi-fastapi/tree/v0.4.0
 [v0.3.0]: https://github.com/stapi-spec/stapi-fastapi/tree/v0.3.0
 [v0.2.0]: https://github.com/stapi-spec/stapi-fastapi/tree/v0.2.0

README.md

@@ -14,13 +14,16 @@ STAPI FastAPI provides an `fastapi.APIRouter` which must be included in
 `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 aas separte key/value pairs for `POST` requests.
+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.
+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
 
 ADRs can be found in in the [adrs](./adrs/README.md) directory.

noxfile.py

@@ -1,7 +1,7 @@
 import nox
 
 
-@nox.session(python=["3.12"])
+@nox.session(python=["3.12", "3.13"])
 def tests(session):
     session.run("poetry", "install", external=True)
     session.run("poetry", "run", "pytest", external=True)

poetry.lock

@@ -9,7 +9,7 @@ readme = "README.md"
 packages = [{include = "stapi_fastapi", from="src"}]
 
 [tool.poetry.dependencies]
-python = "3.12.*"
+python = "^3.12.0"
 fastapi = "^0.115.0"
 pydantic = "^2.10.1"
 geojson-pydantic = "^1.1.1"

pyproject.toml

@@ -1,4 +1,3 @@
-from .backends import ProductBackend, RootBackend
 from .models import (
     Link,
     OpportunityProperties,
@@ -12,10 +11,8 @@
     "Link",
     "OpportunityProperties",
     "Product",
-    "ProductBackend",
     "ProductRouter",
     "Provider",
     "ProviderRole",
-    "RootBackend",
     "RootRouter",
 ]

src/stapi_fastapi/__init__.py

@@ -1,7 +1,10 @@
-from .product_backend import ProductBackend
-from .root_backend import RootBackend
+from .product_backend import CreateOrder, SearchOpportunities
+from .root_backend import GetOrder, GetOrders, GetOrderStatuses
 
 __all__ = [
-    "ProductBackend",
-    "RootBackend",
+    "CreateOrder",
+    "GetOrder",
+    "GetOrders",
+    "GetOrderStatuses",
+    "SearchOpportunities",
 ]

src/stapi_fastapi/backends/__init__.py

@@ -1,41 +1,58 @@
 from __future__ import annotations
 
-from typing import Protocol
+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.opportunity import Opportunity, OpportunityPayload
 from stapi_fastapi.models.order import Order, OrderPayload
 from stapi_fastapi.routers.product_router import ProductRouter
 
-
-class ProductBackend(Protocol):  # pragma: nocover
-    async def search_opportunities(
-        self,
-        product_router: ProductRouter,
-        search: OpportunityRequest,
-        request: Request,
-        next: str | None,
-        limit: int,
-    ) -> ResultE[tuple[list[Opportunity], Maybe[str]]]:
-        """
-        Search for ordering opportunities for the  given search parameters and return pagination token if applicable.
-
-        Backends must validate search constraints and return
-        `stapi_fastapi.exceptions.ConstraintsException` if not valid.
-        """
-
-    async def create_order(
-        self,
-        product_router: ProductRouter,
-        search: OrderPayload,
-        request: Request,
-    ) -> ResultE[Order]:
-        """
-        Create a new order.
-
-        Backends must validate order payload and return
-        `stapi_fastapi.exceptions.ConstraintsException` if not valid.
-        """
+SearchOpportunities = Callable[
+    [ProductRouter, OpportunityPayload, str | None, int, Request],
+    Coroutine[Any, Any, ResultE[tuple[list[Opportunity], Maybe[str]]]],
+]
+"""
+Type alias for an async function that searches for ordering opportunities for the given
+search parameters.
+
+Args:
+    product_router (ProductRouter): The product router.
+    search (OpportunityRequest): The search parameters.
+    next (str | None): A pagination token.
+    limit (int): The maximum number of opportunities to return in a page.
+    request (Request): FastAPI's Request object.
+
+Returns:
+    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.
+
+Note:
+    Backends must validate search constraints and return
+    returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
+"""
+
+CreateOrder = Callable[
+    [ProductRouter, OrderPayload, Request], Coroutine[Any, Any, ResultE[Order]]
+]
+"""
+Type alias for an async function that creates a new order.
+
+Args:
+    product_router (ProductRouter): The product router.
+    payload (OrderPayload): The order payload.
+    request (Request): FastAPI's Request object.
+
+Returns:
+    - Should return returns.result.Success[Order]
+    - Returning returns.result.Failure[Exception] will result in a 500.
+
+Note:
+    Backends must validate order payload and return
+    returns.result.Failure[stapi_fastapi.exceptions.ConstraintsException] if not valid.
+"""

src/stapi_fastapi/backends/product_backend.py

@@ -1,4 +1,4 @@
-from typing import Protocol
+from typing import Any, Callable, Coroutine, TypeVar
 
 from fastapi import Request
 from returns.maybe import Maybe
@@ -9,40 +9,63 @@
     OrderStatus,
 )
 
+GetOrders = Callable[
+    [str | None, int, Request],
+    Coroutine[Any, Any, ResultE[tuple[list[Order], Maybe[str]]]],
+]
+"""
+Type alias for an async function that returns a list of existing Orders.
 
-class RootBackend[T: OrderStatus](Protocol):  # pragma: nocover
-    async def get_orders(
-        self, request: Request, next: str | None, limit: int
-    ) -> ResultE[tuple[list[Order], Maybe[str]]]:
-        """
-        Return a list of existing orders and pagination token if applicable.
-        """
-        ...
+Args:
+    next (str | None): A pagination token.
+    limit (int): The maximum number of orders to return in a page.
+    request (Request): FastAPI's Request object.
 
-    async def get_order(self, order_id: str, request: Request) -> ResultE[Maybe[Order]]:
-        """
-        Get details for order with `order_id`.
+Returns:
+    A tuple containing a list of orders and a pagination token.
 
-        Should return returns.results.Success[Order] if order is found.
+    - 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.
+"""
 
-        Should return returns.results.Failure[returns.maybe.Nothing] if the
-        order is not found or if access is denied.
+GetOrder = Callable[[str, Request], Coroutine[Any, Any, ResultE[Maybe[Order]]]]
+"""
+Type alias for an async function that gets details for the order with `order_id`.
 
-        A Failure[Exception] will result in a 500.
-        """
-        ...
+Args:
+    order_id (str): The order ID.
+    request (Request): FastAPI's Request object.
 
-    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
+Returns:
+    - Should return returns.result.Success[returns.maybe.Some[Order]] if order is found.
+    - Should return returns.result.Success[returns.maybe.Nothing] if the order is not
+    found or if access is denied.
+    - Returning returns.result.Failure[Exception] will result in a 500.
+"""
 
-        Should return returns.results.Success[list[OrderStatus]] if order is found.
 
-        Should return returns.results.Failure[Exception] if the order is
-        not found or if access is denied.
+T = TypeVar("T", bound=OrderStatus)
 
-        A Failure[Exception] will result in a 500.
-        """
-        ...
+
+GetOrderStatuses = Callable[
+    [str, str | None, int, Request],
+    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.
+    next (str | None): A pagination token.
+    limit (int): The maximum number of statuses to return in a page.
+    request (Request): FastAPI's Request object.
+
+Returns:
+    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.
+"""