Analysis¶

def start(self) -> None:
    """
    Marks the analysis as started.

    Notes
    -----
    Updates status to RUNNING and records the start timestamp.
    """
    self.status = AnalysisStatus.RUNNING
    self.started_at = datetime.now()

def complete(self, metadata: Optional[Dict[str, Any]] = None) -> None:
    """
    Marks the analysis as successfully completed.

    Parameters
    ----------
    metadata : Optional[Dict[str, Any]], optional
        Result metadata, by default None.

    Notes
    -----
    Updates status to COMPLETED and records the completion timestamp.
    """
    self.status = AnalysisStatus.COMPLETED
    self.completed_at = datetime.now()
    if metadata:
        self.result_metadata.update(metadata)

def fail(self, error_message: str) -> None:
    """
    Marks the analysis as failed.

    Parameters
    ----------
    error_message : str
        Error message describing the failure.

    Notes
    -----
    Updates status to FAILED and records the error message.
    """
    self.status = AnalysisStatus.FAILED
    self.completed_at = datetime.now()
    self.error_message = error_message

def mark_from_cache(self) -> None:
    """
    Marks the analysis as loaded from cache.

    Notes
    -----
    The CACHED status indicates that the result was retrieved from
    the cache without the need for reprocessing.
    """
    self.status = AnalysisStatus.CACHED
    self.completed_at = datetime.now()

def validate(self) -> None:
    """
    Validates the analysis metadata.

    Raises
    ------
    ValueError
        If ID, name, or category are empty.
    """
    if not self.id or not self.id.strip():
        raise ValueError("Analysis ID cannot be empty")

    if not self.name or not self.name.strip():
        raise ValueError("Analysis name cannot be empty")

    if not self.category or not self.category.strip():
        raise ValueError("Analysis category cannot be empty")

def __str__(self) -> str:
    """
    Returns the string representation of the analysis.

    Returns
    -------
    str
        Descriptive string.
    """
    return f"Analysis({self.id}: {self.name}) - {self.status.value}"

def __repr__(self) -> str:
    """
    Returns the debug representation of the analysis.

    Returns
    -------
    str
        Detailed representation.
    """
    return (
        f"Analysis(id='{self.id}', "
        f"name='{self.name}', "
        f"status={self.status})"
    )