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

recce/state/const.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass
+
+RECCE_STATE_FILE = "recce-state.json"
+RECCE_STATE_COMPRESSED_FILE = f"{RECCE_STATE_FILE}.gz"
+
+
+@dataclass
+class ErrorMessage:
+    error_message: str
+    hint_message: str
+
+
+RECCE_CLOUD_TOKEN_MISSING = ErrorMessage(
+    error_message="No GitHub token is provided to access the pull request information",
+    hint_message="Please provide a GitHub token in the command argument",
+)
+
+RECCE_CLOUD_PASSWORD_MISSING = ErrorMessage(
+    error_message="No password provided to access the state file in Recce Cloud",
+    hint_message='Please provide a password with the option "--password <compress-password>"',
+)
+
+RECCE_API_TOKEN_MISSING = ErrorMessage(
+    error_message="No Recce API token is provided",
+    hint_message="Please login to Recce Cloud and copy the API token from the settings page",
+)

recce/state/local.py

@@ -0,0 +1,56 @@
+import logging
+import os
+from typing import Optional, Tuple, Union
+
+from .state import RecceState
+from .state_loader import RecceStateLoader
+
+logger = logging.getLogger("uvicorn")
+
+
+class FileStateLoader(RecceStateLoader):
+    def __init__(
+        self,
+        review_mode: bool = False,
+        state_file: Optional[str] = None,
+        initial_state: Optional[RecceState] = None,
+    ):
+        super().__init__(review_mode=review_mode, state_file=state_file, initial_state=initial_state)
+
+    def verify(self) -> bool:
+        if self.review_mode is True and self.state_file is None:
+            self.error_message = "Recce can not launch without a state file."
+            self.hint_message = "Please provide a state file in the command argument."
+            return False
+        return True
+
+    def _load_state(self) -> Tuple[RecceState, str]:
+        state = RecceState.from_file(self.state_file) if self.state_file else None
+        state_tag = None
+        return state, state_tag
+
+    def _export_state(self, state: RecceState = None) -> Tuple[Union[str, None], str]:
+        """
+        Store the state to a file. Store happens when terminating the server or run instance.
+        """
+
+        if self.state_file is None:
+            return "No state file is provided. Skip storing the state.", None
+
+        logger.info(f"Store recce state to '{self.state_file}'")
+        message = self._export_state_to_file(self.state_file)
+        tag = None
+
+        return message, tag
+
+    def purge(self) -> bool:
+        if self.state_file is not None:
+            try:
+                os.remove(self.state_file)
+                return True
+            except Exception as e:
+                self.error_message = f"Failed to remove the state file: {e}"
+                return False
+        else:
+            self.error_message = "No state file is provided. Skip removing the state file."
+            return False

recce/state/state.py

