Merge branch 'mp/feat-subclass-router-issue-73' into feat-subclass-router-issue-73

Author: parksjr

pyproject.toml

@@ -6,6 +6,7 @@ description = "Spatio Temporal Asset Tasking with FastAPI"
 authors = ["Christian Wygoda <[email protected]>"]
 license = "MIT"
 readme = "README.md"
+packages = [{include = "stapi_fastapi", from="src"}]
 
 [tool.poetry.dependencies]
 python = "3.12.*"

src/stapi_fastapi/backends/__init__.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from typing import Protocol
+
+from fastapi import Request
+
+import stapi_fastapi
+from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
+from stapi_fastapi.models.order import Order
+
+
+class ProductBackend(Protocol):
+    async def search_opportunities(
+        self,
+        product: stapi_fastapi.models.product.Product,
+        search: OpportunityRequest,
+        request: Request,
+    ) -> list[Opportunity]:
+        """
+        Search for ordering opportunities for the  given search parameters.
+
+        Backends must validate search constraints and raise
+        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
+        """
+        ...
+
+    async def create_order(
+        self,
+        product: stapi_fastapi.models.product.Product,
+        search: OpportunityRequest,
+        request: Request,
+    ) -> Order:
+        """
+        Create a new order.
+
+        Backends must validate order payload and raise
+        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
+        """
+        ...

src/stapi_fastapi/backends/product_backend.py

@@ -0,0 +1,22 @@
+from typing import Protocol
+
+from fastapi import Request
+
+from stapi_fastapi.models.order import Order
+
+
+class RootBackend(Protocol):
+    async def get_orders(self, request: Request) -> list[Order]:
+        """
+        Return a list of existing orders.
+        """
+        ...
+
+    async def get_order(self, order_id: str, request: Request) -> Order:
+        """
+        Get details for order with `order_id`.
+
+        Backends must raise `stapi_fastapi.backend.exceptions.NotFoundException`
+        if not found or access denied.
+        """
+        ...

src/stapi_fastapi/backends/root_backend.py

@@ -1,10 +1,13 @@
 from typing import Any, Mapping
+
 from fastapi import HTTPException
 
+
 class StapiException(HTTPException):
     def __init__(self, status_code: int, detail: str) -> None:
         super().__init__(status_code, detail)
 
+
 class ConstraintsException(Exception):
     detail: Mapping[str, Any] | None
 

src/stapi_fastapi/exceptions.py

@@ -1,34 +1,33 @@
-from typing import Literal, Optional, TypeVar, Generic
+from typing import Literal, Optional
 
 from geojson_pydantic import Feature, FeatureCollection
 from geojson_pydantic.geometries import Geometry
 from pydantic import BaseModel, ConfigDict
 
+from stapi_fastapi.models.shared import Link
 from stapi_fastapi.types.datetime_interval import DatetimeInterval
 from stapi_fastapi.types.filter import CQL2Filter
 
-# Generic type definition for Opportunity Properties
-T = TypeVar("T")
 
 # Copied and modified from https://github.com/stac-utils/stac-pydantic/blob/main/stac_pydantic/item.py#L11
-class OpportunityProperties(BaseModel, Generic[T]):
+class OpportunityProperties(BaseModel):
     datetime: DatetimeInterval
     model_config = ConfigDict(extra="allow")
 
+
 class OpportunityRequest(BaseModel):
     datetime: DatetimeInterval
     geometry: Geometry
     # TODO: validate the CQL2 filter?
     filter: Optional[CQL2Filter] = None
     model_config = ConfigDict(strict=True)
 
-# Generic type definition for Opportunity
-P = TypeVar("P", bound=OpportunityProperties)
-K = TypeVar("K", bound=Geometry)
 
-# Each product implements its own opportunity model
-class Opportunity(Feature[K, P], Generic[K, P]):
+# GENERIC: Each product needs an opportunity model (constraints/parameters)
+class Opportunity(Feature[Geometry, OpportunityProperties]):
     type: Literal["Feature"] = "Feature"
+    links: list[Link] = []
+
 
