📝 Add docstrings to codex/implement-circuit-breaker-and-hygraph-client (#274)

Docstrings generation was requested by @shayancoin.

* #108 (comment)

The following files were modified:

* `backend/api/routes_sync.py`
* `backend/services/cache.py`
* `backend/services/circuit_breaker.py`
* `backend/services/hygraph_client.py`
* `backend/services/hygraph_service.py`

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

Author: coderabbitai[bot]

backend/api/routes_sync.py

@@ -178,10 +178,24 @@ async def hygraph_pull(
     db: Session = Depends(get_db),
 ) -> Dict[str, Any]:
     """
-    Admin pull:
-    - Auth via Bearer token (constant-time compare)
-    - Accepts "type" or "sync_type" + optional "page_size"
-    - Validates positive page_size and caps inside service (≤200)
+    Trigger an administrative Hygraph synchronization for the requested resource type.
+    
+    Accepts a JSON body with either "type" or "sync_type" (case-insensitive) set to one of: "materials", "modules", "systems", or "all". Optionally accepts "page_size" as a positive integer to request a specific page size (service enforces its own maximum).
+    
+    Parameters:
+    	body (dict): Request body that may contain:
+    		- "type" or "sync_type": the resource sync type to run.
+    		- "page_size" (optional): positive integer for page size.
+    	db (Session): Database session (injected).
+    
+    Returns:
+    	dict: {"ok": True, "data": counts} where `counts` maps resource types to processed counts.
+    	      If a circuit-breaker fallback is used, returns {"ok": True, "data": fallback_result, "cached": True}.
+    
+    Raises:
+    	HTTPException (400) if "page_size" is not a positive integer or if the type is unsupported.
+    	HTTPException (503) if the Hygraph circuit breaker is open and no fallback is available.
+    	HTTPException (500) on internal sync failures.
     """
     sync_type = str((body.get("type") or body.get("sync_type") or "")).lower().strip()
     page_size_raw = body.get("page_size")

backend/services/cache.py

@@ -24,16 +24,38 @@ class RedisCache:
     _memory_store: Dict[str, tuple[Any, Optional[float]]] = field(default_factory=dict, init=False, repr=False)
 
     def __post_init__(self) -> None:
+        """
+        Initialize the Redis client for this instance if the asyncio Redis library is available.
+        
+        If the optional asyncio Redis package is present, attempts to create a client from the configured URL with response decoding enabled and stores it on `self._client`; if client creation fails or the package is unavailable, `self._client` is left as `None`.
+        """
         if redis_asyncio is not None:
             try:
                 self._client = redis_asyncio.from_url(self.url, decode_responses=True)
             except Exception:
                 self._client = None
 
     def _prefixed(self, key: str) -> str:
+        """
+        Apply the namespace prefix to a key when a namespace is configured.
+        
+        Parameters:
+            key (str): The key to which the namespace prefix should be applied.
+        
+        Returns:
+            str: The namespaced key in the form `namespace:key` if `namespace` is non-empty, otherwise the original `key`.
+        """
         return f"{self.namespace}:{key}" if self.namespace else key
 
     async def get_json(self, key: str) -> Any | None:
+        """
+        Retrieve a JSON-decoded value for a namespaced key, preferring Redis and falling back to the in-memory store when configured.
+        
+        If a value is found in Redis but cannot be JSON-decoded, this method returns `None`. When using the in-memory fallback, expired entries are removed on access.
+        
+        Returns:
+            The decoded Python value if present and valid, `None` otherwise.
+        """
         full_key = self._prefixed(key)
         if self._client is not None:
             try:
@@ -57,6 +79,14 @@ async def get_json(self, key: str) -> Any | None:
         return value
 
     async def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None) -> None:
+        """
+        Store a JSON-serializable value under the namespaced key, persisting to Redis and optionally to the in-memory fallback with an optional TTL.
+        
+        Parameters:
+            key (str): The cache key (namespace will be applied).
+            value (Any): JSON-serializable value to store.
+            ttl (Optional[int]): Time-to-live in seconds; when provided, the in-memory fallback will expire the entry after this many seconds (relative to the current monotonic clock).
+        """
         full_key = self._prefixed(key)
         dumped = json.dumps(value)
         if self._client is not None:
@@ -70,4 +100,4 @@ async def set_json(self, key: str, value: Any, *, ttl: Optional[int] = None) ->
         expires_at = None
         if ttl is not None:
             expires_at = time.monotonic() + ttl
-        self._memory_store[full_key] = (value, expires_at)
+        self._memory_store[full_key] = (value, expires_at)

backend/services/circuit_breaker.py

