various cleanup and refinements

Author: jkeifer

src/stapi_fastapi/__init__.py

@@ -0,0 +1,21 @@
+from .backends import ProductBackend, RootBackend
+from .models import (
+    Link,
+    OpportunityPropertiesBase,
+    Product,
+    Provider,
+    ProviderRole,
+)
+from .routers import ProductRouter, RootRouter
+
+__all__ = [
+    "Link",
+    "OpportunityPropertiesBase",
+    "Product",
+    "ProductBackend",
+    "ProductRouter",
+    "Provider",
+    "ProviderRole",
+    "RootBackend",
+    "RootRouter",
+]

src/stapi_fastapi/backends/__init__.py

@@ -0,0 +1,7 @@
+from .product_backend import ProductBackend
+from .root_backend import RootBackend
+
+__all__ = [
+    "ProductBackend",
+    "RootBackend",
+]

src/stapi_fastapi/backends/product_backend.py

@@ -4,15 +4,15 @@
 
 from fastapi import Request
 
-import stapi_fastapi
 from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
 from stapi_fastapi.models.order import Order
+from stapi_fastapi.models.product import Product
 
 
 class ProductBackend(Protocol):
     async def search_opportunities(
         self,
-        product: stapi_fastapi.models.product.Product,
+        product: Product,
         search: OpportunityRequest,
         request: Request,
     ) -> list[Opportunity]:
