📝 Add docstrings to feat/pricing-endpoint-cache (#617)

Docstrings generation was requested by @shayancoin.

* #616 (comment)

The following files were modified:

* `backend/api/deps.py`
* `backend/api/graphql.py`
* `backend/api/routes_pricing.py`

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: coderabbitai[bot]

backend/api/deps.py

@@ -17,19 +17,48 @@
 
 class RedisLike(Protocol):
     async def get(self, key: str) -> Optional[str]:
+        """
+        Retrieve a value by key from the in-memory store, respecting expiry.
+        
+        Returns:
+            The stored string value for `key`, or `None` if the key is missing or has expired.
+        """
         ...
 
     async def set(self, key: str, value: str, ex: Optional[int] = None) -> None:
+        """
+        Store a string value under the given key, optionally expiring after a number of seconds.
+        
+        Parameters:
+            key (str): Key under which to store the value.
+            value (str): String value to store.
+            ex (Optional[int]): Expiration time in seconds; if provided, the key will be removed after this many seconds. Existing values for the key are overwritten.
+        """
         ...
 
 
 class _InMemoryRedis:
     """Minimal in-memory Redis replacement used when redis-py asyncio is unavailable."""
 
     def __init__(self) -> None:
+        """
+        Initialize internal storage for the in-memory Redis replacement.
+        
+        Creates the `_store` dictionary that maps keys (str) to tuples of `(value, expires_at)`,
+        where `value` is the stored string and `expires_at` is a Unix timestamp (float) when the
+        entry expires or `None` if it does not expire.
+        """
         self._store: dict[str, tuple[str, Optional[float]]] = {}
 
     async def get(self, key: str) -> Optional[str]:
+        """
+        Retrieve the string value stored for the given key if it exists and has not expired.
+        
+        If the key is missing or its expiry time has passed, the key is removed from the in-memory store and `None` is returned.
+        
+        Returns:
+            The stored `str` value for `key`, or `None` if the key does not exist or is expired.
+        """
         payload = self._store.get(key)
         if payload is None:
             return None
@@ -40,6 +69,14 @@ async def get(self, key: str) -> Optional[str]:
         return value
 
     async def set(self, key: str, value: str, ex: Optional[int] = None) -> None:
+        """
+        Store a string value under a key with an optional TTL in seconds.
+        
+        Parameters:
+            key (str): The key to store the value under.
+            value (str): The string value to store.
+            ex (Optional[int]): Time-to-live in seconds; if provided, the key expires after this many seconds.
+        """
         expires_at = time.monotonic() + ex if ex is not None else None
         self._store[key] = (value, expires_at)
 
@@ -49,7 +86,15 @@ async def set(self, key: str, value: str, ex: Optional[int] = None) -> None:
 
 
 async def get_redis(settings: Settings = Depends(get_settings)) -> RedisLike:
-    """Return a Redis client (asyncio) or in-memory fallback."""
+    """
+    Provide a shared Redis-like client: use the asyncio Redis client when available, otherwise use the in-memory fallback.
+    
+    Parameters:
+        settings (Settings): Application settings used to obtain `redis_url` when lazily initializing the asyncio Redis client.
+    
+    Returns:
+        RedisLike: The module-level Redis-like client (an initialized asyncio Redis client if available, otherwise the in-memory fallback).
+    """
 
     global _redis_client
 
@@ -65,4 +110,4 @@ async def get_redis(settings: Settings = Depends(get_settings)) -> RedisLike:
     return _redis_client
 
 
-__all__ = ["get_redis", "RedisLike"]
+__all__ = ["get_redis", "RedisLike"]

backend/api/graphql.py

@@ -25,6 +25,14 @@ class PriceQuote:
 
 
 def _to_graphql(response: PriceResponse) -> PriceQuote:
+    """
+    Convert a backend PriceResponse into a GraphQL PriceQuote.
+    
+    Constructs a PriceQuote with total_cents from the response and a nested PriceBreakdown populated from the response.breakdown keys: "base", "finish", "hardware", and "countertop".
+    
+    Returns:
+        PriceQuote: GraphQL PriceQuote with mapped `total_cents` and `breakdown`.
+    """
     breakdown = response.breakdown
     return PriceQuote(
         total_cents=response.total_cents,
@@ -47,6 +55,20 @@ async def price_quote(
         hardware: str,
         countertop: str,
     ) -> PriceQuote:
+        """
+        Resolve a price quote for a product configuration specified by the provided attributes.
+        
+        Builds a price request from the provided elevation, finish, hardware, and countertop identifiers, queries the pricing backend, and returns the result as a GraphQL PriceQuote.
+        
+        Parameters:
+            elevation (str): Identifier for the product elevation/profile.
+            finish (str): Identifier for the surface finish option.
+            hardware (str): Identifier for the hardware option.
+            countertop (str): Identifier for the countertop option.
+        
+        Returns:
+            PriceQuote: GraphQL representation of the computed price, including `total_cents` and a `breakdown` of cost components.
+        """
         request = PriceRequest(
             elevation=elevation,
             finish=finish,
@@ -68,4 +90,4 @@ async def price_quote(
 )
 
 
-__all__ = ["graphql_app", "schema"]
+__all__ = ["graphql_app", "schema"]

backend/api/routes_pricing.py

@@ -48,13 +48,38 @@ class PriceResponse(BaseModel):
 
 
 def _lookup(mapping: dict[str, int], key: str, field: str) -> int:
+    """
+    Retrieve the integer value associated with `key` in `mapping`, or raise an HTTP 422 error if the key is not present.
+    
+    Parameters:
+        mapping (dict[str, int]): Lookup mapping from keys to integer values (e.g., price components in cents).
+        key (str): Key to look up in the mapping.
+        field (str): Human-readable field name used in the error detail when `key` is unsupported.
+    
+    Returns:
+        int: The value found for `key`.
+    
+    Raises:
+        HTTPException: With status code 422 and detail "Unsupported {field}: {key}" when `key` is not in `mapping`.
+    """
     try:
         return mapping[key]
     except KeyError as exc:  # pragma: no cover - defensive guard
         raise HTTPException(status_code=422, detail=f"Unsupported {field}: {key}") from exc
 
 
 async def compute_price_quote(request: PriceRequest, redis: RedisLike) -> PriceResponse:
+    """
+    Compute a price quote for the given selection and use a short-lived micro-cache.
+    
+    Attempts to return a cached PriceResponse keyed by the request fields. On cache read errors the function treats the cache as a miss; after computing the quote it will try to write the result to the cache but will ignore cache write failures so they do not affect the response.
+    
+    Returns:
+        PriceResponse: The total price in cents and a breakdown of the component prices.
+    
+    Raises:
+        HTTPException: 422 if any provided option (elevation, finish, hardware, or countertop) is not supported.
+    """
     cache_key = f"price:{request.elevation}:{request.finish}:{request.hardware}:{request.countertop}"
 
     cached = None
@@ -95,4 +120,13 @@ async def quote(
     request: PriceRequest,
     redis: RedisLike = Depends(get_redis),
 ) -> PriceResponse:
-    return await compute_price_quote(request, redis)
+    """
+    Generate a price quote for the given PriceRequest, using Redis for micro-caching.
+    
+    Parameters:
+        request (PriceRequest): The requested configuration with fields `elevation`, `finish`, `hardware`, and `countertop`.
+    
+    Returns:
+        PriceResponse: The computed quote containing `total_cents` and a `breakdown` mapping of component prices.
+    """
+    return await compute_price_quote(request, redis)