@@ -14,6 +14,13 @@ class CircuitOpenError(RuntimeError):
     """Raised when the circuit breaker is OPEN and calls are blocked."""
 
     def __init__(self, message: str, fallback_result: Any | None = None) -> None:
+        """
+        Initialize the CircuitOpenError with an error message and an optional fallback result.
+        
+        Parameters:
+            message (str): Human-readable error message describing why the circuit is open.
+            fallback_result (Any | None): Optional value to be used as a fallback when the circuit blocks calls; stored on the exception as `fallback_result`.
+        """
         super().__init__(message)
         self.fallback_result = fallback_result
 
@@ -36,29 +43,57 @@ class CircuitBreaker:
     HALF_OPEN: str = "HALF_OPEN"
 
     def _transition_to_open(self) -> None:
+        """
+        Transition the circuit to OPEN state and reset internal counters.
+        
+        Sets the circuit state to OPEN, records the open timestamp from the configured time provider, and resets both failure_count and success_count to 0.
+        """
         self.state = self.OPEN
         self.opened_at = self.time_provider()
         self.failure_count = 0
         self.success_count = 0
 
     def _transition_to_half_open(self) -> None:
+        """
+        Transition the circuit to HALF_OPEN and reset timing and counters.
+        
+        Sets the breaker state to HALF_OPEN, clears the recorded open timestamp, and resets both failure and success counters to zero.
+        """
         self.state = self.HALF_OPEN
         self.opened_at = None
         self.failure_count = 0
         self.success_count = 0
 
     def _transition_to_closed(self) -> None:
+        """
+        Transition the circuit to CLOSED and reset timing and counters.
+        
+        Sets the breaker state to CLOSED, clears `opened_at`, and resets `failure_count` and `success_count` to 0 so the circuit treats subsequent calls as healthy.
+        """
         self.state = self.CLOSED
         self.opened_at = None
         self.failure_count = 0
         self.success_count = 0
 
     def _ready_for_half_open(self) -> bool:
+        """
+        Determine whether the circuit has been open long enough to move to HALF_OPEN.
+        
+        Returns:
+            True if `opened_at` is set and the elapsed time since it was set is greater than or equal to `recovery_timeout`, False otherwise.
+        """
         if self.opened_at is None:
             return False
         return (self.time_provider() - self.opened_at) >= self.recovery_timeout
 
     def _record_failure(self) -> None:
+        """
+        Record a failure and update the circuit breaker state accordingly.
+        
+        If the circuit is HALF_OPEN, transition it to OPEN immediately. Otherwise,
+        increment the consecutive failure count and transition to OPEN when that
+        count reaches or exceeds the configured failure_threshold.
+        """
         if self.state == self.HALF_OPEN:
             self._transition_to_open()
             return
@@ -67,6 +102,13 @@ def _record_failure(self) -> None:
             self._transition_to_open()
 
     def _record_success(self) -> None:
+        """
+        Record a successful call and update the circuit breaker state.
+        
+        If the circuit is HALF_OPEN, increments the consecutive success counter and closes the circuit when the
+        count reaches or exceeds `half_open_success_threshold`. If the circuit is OPEN (unexpected), transitions
+        proactively to CLOSED. Otherwise (CLOSED), resets the consecutive failure counter to zero.
+        """
         if self.state == self.HALF_OPEN:
             self.success_count += 1
             if self.success_count >= self.half_open_success_threshold:
@@ -85,7 +127,31 @@ def call(
         fallback: Optional[Callable[[], T]] = None,
         **kwargs: Any,
     ) -> T:
-        """Execute ``func`` guarding access through the circuit breaker."""
+        """
+        Guard execution of a callable using the circuit breaker and return its result.
+        
+        If the circuit is OPEN and not yet ready for HALF_OPEN, this method invokes the optional
+        `fallback` to obtain a fallback result and raises CircuitOpenError carrying that result.
+        If a call executed while in HALF_OPEN raises an exception, the circuit transitions to OPEN,
+        the optional `fallback` is invoked to obtain a fallback result, and a CircuitOpenError is
+        raised chained to the original exception. Exceptions raised outside HALF_OPEN are re-raised.
+        
+        Parameters:
+            func (Callable[..., T]): The callable to invoke when the circuit allows execution.
+            *args: Positional arguments forwarded to `func`.
+            fallback (Optional[Callable[[], T]]): Callable producing a fallback result when the
+                circuit blocks execution or when a HALF_OPEN call fails. If not provided, the
+                CircuitOpenError will carry `None` as its `fallback_result`.
+            **kwargs: Keyword arguments forwarded to `func`.
+        
+        Returns:
+            T: The result returned by `func` when execution succeeds.
+        
+        Raises:
+            CircuitOpenError: When the circuit is OPEN (and not ready for HALF_OPEN) or when a
+                HALF_OPEN call fails; contains the `fallback_result` returned by `fallback` (or
+                `None` if no fallback was provided).
+        """
 
         if self.state == self.OPEN:
             if self._ready_for_half_open():