-class OpportunityCollection(FeatureCollection[Opportunity[K, P]], Generic[K, P]):
+class OpportunityCollection(FeatureCollection[Opportunity]):
     type: Literal["FeatureCollection"] = "FeatureCollection"

src/stapi_fastapi/models/opportunity.py

@@ -1,13 +1,14 @@
+from __future__ import annotations
+
+from copy import deepcopy
 from enum import Enum
-from typing import Literal, Optional
-from abc import ABC, abstractmethod
-from fastapi import Request
+from typing import Literal, Optional, Self
 
 from pydantic import AnyHttpUrl, BaseModel, Field
 
+from stapi_fastapi.backends.product_backend import ProductBackend
+from stapi_fastapi.models.opportunity import OpportunityProperties
 from stapi_fastapi.models.shared import Link
-from stapi_fastapi.models.opportunity import Opportunity, OpportunityProperties, OpportunityRequest
-from stapi_fastapi.models.order import Order
 
 
 class ProviderRole(str, Enum):
@@ -24,8 +25,8 @@ class Provider(BaseModel):
     url: AnyHttpUrl
 
 
-class Product(BaseModel, ABC):
-    type: Literal["Product"] = "Product"
+class Product(BaseModel):
+    type_: Literal["Product"] = Field(default="Product", alias="type")
     conformsTo: list[str] = Field(default_factory=list)
     id: str
     title: str = ""
@@ -34,28 +35,38 @@ class Product(BaseModel, ABC):
     license: str
     providers: list[Provider] = Field(default_factory=list)
     links: list[Link]
-    parameters: OpportunityProperties
-
-    @abstractmethod
-    def search_opportunities(self, search: OpportunityRequest, request: Request
-    ) -> list[Opportunity]:
-        """
-        Search for ordering opportunities for the  given search parameters.
-
-        Backends must validate search constraints and raise
-        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
-        """
-        ...
-
-    @abstractmethod
-    def create_order(self, search: OpportunityRequest, request: Request) -> Order:
-        """
-        Create a new order.
-
-        Backends must validate order payload and raise
-        `stapi_fastapi.backend.exceptions.ConstraintsException` if not valid.
-        """
-        ...
+
+    # we don't want to include these in the model fields
+    _constraints: type[OpportunityProperties]
+    _backend: ProductBackend
+
+    def __init__(
+        self: Self,
+        *args,
+        backend: ProductBackend,
+        constraints: type[OpportunityProperties],
+        **kwargs,
+    ) -> None:
+        super().__init__(*args, **kwargs)
+        self._backend = backend
+        self._constraints = constraints
+
+    @property
+    def backend(self: Self) -> ProductBackend:
+        return self._backend
+
+    @property
+    def constraints(self: Self) -> type[OpportunityProperties]:
+        return self._constraints
+
+    def with_links(self: Self, links: list[Link] | None = None) -> Self:
+        if not links:
+            return self
+
+        new = deepcopy(self)
+        new.links.extend(links)
+        return new
+
 
 class ProductsCollection(BaseModel):
     type: Literal["ProductCollection"] = "ProductCollection"

src/stapi_fastapi/models/product.py

@@ -1,17 +1,26 @@
-from typing import Optional
+from typing import Any, Optional, Self, Union
 
 from pydantic import AnyUrl, BaseModel, ConfigDict
 
 
 class Link(BaseModel):
     href: AnyUrl
     rel: str
-    type: Optional[str] = None
+    type: str | None = None
     title: Optional[str] = None
     method: Optional[str] = None
+    headers: Optional[dict[str, Union[str, list[str]]]] = None
+    body: Any = None
 
     model_config = ConfigDict(extra="allow")
 
+    def model_dump_json(self: Self, *args, **kwargs) -> bytes:
+        # TODO: this isn't working as expected and we get nulls in the output
+        #       maybe need to override python dump too
+        # forcing the call to model_dump_json to exclude unset fields by default
+        kwargs["exclude_unset"] = kwargs.get("exclude_unset", True)
+        return super().model_dump_json(*args, **kwargs)
+
 
 class HTTPException(BaseModel):
     detail: str

