RootBackend protocol uses library types Result and Maybe instead of exceptions.

Author: Phil Varner

CHANGELOG.md

@@ -13,7 +13,7 @@ none
 
 ### Changed
 
-none
+- RootBackend protocol uses `returns` library types Result and Maybe instead of exceptions.
 
 ### Deprecated
 

bin/server.py

@@ -2,10 +2,11 @@
 from uuid import uuid4
 
 from fastapi import FastAPI, Request
+from returns.maybe import Maybe, Nothing
+from returns.result import Failure, Result, Success
 
 from stapi_fastapi.backends.product_backend import ProductBackend
 from stapi_fastapi.backends.root_backend import RootBackend
-from stapi_fastapi.exceptions import NotFoundException
 from stapi_fastapi.models.conformance import CORE
 from stapi_fastapi.models.opportunity import (
     Opportunity,
@@ -43,14 +44,16 @@ async def get_orders(self, request: Request) -> OrderCollection:
         """
         return OrderCollection(features=list(self._orders.values()))
 
-    async def get_order(self, order_id: str, request: Request) -> Order:
+    async def get_order(
+        self, order_id: str, request: Request
+    ) -> Result[Order, Maybe[Exception]]:
         """
         Show details for order with `order_id`.
         """
-        try:
-            return self._orders[order_id]
-        except KeyError:
-            raise NotFoundException()
+        if order := self._orders.get(order_id):
+            return Success(order)
+
+        return Failure(Nothing)
 
 
 class MockProductBackend(ProductBackend):

poetry.lock

@@ -14,6 +14,7 @@ fastapi = "^0.115.0"
 pydantic = "^2.9.2"
 geojson-pydantic = "^1.1.1"
 pygeofilter = "^0.2.4"
+returns = "^0.23.0"
 
 [tool.poetry.group.dev]
 optional = true

pyproject.toml

@@ -1,6 +1,8 @@
 from typing import Protocol
 
 from fastapi import Request
+from returns.maybe import Maybe
+from returns.result import Result
 
 from stapi_fastapi.models.order import Order, OrderCollection
 
@@ -12,11 +14,18 @@ async def get_orders(self, request: Request) -> OrderCollection:
         """
         ...
 
-    async def get_order(self, order_id: str, request: Request) -> Order:
+    async def get_order(
+        self, order_id: str, request: Request
+    ) -> Result[Order, Maybe[Exception]]:
         """
         Get details for order with `order_id`.
 
-        Backends must raise `stapi_fastapi.exceptions.NotFoundException`
-        if not found or access denied.
+        Should return returns.results.Success[Order] if order is found.
+
+        Should return returns.results.Failure[returns.maybe.Nothing] if the order is
+        not found or if access is denied. If there is an Exception associated with attempting to find the order,
+        then resturns.results.Failure[returns.maybe.Some[Exception]] should be returned.
+
+        Typically, a Failure[Nothing] will result in a 404 and Failure[Some[Exception]] will resulting in a 500.
         """
         ...

src/stapi_fastapi/backends/root_backend.py

@@ -1,10 +1,14 @@
+import logging
 from typing import Self
 
-from fastapi import APIRouter, Request
+from fastapi import APIRouter, HTTPException, Request, status
 from fastapi.datastructures import URL
+from returns.maybe import Some
+from returns.result import Failure, Success
 
 from stapi_fastapi.backends.root_backend import RootBackend
 from stapi_fastapi.constants import TYPE_GEOJSON, TYPE_JSON
+from stapi_fastapi.exceptions import NotFoundException
 from stapi_fastapi.models.conformance import CORE, Conformance
 from stapi_fastapi.models.order import Order, OrderCollection
 from stapi_fastapi.models.product import Product, ProductsCollection
@@ -152,9 +156,22 @@ async def get_order(self: Self, order_id: str, request: Request) -> Order:
         """
         Get details for order with `order_id`.
         """
-        order = await self.backend.get_order(order_id, request)
-        order.links.append(Link(href=str(request.url), rel="self", type=TYPE_GEOJSON))
-        return order
+        match await self.backend.get_order(order_id, request):
+            case Success(order):
+                order.links.append(
+                    Link(href=str(request.url), rel="self", type=TYPE_GEOJSON)
+                )
+                return order
+            case Failure(Some(e)):
+                logging.exception(
+                    f"An error occurred while retrieving order '{order_id}'", e
+                )
+                raise HTTPException(
+                    status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+                    detail="Error finding Order",
+                )
+            case _:
+                raise NotFoundException("Order not found")
 
     def add_product(self: Self, product: Product) -> None:
         # Give the include a prefix from the product router

src/stapi_fastapi/routers/root_router.py

@@ -2,10 +2,12 @@
 from uuid import uuid4
 
 from fastapi import Request
+from returns.maybe import Maybe, Nothing
+from returns.result import Failure, Result, Success
 
 from stapi_fastapi.backends.product_backend import ProductBackend
 from stapi_fastapi.backends.root_backend import RootBackend
-from stapi_fastapi.exceptions import ConstraintsException, NotFoundException
+from stapi_fastapi.exceptions import ConstraintsException
 from stapi_fastapi.models.opportunity import Opportunity, OpportunityRequest
 from stapi_fastapi.models.order import (
     Order,
@@ -31,14 +33,16 @@ async def get_orders(self, request: Request) -> OrderCollection:
         """
         return OrderCollection(features=list(self._orders.values()))
 
-    async def get_order(self, order_id: str, request: Request) -> Order:
+    async def get_order(
+        self, order_id: str, request: Request
+    ) -> Result[Order, Maybe[Exception]]:
         """
         Show details for order with `order_id`.
         """
-        try:
-            return self._orders[order_id]
-        except KeyError:
-            raise NotFoundException()
+        if order := self._orders.get(order_id):
+            return Success(order)
+
+        return Failure(Nothing)
 
 
 class MockProductBackend(ProductBackend):