@@ -105,4 +171,4 @@ def call(
             raise
         else:
             self._record_success()
-            return result
+            return result

backend/services/hygraph_client.py

@@ -12,6 +12,12 @@ class HygraphGraphQLError(RuntimeError):
     """Raised when Hygraph returns GraphQL errors."""
 
     def __init__(self, errors: Any) -> None:
+        """
+        Create a HygraphGraphQLError that wraps a GraphQL `errors` payload.
+        
+        Parameters:
+            errors: The GraphQL `errors` payload returned by Hygraph (commonly a list of error objects or a dict). Stored on the exception instance as the `errors` attribute.
+        """
         super().__init__("Hygraph GraphQL error")
         self.errors = errors
 
@@ -28,6 +34,19 @@ def __init__(
         breaker: Optional[CircuitBreaker] = None,
         client: Optional[httpx.Client] = None,
     ) -> None:
+        """
+        Initialize the Hygraph client with the GraphQL endpoint, optional authentication, HTTP client, and circuit breaker.
+        
+        Parameters:
+        	endpoint (str): Hygraph GraphQL endpoint URL; must be non-empty.
+        	token (str): Optional bearer token; when provided, an Authorization header is set.
+        	timeout (float): Timeout (seconds) for the created HTTPX client when no client is supplied.
+        	breaker (Optional[CircuitBreaker]): Circuit breaker instance to use; a default CircuitBreaker is created if omitted.
+        	client (Optional[httpx.Client]): Preconfigured HTTPX client to use instead of creating one.
+        
+        Raises:
+        	ValueError: If `endpoint` is empty or falsy.
+        """
         if not endpoint:
             raise ValueError("Hygraph endpoint must be configured")
         self._endpoint = endpoint
@@ -41,6 +60,12 @@ def __init__(
 
     @property
     def breaker(self) -> CircuitBreaker:
+        """
+        Expose the CircuitBreaker instance used by this client.
+        
+        Returns:
+            CircuitBreaker: The circuit breaker used to protect and control execution of remote requests.
+        """
         return self._breaker
 
     def execute(
@@ -50,9 +75,33 @@ def execute(
         *,
         fallback: Optional[Callable[[], Any]] = None,
     ) -> Dict[str, Any]:
-        """Run the GraphQL ``query`` through the circuit breaker."""
+        """
+        Execute the given GraphQL query via the client's circuit breaker and return the response data.
+        
+        Runs the query against the configured Hygraph endpoint, raising HygraphGraphQLError if the GraphQL response contains errors. If the response contains a `data` object it is returned as a dict; if `data` is missing or not a dict, an empty dict is returned. If the underlying circuit breaker is open, the CircuitOpenError raised by the breaker is propagated so callers can apply their fallback handling.
+        
+        Parameters:
+            query: The GraphQL query string to execute.
+            variables: Optional mapping of variables to include with the query.
+            fallback: Optional callable to be used by the circuit breaker when executing the request.
+        
+        Returns:
+            dict: The `data` payload from the GraphQL response, or an empty dict if no valid data is present.
+        
+        Raises:
+            HygraphGraphQLError: If the GraphQL response contains an `errors` payload.
+            CircuitOpenError: If the circuit breaker is open and rejects execution.
+        """
 
         def _request() -> Dict[str, Any]:
+            """
+            Perform the GraphQL POST to the configured Hygraph endpoint and return the `data` payload.
+            
+            Sends the provided `query` and `variables` as JSON, raises `HygraphGraphQLError` when the response contains GraphQL errors, and returns the `data` object from the response as a dict. If `data` is missing or not a dict, returns an empty dict.
+            
+            Returns:
+                Dict[str, Any]: The `data` object from the GraphQL response, or an empty dict if absent or malformed.
+            """
             response = self._client.post(
                 self._endpoint,
                 json={"query": query, "variables": variables or {}},
@@ -74,4 +123,9 @@ def _request() -> Dict[str, Any]:
             raise
 
     def close(self) -> None:
-        self._client.close()
+        """
+        Close the Hygraph client's underlying HTTP connection pool.
+        
+        Closes the internal httpx.Client to release network resources and sockets.
+        """
+        self._client.close()