src/stapi_fastapi/models/shared.py

@@ -0,0 +1,131 @@
+# Generic product router factory
+from __future__ import annotations
+
+from typing import Self
+
+from fastapi import APIRouter, HTTPException, Request, status
+from fastapi.encoders import jsonable_encoder
+from fastapi.responses import JSONResponse
+
+import stapi_fastapi
+from stapi_fastapi.constants import TYPE_GEOJSON, TYPE_JSON
+from stapi_fastapi.exceptions import ConstraintsException
+from stapi_fastapi.models.opportunity import (
+    OpportunityCollection,
+    OpportunityRequest,
+)
+from stapi_fastapi.models.product import Product
+from stapi_fastapi.models.shared import Link
+from stapi_fastapi.types.json_schema_model import JsonSchemaModel
+
+"""
+/products[MainRouter]/opportunities
+/products[MainRouter]/parameters
+/products[MainRouter]/order
+"""
+
+
+class ProductRouter(APIRouter):
+    def __init__(
+        self: Self,
+        product: Product,
+        root_router: stapi_fastapi.routers.RootRouter,
+        *args,
+        **kwargs,
+    ):
+        super().__init__(*args, **kwargs)
+        self.product = product
+        self.root_router = root_router
+
+        self.add_api_route(
+            path="",
+            endpoint=self.get_product,
+            name=f"{self.root_router.name}:{self.product.id}:get-product",
+            methods=["GET"],
+            summary="Retrieve this product",
+        )
+
+        self.add_api_route(
+            path="/opportunities",
+            endpoint=self.search_opportunities,
+            name=f"{self.root_router.name}:{self.product.id}:search-opportunities",
+            methods=["POST"],
+            summary="Search Opportunities for the product",
+        )
+
+        self.add_api_route(
+            path="/constraints",
+            endpoint=self.get_product_constraints,
+            name=f"{self.root_router.name}:{self.product.id}:get-constraints",
+            methods=["GET"],
+            summary="Get constraints for the product",
+        )
+
+        self.add_api_route(
+            path="/order",
+            endpoint=self.create_order,
+            name=f"{self.root_router.name}:{self.product.id}:create-order",
+            methods=["POST"],
+            summary="Create an order for the product",
+        )
+
+    def get_product(self, request: Request) -> Product:
+        return self.product.with_links(
+            links=[
+                Link(
+                    href=str(
+                        request.url_for(
+                            f"{self.root_router.name}:{self.product.id}:get-product",
+                        ),
+                    ),
+                    rel="self",
+                    type=TYPE_JSON,
+                ),
+            ],
+        )
+
+    async def search_opportunities(
+        self, search: OpportunityRequest, request: Request
+    ) -> OpportunityCollection:
+        """
+        Explore the opportunities available for a particular set of constraints
+        """
+        try:
+            opportunities = await self.product.backend.search_opportunities(
+                search, request
+            )
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+        return JSONResponse(
+            jsonable_encoder(OpportunityCollection(features=opportunities)),
+            media_type=TYPE_GEOJSON,
+        )
+
+    async def get_product_constraints(self: Self, request: Request) -> JsonSchemaModel:
+        """
+        Return supported constraints of a specific product
+        """
+        return {
+            "product.id": self.product.product.id,
+            "constraints": self.product.constraints,
+        }
+
+    async def create_order(
+        self, payload: OpportunityRequest, request: Request
+    ) -> JSONResponse:
+        """
+        Create a new order.
+        """
+        try:
+            order = await self.product.backend.create_order(payload, request)
+        except ConstraintsException as exc:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_ENTITY, detail=exc.detail)
+
+        location = self.root_router.generate_order_href(request, order.id)
+        order.links.append(Link(href=location, rel="self", type=TYPE_GEOJSON))
+        return JSONResponse(
+            jsonable_encoder(order, exclude_unset=True),
+            status.HTTP_201_CREATED,
+            {"Location": location},
+            TYPE_GEOJSON,
+        )