recce-nightly 1.10.0.20250625__py3-none-any.whl → 1.30.0.20251221__py3-none-any.whl

recce/util/cloud/check_events.py

@@ -0,0 +1,190 @@
+"""
+Recce Cloud API client for check event operations.
+
+This module provides methods for managing check events (timeline/conversation) in Recce Cloud,
+including CRUD operations for comments and retrieving state change events.
+"""
+
+from typing import Dict, List
+
+from recce.util.cloud.base import CloudBase
+
+
+class CheckEventsCloud(CloudBase):
+    """
+    Client for Recce Cloud check event operations.
+
+    Provides methods to list, create, update, and delete check events
+    (comments and state changes) within Recce Cloud sessions.
+
+    Examples:
+        >>> client = CheckEventsCloud(token="your-api-token")
+        >>> events = client.list_events(
+        ...     org_id="org123",
+        ...     project_id="proj456",
+        ...     session_id="sess789",
+        ...     check_id="check001"
+        ... )
+    """
+
+    def _build_events_url(self, org_id: str, project_id: str, session_id: str, check_id: str) -> str:
+        """Build the base URL for check events endpoints."""
+        return f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks/{check_id}/events"
+
+    def list_events(self, org_id: str, project_id: str, session_id: str, check_id: str) -> List[Dict]:
+        """
+        List all events for a check in chronological order.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+
+        Returns:
+            List of event dictionaries
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> events = client.list_events("org123", "proj456", "sess789", "check001")
+            >>> for event in events:
+            ...     print(f"{event['event_type']}: {event['content']}")
+        """
+        api_url = self._build_events_url(org_id, project_id, session_id, check_id)
+        query_params = {"include_deleted": True}
+        response = self._request("GET", api_url, params=query_params)
+
+        self._raise_for_status(
+            response,
+            "Failed to list check events from Recce Cloud.",
+        )
+
+        data = response.json()
+        # Response is wrapped: {"events": [...]}
+        return data.get("events", [])
+
+    def get_event(self, org_id: str, project_id: str, session_id: str, check_id: str, event_id: str) -> Dict:
+        """
+        Get a specific event by ID.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+            event_id: Event ID
+
+        Returns:
+            Event dictionary
+
+        Raises:
+            RecceCloudException: If the request fails or event not found
+        """
+        api_url = f"{self._build_events_url(org_id, project_id, session_id, check_id)}/{event_id}"
+        response = self._request("GET", api_url)
+
+        self._raise_for_status(
+            response,
+            f"Failed to get check event {event_id} from Recce Cloud.",
+        )
+
+        data = response.json()
+        # Response is wrapped: {"event": {...}}
+        return data.get("event", {})
+
+    def create_comment(self, org_id: str, project_id: str, session_id: str, check_id: str, content: str) -> Dict:
+        """
+        Create a new comment on a check.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+            content: Comment content (plain text or markdown)
+
+        Returns:
+            Created event dictionary
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> event = client.create_comment(
+            ...     "org123", "proj456", "sess789", "check001",
+            ...     "This looks good to me!"
+            ... )
+            >>> print(f"Created comment with ID: {event['id']}")
+        """
+        api_url = self._build_events_url(org_id, project_id, session_id, check_id)
+        response = self._request("POST", api_url, json={"content": content})
+
+        self._raise_for_status(
+            response,
+            "Failed to create comment in Recce Cloud.",
+        )
+
+        data = response.json()
+        # Response is wrapped: {"event": {...}}
+        return data.get("event", {})
+
+    def update_comment(
+        self, org_id: str, project_id: str, session_id: str, check_id: str, event_id: str, content: str
+    ) -> Dict:
+        """
+        Update an existing comment.
+
+        Only the author or an admin can update a comment.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+            event_id: Event ID of the comment to update
+            content: New comment content
+
+        Returns:
+            Updated event dictionary
+
+        Raises:
+            RecceCloudException: If the request fails or user is not authorized
+        """
+        api_url = f"{self._build_events_url(org_id, project_id, session_id, check_id)}/{event_id}"
+        response = self._request("PATCH", api_url, json={"content": content})
+
+        self._raise_for_status(
+            response,
+            f"Failed to update comment {event_id} in Recce Cloud.",
+        )
+
+        data = response.json()
+        # Response is wrapped: {"event": {...}}
+        return data.get("event", {})
+
+    def delete_comment(self, org_id: str, project_id: str, session_id: str, check_id: str, event_id: str) -> None:
+        """
+        Delete a comment (soft delete).
+
+        Only the author or an admin can delete a comment.
+        The comment will be marked as deleted but remain in the timeline.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+            event_id: Event ID of the comment to delete
+
+        Raises:
+            RecceCloudException: If the request fails or user is not authorized
+        """
+        api_url = f"{self._build_events_url(org_id, project_id, session_id, check_id)}/{event_id}"
+        response = self._request("DELETE", api_url)
+
+        self._raise_for_status(
+            response,
+            f"Failed to delete comment {event_id} in Recce Cloud.",
+        )

recce/util/cloud/checks.py

