recce-cloud 1.33.1__py3-none-any.whl → 1.34.0__py3-none-any.whl

recce_cloud/VERSION

@@ -1 +1 @@
-1.33.1
+1.34.0

recce_cloud/api/base.py

@@ -74,7 +74,7 @@ class BaseRecceCloudClient(ABC):
         self,
         branch: str,
         adapter_type: str,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
@@ -84,9 +84,9 @@ class BaseRecceCloudClient(ABC):
         Args:
             branch: Branch name
             adapter_type: DBT adapter type (e.g., 'postgres', 'snowflake', 'bigquery')
-            cr_number: Change request number (PR/MR number) for CR sessions
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
             commit_sha: Commit SHA (GitLab requires this)
-            session_type: Session type ("cr", "prod", "dev") - determines if cr_number is used
+            session_type: Session type ("pr", "prod", "dev") - determines if pr_number is used
 
         Returns:
             Dictionary containing:
@@ -113,15 +113,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def get_session_download_urls(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Get download URLs for artifacts from a session.
 
         Args:
-            cr_number: Change request number (PR/MR number) for CR sessions
-            session_type: Session type ("cr", "prod", "dev")
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod", "dev")
 
         Returns:
             Dictionary containing:
@@ -134,15 +134,15 @@ class BaseRecceCloudClient(ABC):
     @abstractmethod
     def delete_session(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Delete a session.
 
         Args:
-            cr_number: Change request number (PR/MR number) for CR sessions
-            session_type: Session type ("cr", "prod") - "prod" deletes base session
+            pr_number: Pull/Merge request number (PR/MR number) for PR sessions
+            session_type: Session type ("pr", "prod") - "prod" deletes base session
 
         Returns:
             Dictionary containing:

recce_cloud/api/client.py

@@ -42,6 +42,24 @@ class RecceCloudClient:
         }
         return requests.request(method, url, headers=headers, **kwargs)
 
+    def _safe_get_error_detail(self, response, default: str) -> str:
+        """Safely extract error detail from response JSON.
+
+        Some error responses may not have a valid JSON body (e.g., HTML error pages
+        from proxies), so we need to handle JSONDecodeError gracefully.
+
+        Args:
+            response: The HTTP response object.
+            default: Default message to return if JSON parsing fails.
+
+        Returns:
+            The error detail string from the response, or the default message.
+        """
+        try:
+            return response.json().get("detail", default)
+        except (json.JSONDecodeError, ValueError):
+            return default
+
     def _replace_localhost_with_docker_internal(self, url: str) -> str:
         """Convert localhost URLs to docker internal URLs if running in Docker."""
         if url is None:
@@ -75,7 +93,7 @@ class RecceCloudClient:
         api_url = f"{self.base_url_v2}/sessions/{session_id}"
         response = self._request("GET", api_url)
         if response.status_code == 403:
-            return {"status": "error", "message": response.json().get("detail")}
+            return {"status": "error", "message": self._safe_get_error_detail(response, "Permission denied")}
         if response.status_code != 200:
             raise RecceCloudException(
                 reason=response.text,
@@ -181,7 +199,7 @@ class RecceCloudClient:
         data = {"adapter_type": adapter_type}
         response = self._request("PATCH", api_url, json=data)
         if response.status_code == 403:
-            return {"status": "error", "message": response.json().get("detail")}
+            return {"status": "error", "message": self._safe_get_error_detail(response, "Permission denied")}
         if response.status_code != 200:
             raise RecceCloudException(
                 reason=response.text,
@@ -211,7 +229,7 @@ class RecceCloudClient:
             return True
         if response.status_code == 403:
             raise RecceCloudException(
-                reason=response.json().get("detail", "Permission denied"),
+                reason=self._safe_get_error_detail(response, "Permission denied"),
                 status_code=response.status_code,
             )
         if response.status_code == 404:
@@ -247,7 +265,7 @@ class RecceCloudClient:
             return response.json()
         if response.status_code == 403:
             raise RecceCloudException(
-                reason=response.json().get("detail", "Permission denied"),
+                reason=self._safe_get_error_detail(response, "Permission denied"),
                 status_code=response.status_code,
             )
         if response.status_code == 404:
@@ -488,7 +506,7 @@ class RecceCloudClient:
             )
         if response.status_code == 403:
             raise RecceCloudException(
-                reason=response.json().get("detail", "Permission denied"),
+                reason=self._safe_get_error_detail(response, "Permission denied"),
                 status_code=response.status_code,
             )
         if response.status_code not in [200, 201]:
@@ -503,6 +521,240 @@ class RecceCloudClient:
             return result["session"]
         return result
 
+    def check_prerequisites(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Dict[str, Any]:
+        """
+        Check prerequisites for data review generation.
+
+        This calls the backend API to verify:
+        1. Session exists and belongs to the project
+        2. Session has artifacts uploaded (adapter_type is set)
+        3. Base session exists for the project
+        4. Base session has artifacts uploaded
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to check.
+
+        Returns:
+            dict with:
+                - success: bool
+                - session_id: str
+                - session_name: str
+                - adapter_type: str or None
+                - has_base_session: bool
+                - base_session_has_artifacts: bool
+                - is_ready: bool
+                - reason: str or None (explains why not ready)
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = (
+            f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/check-prerequisites"
+        )
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            error_detail = "Session or project not found"
+            try:
+                error_detail = response.json().get("detail", error_detail)
+            except Exception:
+                pass
+            raise RecceCloudException(
+                reason=error_detail,
+                status_code=response.status_code,
+            )
+        if response.status_code == 400:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Bad request"),
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def generate_data_review(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        regenerate: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Trigger data review generation for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to generate review for.
+            regenerate: If True, regenerate even if a review already exists.
+
+        Returns:
+            dict with task_id if a new task was created, or empty if review already exists.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/recce_summary"
+        data = {"regenerate": regenerate}
+
+        response = self._request("POST", api_url, json=data)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Session not found",
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code == 400:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Bad request"),
+                status_code=response.status_code,
+            )
+        if response.status_code not in [200, 201, 202]:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def get_data_review(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get the existing data review for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to get review for.
+
+        Returns:
+            dict with session_id, session_name, summary (content), trace_id if found.
+            None if no review exists.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/recce_summary"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            # No review exists for this session
+            return None
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
+    def get_running_task(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """
+        Get the currently running task for a session.
+
+        Args:
+            org_id: Organization ID or slug.
+            project_id: Project ID or slug.
+            session_id: Session ID to check.
+
+        Returns:
+            dict with task_id and status if a task is running, None otherwise.
+
+        Raises:
+            RecceCloudException: If the API call fails.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/running_task"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            return None
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        data = response.json()
+        # Return None if no task is running
+        if data.get("task_id") is None:
+            return None
+        return data
+
+    def get_task_status(self, org_id: str, task_id: str) -> Dict[str, Any]:
+        """
+        Get the status of a task by ID.
+
+        Args:
+            org_id: Organization ID or slug.
+            task_id: Task ID to check.
+
+        Returns:
+            dict with id, command, status, created_at, started_at, finished_at, metadata.
+
+        Raises:
+            RecceCloudException: If the API call fails or task not found.
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/tasks/{task_id}/status"
+        response = self._request("GET", api_url)
+
+        if response.status_code == 404:
+            raise RecceCloudException(
+                reason="Task not found",
+                status_code=response.status_code,
+            )
+        if response.status_code == 403:
+            raise RecceCloudException(
+                reason=self._safe_get_error_detail(response, "Permission denied"),
+                status_code=response.status_code,
+            )
+        if response.status_code != 200:
+            raise RecceCloudException(
+                reason=response.text,
+                status_code=response.status_code,
+            )
+
+        return response.json()
+
 
 class ReportClient:
     """Client for fetching reports from Recce Cloud API."""

recce_cloud/api/github.py

@@ -26,7 +26,7 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         self,
         branch: str,
         adapter_type: str,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
@@ -36,9 +36,9 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         Args:
             branch: Branch name
             adapter_type: DBT adapter type
-            cr_number: PR number for pull request sessions (None for prod sessions)
+            pr_number: PR number for pull request sessions (None for prod sessions)
             commit_sha: Not used for GitHub (optional for compatibility)
-            session_type: Session type ("cr", "prod", "dev") - determines if pr_number is passed
+            session_type: Session type ("pr", "prod", "dev") - determines if pr_number is passed
 
         Returns:
             Dictionary containing session_id, manifest_upload_url, catalog_upload_url
@@ -50,10 +50,10 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
             "adapter_type": adapter_type,
         }
 
-        # Only include pr_number for "cr" type sessions
-        # For "prod" type, omit pr_number even if cr_number is detected
-        if session_type == "cr" and cr_number is not None:
-            payload["pr_number"] = cr_number
+        # Only include pr_number for "pr" type sessions
+        # For "prod" type, omit pr_number even if pr_number is detected
+        if session_type == "pr" and pr_number is not None:
+            payload["pr_number"] = pr_number
 
         return self._make_request("POST", url, json=payload)
 
@@ -78,15 +78,15 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
 
     def get_session_download_urls(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Get download URLs for artifacts from a GitHub session.
 
         Args:
-            cr_number: PR number for pull request sessions
-            session_type: Session type ("cr", "prod", "dev")
+            pr_number: PR number for pull request sessions
+            session_type: Session type ("pr", "prod", "dev")
 
         Returns:
             Dictionary containing session_id, manifest_url, catalog_url
@@ -99,23 +99,23 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         # For prod session, set base=true
         if session_type == "prod":
             params["base"] = "true"
-        # For CR session, include pr_number
-        elif session_type == "cr" and cr_number is not None:
-            params["pr_number"] = cr_number
+        # For PR session, include pr_number
+        elif session_type == "pr" and pr_number is not None:
+            params["pr_number"] = pr_number
 
         return self._make_request("GET", url, params=params)
 
     def delete_session(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Delete a GitHub PR/base session.
 
         Args:
-            cr_number: PR number for pull request sessions
-            session_type: Session type ("cr", "prod") - "prod" deletes base session
+            pr_number: PR number for pull request sessions
+            session_type: Session type ("pr", "prod") - "prod" deletes base session
 
         Returns:
             Dictionary containing session_id of deleted session
@@ -128,8 +128,8 @@ class GitHubRecceCloudClient(BaseRecceCloudClient):
         # For prod session, set base=true
         if session_type == "prod":
             params["base"] = "true"
-        # For CR session, include pr_number
-        elif session_type == "cr" and cr_number is not None:
-            params["pr_number"] = cr_number
+        # For PR session, include pr_number
+        elif session_type == "pr" and pr_number is not None:
+            params["pr_number"] = pr_number
 
         return self._make_request("DELETE", url, params=params)

recce_cloud/api/gitlab.py

@@ -28,7 +28,7 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
         self,
         branch: str,
         adapter_type: str,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         commit_sha: Optional[str] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
@@ -38,9 +38,9 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
         Args:
             branch: Branch name
             adapter_type: DBT adapter type
-            cr_number: MR IID for merge request sessions (None for prod sessions)
+            pr_number: MR IID for merge request sessions (None for prod sessions)
             commit_sha: Commit SHA (required for GitLab)
-            session_type: Session type ("cr", "prod", "dev") - determines if mr_iid is passed
+            session_type: Session type ("pr", "prod", "dev") - determines if mr_iid is passed
 
         Returns:
             Dictionary containing session_id, manifest_upload_url, catalog_upload_url
@@ -54,10 +54,10 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
             "repository_url": self.repository_url,
         }
 
-        # Only include mr_iid for "cr" type sessions
-        # For "prod" type, omit mr_iid even if cr_number is detected
-        if session_type == "cr" and cr_number is not None:
-            payload["mr_iid"] = cr_number
+        # Only include mr_iid for "pr" type sessions
+        # For "prod" type, omit mr_iid even if pr_number is detected
+        if session_type == "pr" and pr_number is not None:
+            payload["mr_iid"] = pr_number
 
         return self._make_request("POST", url, json=payload)
 
@@ -83,15 +83,15 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
 
     def get_session_download_urls(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Get download URLs for artifacts from a GitLab session.
 
         Args:
-            cr_number: MR IID for merge request sessions
-            session_type: Session type ("cr", "prod", "dev")
+            pr_number: MR IID for merge request sessions
+            session_type: Session type ("pr", "prod", "dev")
 
         Returns:
             Dictionary containing session_id, manifest_url, catalog_url
@@ -104,23 +104,23 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
         # For prod session, set base=true
         if session_type == "prod":
             params["base"] = "true"
-        # For CR session, include mr_iid
-        elif session_type == "cr" and cr_number is not None:
-            params["mr_iid"] = cr_number
+        # For PR session, include mr_iid
+        elif session_type == "pr" and pr_number is not None:
+            params["mr_iid"] = pr_number
 
         return self._make_request("GET", url, params=params)
 
     def delete_session(
         self,
-        cr_number: Optional[int] = None,
+        pr_number: Optional[int] = None,
         session_type: Optional[str] = None,
     ) -> Dict:
         """
         Delete a GitLab MR/base session.
 
         Args:
-            cr_number: MR IID for merge request sessions
-            session_type: Session type ("cr", "prod") - "prod" deletes base session
+            pr_number: MR IID for merge request sessions
+            session_type: Session type ("pr", "prod") - "prod" deletes base session
 
         Returns:
             Dictionary containing session_id of deleted session
@@ -133,8 +133,8 @@ class GitLabRecceCloudClient(BaseRecceCloudClient):
         # For prod session, set base=true
         if session_type == "prod":
             params["base"] = "true"
-        # For CR session, include mr_iid
-        elif session_type == "cr" and cr_number is not None:
-            params["mr_iid"] = cr_number
+        # For PR session, include mr_iid
+        elif session_type == "pr" and pr_number is not None:
+            params["mr_iid"] = pr_number
 
         return self._make_request("DELETE", url, params=params)

recce_cloud/ci_providers/base.py

@@ -13,9 +13,9 @@ class CIInfo:
     """Information extracted from CI environment."""
 
     platform: Optional[str] = None  # "github-actions", "gitlab-ci", etc.
-    cr_number: Optional[int] = None  # Change request number (PR/MR)
-    cr_url: Optional[str] = None  # Change request URL (for session linking)
-    session_type: Optional[str] = None  # "cr", "prod", "dev"
+    pr_number: Optional[int] = None  # Pull/Merge request number (PR/MR)
+    pr_url: Optional[str] = None  # Pull/Merge request URL (for session linking)
+    session_type: Optional[str] = None  # "pr", "prod", "dev"
     commit_sha: Optional[str] = None  # Full commit SHA
     base_branch: Optional[str] = None  # Target/base branch
     source_branch: Optional[str] = None  # Source/head branch
@@ -64,19 +64,19 @@ class BaseCIProvider(ABC):
             return None
 
     @staticmethod
-    def determine_session_type(cr_number: Optional[int], source_branch: Optional[str]) -> str:
+    def determine_session_type(pr_number: Optional[int], source_branch: Optional[str]) -> str:
         """
         Determine session type based on context.
 
         Args:
-            cr_number: Change request number (PR/MR)
+            pr_number: Pull/Merge request number (PR/MR)
             source_branch: Source branch name
 
         Returns:
-            Session type: "cr", "prod", or "dev"
+            Session type: "pr", "prod", or "dev"
         """
-        if cr_number is not None:
-            return "cr"
+        if pr_number is not None:
+            return "pr"
         if source_branch in ["main", "master"]:
             return "prod"
         return "dev"