@@ -26,7 +26,7 @@ async def search_opportunities(
 
     async def create_order(
         self,
-        product: stapi_fastapi.models.product.Product,
+        product: Product,
         search: OpportunityRequest,
         request: Request,
     ) -> Order:

src/stapi_fastapi/models/__init__.py

@@ -0,0 +1,11 @@
+from .opportunity import OpportunityPropertiesBase
+from .product import Product, Provider, ProviderRole
+from .shared import Link
+
+__all__ = [
+    "Link",
+    "OpportunityPropertiesBase",
+    "Product",
+    "Provider",
+    "ProviderRole",
+]

src/stapi_fastapi/models/opportunity.py

@@ -1,4 +1,4 @@
-from typing import Literal, Optional
+from typing import Literal, TypeVar
 
 from geojson_pydantic import Feature, FeatureCollection
 from geojson_pydantic.geometries import Geometry
@@ -10,7 +10,7 @@
 
 
 # Copied and modified from https://github.com/stac-utils/stac-pydantic/blob/main/stac_pydantic/item.py#L11
-class OpportunityProperties(BaseModel):
+class OpportunityPropertiesBase(BaseModel):
     datetime: DatetimeInterval
     model_config = ConfigDict(extra="allow")
 
@@ -19,15 +19,18 @@ class OpportunityRequest(BaseModel):
     datetime: DatetimeInterval
     geometry: Geometry
     # TODO: validate the CQL2 filter?
-    filter: Optional[CQL2Filter] = None
+    filter: CQL2Filter | None = None
     model_config = ConfigDict(strict=True)
 
 
-# GENERIC: Each product needs an opportunity model (constraints/parameters)
-class Opportunity(Feature[Geometry, OpportunityProperties]):
+G = TypeVar("G", bound=Geometry)
+P = TypeVar("P", bound=OpportunityPropertiesBase)
+
+
+class Opportunity(Feature[G, P]):
     type: Literal["Feature"] = "Feature"
     links: list[Link] = []
 
 
-class OpportunityCollection(FeatureCollection[Opportunity]):
+class OpportunityCollection(FeatureCollection[Opportunity[G, P]]):
     type: Literal["FeatureCollection"] = "FeatureCollection"

src/stapi_fastapi/models/order.py

@@ -1,12 +1,19 @@
-from typing import Literal
+from typing import Literal, TypeVar
 
 from geojson_pydantic import Feature
 from geojson_pydantic.geometries import Geometry
+from pydantic import StrictInt, StrictStr
 
-from stapi_fastapi.models.opportunity import OpportunityProperties
+from stapi_fastapi.models.opportunity import OpportunityPropertiesBase
 from stapi_fastapi.models.shared import Link
 
+G = TypeVar("G", bound=Geometry)
+P = TypeVar("P", bound=OpportunityPropertiesBase)
 
-class Order(Feature[Geometry, OpportunityProperties]):
+
+class Order(Feature[G, P]):
+    # We need to enforce that orders have an id defined, as that is required to
+    # retrieve them via the API
+    id: StrictInt | StrictStr  # type: ignore
     type: Literal["Feature"] = "Feature"
     links: list[Link]

src/stapi_fastapi/models/product.py

@@ -2,14 +2,16 @@
 
 from copy import deepcopy
 from enum import Enum
-from typing import Literal, Optional, Self
+from typing import TYPE_CHECKING, 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.opportunity import OpportunityPropertiesBase
 from stapi_fastapi.models.shared import Link
 
+if TYPE_CHECKING:
+    from stapi_fastapi.backends.product_backend import ProductBackend
+
 
 class ProviderRole(str, Enum):
     licensor = "licensor"
@@ -24,6 +26,11 @@ class Provider(BaseModel):
     roles: list[ProviderRole]
     url: AnyHttpUrl
 
+    # redefining init is a hack to get str type to validate for `url`,
+    # as str is ultimately coerced into an AnyHttpUrl automatically anyway
+    def __init__(self, url: AnyHttpUrl | str, **kwargs):
+        super().__init__(url=url, **kwargs)
+
 
 class Product(BaseModel):
     type_: Literal["Product"] = Field(default="Product", alias="type")
@@ -37,14 +44,14 @@ class Product(BaseModel):
     links: list[Link]
 
     # we don't want to include these in the model fields
-    _constraints: type[OpportunityProperties]
+    _constraints: type[OpportunityPropertiesBase]
     _backend: ProductBackend
 
     def __init__(
-        self: Self,
+        self,
         *args,
         backend: ProductBackend,
-        constraints: type[OpportunityProperties],
+        constraints: type[OpportunityPropertiesBase],
         **kwargs,
     ) -> None:
         super().__init__(*args, **kwargs)
@@ -56,7 +63,7 @@ def backend(self: Self) -> ProductBackend:
         return self._backend
 
     @property
-    def constraints(self: Self) -> type[OpportunityProperties]:
+    def constraints(self: Self) -> type[OpportunityPropertiesBase]:
         return self._constraints
 
     def with_links(self: Self, links: list[Link] | None = None) -> Self:

src/stapi_fastapi/models/shared.py

@@ -14,7 +14,12 @@ class Link(BaseModel):
 
     model_config = ConfigDict(extra="allow")
 
-    def model_dump_json(self: Self, *args, **kwargs) -> bytes:
+    # redefining init is a hack to get str type to validate for `href`,
+    # as str is ultimately coerced into an AnyUrl automatically anyway
+    def __init__(self, href: AnyUrl | str, **kwargs):
+        super().__init__(href=href, **kwargs)
+
+    def model_dump_json(self: Self, *args, **kwargs) -> str:
         # 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

src/stapi_fastapi/routers/__init__.py

@@ -0,0 +1,7 @@
+from .product_router import ProductRouter
+from .root_router import RootRouter
+
+__all__ = [
+    "ProductRouter",
+    "RootRouter",
+]

src/stapi_fastapi/routers/product_router.py

@@ -1,38 +1,32 @@
-# Generic product router factory
 from __future__ import annotations
 
-from typing import Self
+from typing import TYPE_CHECKING, 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.order import Order
 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
-"""
+if TYPE_CHECKING:
+    from stapi_fastapi.routers import RootRouter
 
 
 class ProductRouter(APIRouter):
     def __init__(
-        self: Self,
+        self,
         product: Product,
-        root_router: stapi_fastapi.routers.RootRouter,
+        root_router: RootRouter,
         *args,
         **kwargs,
-    ):
+    ) -> None:
         super().__init__(*args, **kwargs)
         self.product = product
         self.root_router = root_router
@@ -50,6 +44,13 @@ def __init__(
             endpoint=self.search_opportunities,
             name=f"{self.root_router.name}:{self.product.id}:search-opportunities",
             methods=["POST"],
+            responses={
+                200: {
+                    "content": {
+                        "TYPE_GEOJSON": {},
+                    },
+                }
+            },
             summary="Search Opportunities for the product",
         )
 
@@ -66,6 +67,13 @@ def __init__(
             endpoint=self.create_order,
             name=f"{self.root_router.name}:{self.product.id}:create-order",
             methods=["POST"],
+            responses={
+                201: {
+                    "content": {
+                        "TYPE_GEOJSON": {},
+                    },
+                }
+            },
             summary="Create an order for the product",
         )
 
@@ -92,37 +100,33 @@ async def search_opportunities(
         """
         try:
             opportunities = await self.product.backend.search_opportunities(
-                search, request
+                self.product, 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,
-        )
+        return OpportunityCollection(features=opportunities)
 
-    async def get_product_constraints(self: Self, request: Request) -> JsonSchemaModel:
+    async def get_product_constraints(self: Self) -> JsonSchemaModel:
         """
         Return supported constraints of a specific product
         """
         return self.product.constraints
 
     async def create_order(
         self, payload: OpportunityRequest, request: Request
-    ) -> JSONResponse:
+    ) -> Order:
         """
         Create a new order.
         """
         try:
-            order = await self.product.backend.create_order(payload, request)
+            order = await self.product.backend.create_order(
+                self.product,
+                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,
-        )
+        order.links.append(Link(href=str(location), rel="self", type=TYPE_GEOJSON))
+        return order