@@ -0,0 +1,242 @@
+"""
+Recce Cloud API client for check operations.
+
+This module provides methods for managing checks (validation operations) in Recce Cloud,
+including CRUD operations for checks within sessions.
+"""
+
+from typing import Dict, List
+
+from recce.util.cloud.base import CloudBase
+
+
+class ChecksCloud(CloudBase):
+    """
+    Client for Recce Cloud check operations.
+
+    Provides methods to list, create, retrieve, update, and delete checks
+    within Recce Cloud sessions.
+
+    Examples:
+        >>> client = ChecksCloud(token="your-api-token")
+        >>> checks = client.list_checks(org_id="org123", project_id="proj456", session_id="sess789")
+        >>> check = client.get_check(org_id="org123", project_id="proj456",
+        ...                          session_id="sess789", check_id="check001")
+    """
+
+    def list_checks(self, org_id: str, project_id: str, session_id: str) -> List[Dict]:
+        """
+        List all checks in a session.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+
+        Returns:
+            List of check dictionaries
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> checks = client.list_checks("org123", "proj456", "sess789")
+            >>> print(f"Found {len(checks)} checks")
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks"
+        response = self._request("GET", api_url)
+
+        self._raise_for_status(
+            response,
+            "Failed to list checks from Recce Cloud.",
+        )
+
+        data = response.json()
+        return data.get("checks", [])
+
+    def create_check(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        check_data: Dict,
+    ) -> Dict:
+        """
+        Create a new check in a session.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_data: Check data to create (should include check type, params, etc.)
+
+        Returns:
+            Created check dictionary
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> check_data = {
+            ...     "name": "Schema Check",
+            ...     "type": "schema_diff",
+            ...     "params": {"model": "customers"}
+            ... }
+            >>> check = client.create_check("org123", "proj456", "sess789", check_data)
+            >>> print(f"Created check with ID: {check['id']}")
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks"
+        response = self._request("POST", api_url, json=check_data)
+
+        self._raise_for_status(
+            response,
+            "Failed to create check in Recce Cloud.",
+        )
+        data = response.json()
+        return data.get("check")
+
+    def get_check(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        check_id: str,
+    ) -> Dict:
+        """
+        Get a specific check by ID.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+
+        Returns:
+            Check dictionary
+
+        Raises:
+            RecceCloudException: If the request fails or check not found
+
+        Example:
+            >>> check = client.get_check("org123", "proj456", "sess789", "check001")
+            >>> print(f"Check name: {check['name']}")
+            >>> print(f"Check status: {check['status']}")
+        """
+        api_url = (
+            f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks/{check_id}"
+        )
+        response = self._request("GET", api_url)
+
+        self._raise_for_status(
+            response,
+            f"Failed to get check {check_id} from Recce Cloud.",
+        )
+
+        data = response.json()
+        return data.get("check", {})
+
+    def update_check(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        check_id: str,
+        check_data: Dict,
+    ) -> Dict:
+        """
+        Update an existing check.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+            check_data: Updated check data (partial updates supported)
+
+        Returns:
+            Updated check dictionary
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> update_data = {
+            ...     "status": "approved",
+            ...     "notes": "Validated successfully"
+            ... }
+            >>> check = client.update_check("org123", "proj456", "sess789", "check001", update_data)
+            >>> print(f"Updated check status: {check['status']}")
+        """
+        api_url = (
+            f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks/{check_id}"
+        )
+        response = self._request("PATCH", api_url, json=check_data)
+
+        self._raise_for_status(
+            response,
+            f"Failed to update check {check_id} in Recce Cloud.",
+        )
+
+        data = response.json()
+        return data.get("check", {})
+
+    def delete_check(
+        self,
+        org_id: str,
+        project_id: str,
+        session_id: str,
+        check_id: str,
+    ) -> None:
+        """
+        Delete a check.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            session_id: Session ID
+            check_id: Check ID
+
+        Raises:
+            RecceCloudException: If the request fails
+
+        Example:
+            >>> client.delete_check("org123", "proj456", "sess789", "check001")
+            >>> print("Check deleted successfully")
+        """
+        api_url = (
+            f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/sessions/{session_id}/checks/{check_id}"
+        )
+        response = self._request("DELETE", api_url)
+
+        # DELETE typically returns 204 No Content on success
+        if response.status_code not in (200, 204):
+            self._raise_for_status(
+                response,
+                f"Failed to delete check {check_id} from Recce Cloud.",
+            )
+
+    def create_preset_check(self, org_id: str, project_id: str, check_data: Dict):
+        """
+        Create a preset check from an existing check.
+
+        Args:
+            org_id: Organization ID
+            project_id: Project ID
+            check_data: Check data including name, description, type, params, view_options, and order_index
+
+        Returns:
+            Created preset check dictionary
+
+        Raises:
+            RecceCloudException: If the request fails
+        """
+        api_url = f"{self.base_url_v2}/organizations/{org_id}/projects/{project_id}/preset-checks"
+        response = self._request("POST", api_url, json=check_data)
+
+        self._raise_for_status(
+            response,
+            "Failed to create preset check in Recce Cloud.",
+        )
+
+        data = response.json()
+        return data.get("presetCheck", {})