@@ -0,0 +1,119 @@
+"""Define the type to serialize/de-serialize the state of the recce instance."""
+
+import json
+import logging
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from recce import get_version
+from recce.exceptions import RecceException
+from recce.git import current_branch
+from recce.models.types import Check, Run
+from recce.pull_request import PullRequestInfo
+from recce.util.io import SupportedFileTypes, file_io_factory
+from recce.util.pydantic_model import pydantic_model_dump, pydantic_model_json_dump
+
+logger = logging.getLogger("uvicorn")
+
+
+class GitRepoInfo(BaseModel):
+    branch: Optional[str] = None
+
+    @staticmethod
+    def from_current_repository() -> Optional["GitRepoInfo"]:
+        branch = current_branch()
+        if branch is None:
+            return None
+
+        return GitRepoInfo(branch=branch)
+
+    def to_dict(self):
+        return pydantic_model_dump(self)
+
+
+class RecceStateMetadata(BaseModel):
+    schema_version: str = "v0"
+    recce_version: str = Field(default_factory=lambda: get_version())
+    generated_at: str = Field(default_factory=lambda: datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"))
+
+
+class ArtifactsRoot(BaseModel):
+    """
+    Root of the artifacts.
+
+    base: artifacts of the base env. key is file name, value is dict
+    current: artifacts of the current env. key is file name, value is dict
+    """
+
+    base: Dict[str, Optional[dict]] = {}
+    current: Dict[str, Optional[dict]] = {}
+
+
+class RecceState(BaseModel):
+    metadata: Optional[RecceStateMetadata] = None
+    runs: Optional[List[Run]] = Field(default_factory=list)
+    checks: Optional[List[Check]] = Field(default_factory=list)
+    artifacts: ArtifactsRoot = ArtifactsRoot(base={}, current={})
+    git: Optional[GitRepoInfo] = None
+    pull_request: Optional[PullRequestInfo] = None
+
+    @staticmethod
+    def from_json(json_content: str):
+        dict_data = json.loads(json_content)
+        state = RecceState(**dict_data)
+        metadata = state.metadata
+
+        if metadata:
+            if metadata.schema_version is None:
+                pass
+            if metadata.schema_version == "v0":
+                pass
+            else:
+                raise RecceException(f"Unsupported state file version: {metadata.schema_version}")
+        return state
+
+    @staticmethod
+    def from_file(file_path: str, file_type: SupportedFileTypes = SupportedFileTypes.FILE):
+        """
+        Load the state from a recce state file.
+        """
+        from pathlib import Path
+
+        logger.debug(f"Load state file from: '{file_path}'")
+        if not Path(file_path).is_file():
+            return None
+
+        io = file_io_factory(file_type)
+        json_content = io.read(file_path)
+        return RecceState.from_json(json_content)
+
+    def to_json(self):
+        return pydantic_model_json_dump(self)
+
+    def to_file(self, file_path: str, file_type: SupportedFileTypes = SupportedFileTypes.FILE):
+
+        json_data = self.to_json()
+        io = file_io_factory(file_type)
+
+        io.write(file_path, json_data)
+        return f"The state file is stored at '{file_path}'"
+
+    def _merge_run(self, run: Run):
+        for r in self.runs:
+            if r.run_id == run.run_id:
+                break
+        else:
+            self.runs.append(run)
+
+    def _merge_check(self, check: Check):
+        for c in self.checks:
+            if c.check_id == check.check_id:
+                c.merge(check)
+                break
+        else:
+            self.checks.append(check)
+
+    def _merge_artifacts(self, artifacts: ArtifactsRoot):
+        self.artifacts.merge(artifacts)

recce/state/state_loader.py

@@ -0,0 +1,174 @@
+import logging
+import threading
+import time
+from abc import ABC, abstractmethod
+from typing import Dict, Literal, Optional, Tuple, Union, final
+
+from recce.exceptions import RecceException
+from recce.pull_request import fetch_pr_metadata
+
+from ..util.io import SupportedFileTypes, file_io_factory
+from .const import RECCE_API_TOKEN_MISSING
+from .state import RecceState
+
+logger = logging.getLogger("uvicorn")
+
+
+class RecceStateLoader(ABC):
+    def __init__(
+        self,
+        review_mode: bool = False,
+        cloud_mode: bool = False,
+        state_file: Optional[str] = None,
+        cloud_options: Optional[Dict[str, str]] = None,
+        initial_state: Optional[RecceState] = None,
+    ):
+        self.review_mode = review_mode
+        self.cloud_mode = cloud_mode
+        self.state_file = state_file
+        self.cloud_options = cloud_options or {}
+        self.error_message = None
+        self.hint_message = None
+        self.state: RecceState | None = initial_state
+        self.state_lock = threading.Lock()
+        self.state_etag = None
+        self.pr_info = None
+        self.catalog: Literal["github", "preview", "session"] = "github"
+        self.share_id = None
+        self.session_id = None
+
+        if self.cloud_mode:
+            if self.cloud_options.get("github_token"):
+                self.catalog = "github"
+                self.pr_info = fetch_pr_metadata(
+                    cloud=self.cloud_mode, github_token=self.cloud_options.get("github_token")
+                )
+                if self.pr_info.id is None:
+                    raise RecceException("Cannot get the pull request information from GitHub.")
+            elif self.cloud_options.get("api_token"):
+                if self.cloud_options.get("session_id"):
+                    self.catalog = "session"
+                    self.session_id = self.cloud_options.get("session_id")
+                else:
+                    self.catalog = "preview"
+                    self.share_id = self.cloud_options.get("share_id")
+            else:
+                raise RecceException(RECCE_API_TOKEN_MISSING.error_message)
+
+    @property
+    def token(self):
+        return self.cloud_options.get("github_token") or self.cloud_options.get("api_token")
+
+    @abstractmethod
+    def verify(self) -> bool:
+        """
+        Verify the state loader configuration.
+        Returns:
+            bool: True if the configuration is valid, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    @property
+    def error_and_hint(self) -> (Union[str, None], Union[str, None]):
+        return self.error_message, self.hint_message
+
+    def update(self, state: RecceState):
+        self.state = state
+
+    @final
+    def load(self, refresh=False) -> RecceState:
+        if self.state is not None and refresh is False:
+            return self.state
+        self.state_lock.acquire()
+        try:
+            self.state, self.state_etag = self._load_state()
+        finally:
+            self.state_lock.release()
+        return self.state
+
+    @abstractmethod
+    def _load_state(self) -> Tuple[RecceState, str]:
+        """
+        Load the state from the specified source (file or cloud).
+        Returns:
+            RecceState: The loaded state object.
+            str: The etag of the state file (if applicable).
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    def save_as(self, state_file: str, state: RecceState = None):
+        if self.cloud_mode:
+            raise Exception("Cannot save the state to Recce Cloud.")
+
+        self.state_file = state_file
+        self.export(state)
+
+    @final
+    def export(self, state: RecceState = None) -> Union[str, None]:
+        if state is not None:
+            self.update(state)
+
+        start_time = time.time()
+        self.state_lock.acquire()
+        try:
+            message, state_etag = self._export_state()
+            self.state_etag = state_etag
+            end_time = time.time()
+            elapsed_time = end_time - start_time
+        finally:
+            self.state_lock.release()
+        logger.info(f"Store state completed in {elapsed_time:.2f} seconds")
+        return message
+
+    @abstractmethod
+    def _export_state(self) -> Tuple[Union[str, None], str]:
+        """
+        Export the current Recce state to a file or cloud storage.
+        Returns:
+            str: A message indicating the result of the export operation.
+            str: The etag of the exported state file (if applicable).
+        """
+        raise NotImplementedError("Subclasses must implement this method.")
+
+    def _export_state_to_file(self, file_path: str, file_type: SupportedFileTypes = SupportedFileTypes.FILE) -> str:
+        """
+        Store the state to a file. Store happens when terminating the server or run instance.
+        """
+
+        json_data = self.state.to_json()
+        io = file_io_factory(file_type)
+
+        io.write(file_path, json_data)
+        return f"The state file is stored at '{file_path}'"
+
+    def refresh(self):
+        new_state = self.load(refresh=True)
+        return new_state
+
+    def check_conflict(self) -> bool:
+        return False
+
+    def info(self) -> dict:
+        if self.state is None:
+            self.error_message = "No state is loaded."
+            return None
+
+        state_info = {
+            "mode": "cloud" if self.cloud_mode else "local",
+            "source": None,
+        }
+        if self.cloud_mode:
+            state_info["source"] = "Recce Cloud"
+            state_info["pull_request"] = self.pr_info
+        else:
+            state_info["source"] = self.state_file
+        return state_info
+
+    @abstractmethod
+    def purge(self) -> bool:
+        """
+        Purge the state file or cloud storage.
+        Returns:
+            bool: True if the purge was successful, False otherwise.
+        """
+        raise NotImplementedError("Subclasses must implement this method.")