📝 Add docstrings to codex/refactor-_process-to-use-own-sqlalchemy-session (#154)

Docstrings generation was requested by @shayancoin.

* #90 (comment)

The following files were modified:

* `backend/api/routes_sync.py`
* `backend/api/security.py`
* `backend/tests/test_sync_routes_metrics.py`

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

Author: coderabbitai[bot]

backend/api/routes_sync.py

@@ -129,6 +129,13 @@ async def hygraph_webhook(
         raise HTTPException(status_code=400, detail=_error_envelope("BAD_REQUEST", "Invalid JSON payload"))
 
     async def _process(event_id_local: Optional[str], body_sha_local: str) -> None:
+        """
+        Perform the background Hygraph sync: pull all content, update Prometheus metrics, and log success or failure.
+        
+        Parameters:
+            event_id_local (Optional[str]): Optional sync event identifier used for logging and correlation.
+            body_sha_local (str): SHA-256 of the webhook body used for correlation in logs and metrics.
+        """
         t0 = time.perf_counter()
         with _tracer.start_as_current_span("hygraph.pull_all") as pull_span:
             pull_span.set_attribute("retry.count", 0)

backend/api/security.py

@@ -15,7 +15,15 @@
 
 
 def _load_expected_write_token(settings: Settings) -> str:
-    """Resolve the configured API write token from settings or environment."""
+    """
+    Resolve the API write token from the provided settings or the API_WRITE_TOKEN environment variable.
+    
+    Parameters:
+        settings (Settings): Configuration object that may contain an `api_write_token` attribute.
+    
+    Returns:
+        str: The resolved token with surrounding whitespace removed; an empty string if no token is configured.
+    """
 
     token = getattr(settings, "api_write_token", None)
     if isinstance(token, str) and token.strip():
@@ -137,4 +145,4 @@ async def validate_hygraph_request(
         raise HTTPException(status_code=HTTP_401_UNAUTHORIZED, detail="Invalid signature")
     request.state.raw_body = body
     request.state.body_sha256 = hashlib.sha256(body).hexdigest()
-    return True
+    return True

backend/tests/test_sync_routes_metrics.py

@@ -17,6 +17,12 @@
 
 def _sig(secret: str, body: bytes) -> str:
     # x-hygraph-signature uses sha256=<hex>
+    """
+    Compute an HMAC-SHA256 signature for a request body using the given secret.
+    
+    Returns:
+        A string in the form "sha256=<hex digest>" containing the lowercase hexadecimal HMAC-SHA256 of the body (the secret is encoded as UTF-8).
+    """
     return "sha256=" + hmac.new(secret.encode("utf-8"), body, hashlib.sha256).hexdigest()
 
 
@@ -95,4 +101,4 @@ async def fake_pull_modules(db, page_size=None):
     )
     assert r.status_code == 200
     assert r.json()["ok"] is True
-    assert r.json()["data"]["processed"] == 5
+    assert r.json()["data"]["processed"] == 5