recce/util/io.py

@@ -37,12 +37,12 @@ class AbstractFileIO(metaclass=ABCMeta):
 class FileIO(AbstractFileIO, ABC):
     @staticmethod
     def write(path: str, data: str, **kwargs):
-        with open(path, "w") as f:
+        with open(path, "w", encoding="utf-8") as f:
             f.write(data)
 
     @staticmethod
     def read(path: str, **kwargs) -> str:
-        with open(path, "r") as f:
+        with open(path, "r", encoding="utf-8") as f:
             return f.read()
 
 

recce/util/lineage.py

@@ -7,19 +7,17 @@ def find_upstream(node_ids: Iterable, parent_map):
     visited = set()
     upstream = set()
 
-    def dfs(current):
+    stack = list(node_ids)
+    while stack:
+        current = stack.pop()
         if current in visited:
-            return
+            continue
         visited.add(current)
-
         parents = parent_map.get(current, [])
         for parent in parents:
-            upstream.add(parent)
-            dfs(parent)
-
-    for node_id in node_ids:
-        dfs(node_id)
-
+            if parent not in upstream:
+                upstream.add(parent)
+                stack.append(parent)
     return upstream
 
 
@@ -27,19 +25,17 @@ def find_downstream(node_ids: Iterable, child_map):
     visited = set()
     downstream = set()
 
-    def dfs(current):
+    stack = list(node_ids)
+    while stack:
+        current = stack.pop()
         if current in visited:
-            return
+            continue
         visited.add(current)
-
         children = child_map.get(current, [])
         for child in children:
-            downstream.add(child)
-            dfs(child)
-
-    for node_id in node_ids:
-        dfs(node_id)
-
+            if child not in downstream:
+                downstream.add(child)
+                stack.append(child)
     return downstream
 
 
@@ -80,3 +76,8 @@ def filter_dependency_maps(
             c_map[node_id] = {c for c in children if c in relevant_ids}
 
     return p_map, c_map
+
+
+def build_column_key(node_id: str, column_name: str) -> str:
+    """Build a unique column key from node name and column name."""
+    return f"{node_id}_{column_name}"

recce/util/perf_tracking.py

@@ -0,0 +1,85 @@
+import time
+from dataclasses import dataclass
+
+
+@dataclass
+class LineagePerfTracker:
+    lineage_start = None
+    lineage_elapsed = None
+    column_lineage_start = None
+    column_lineage_elapsed = None
+
+    total_nodes = None
+    init_nodes = None
+    cll_nodes = 0
+    change_analysis_nodes = 0
+    anchor_nodes = None
+
+    params = None
+
+    def start_lineage(self):
+        self.lineage_start = time.perf_counter_ns()
+
+    def end_lineage(self):
+        if self.lineage_start is None:
+            return
+        self.lineage_elapsed = (time.perf_counter_ns() - self.lineage_start) / 1000000
+
+    def start_column_lineage(self):
+        self.column_lineage_start = time.perf_counter_ns()
+
+    def end_column_lineage(self):
+        if self.column_lineage_start is None:
+            return
+        self.column_lineage_elapsed = (time.perf_counter_ns() - self.column_lineage_start) / 1000000
+
+    def set_total_nodes(self, total_nodes):
+        self.total_nodes = total_nodes
+
+    def set_init_nodes(self, init_nodes):
+        self.init_nodes = init_nodes
+
+    def set_anchor_nodes(self, anchor_nodes):
+        self.anchor_nodes = anchor_nodes
+
+    def increment_cll_nodes(self):
+        self.cll_nodes += 1
+
+    def increment_change_analysis_nodes(self):
+        self.change_analysis_nodes += 1
+
+    def set_params(self, has_node, has_column, change_analysis, no_cll, no_upstream, no_downstream):
+        self.params = {
+            "has_node": has_node,
+            "has_column": has_column,
+            "change_analysis": change_analysis,
+            "no_cll": no_cll,
+            "no_upstream": no_upstream,
+            "no_downstream": no_downstream,
+        }
+
+    def to_dict(self):
+        return {
+            "lineage_elapsed_ms": self.lineage_elapsed,
+            "column_lineage_elapsed_ms": self.column_lineage_elapsed,
+            "total_nodes": self.total_nodes,
+            "init_nodes": self.init_nodes,
+            "cll_nodes": self.cll_nodes,
+            "change_analysis_nodes": self.change_analysis_nodes,
+            "anchor_nodes": self.anchor_nodes,
+            "params": self.params,
+        }
+
+    def reset(self):
+        self.lineage_start = None
+        self.lineage_elapsed = None
+        self.column_lineage_start = None
+        self.column_lineage_elapsed = None
+
+        self.total_nodes = None
+        self.init_nodes = None
+        self.change_analysis_nodes = 0
+        self.cll_nodes = 0
+        self.anchor_nodes = 0
+
+        self.params = None