DataExcept 0.1.0__py3-none-any.whl

dataexcept/datascience_exceptions/ingestion.py

@@ -0,0 +1,312 @@
+"""Data ingestion and validation related errors."""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Sequence
+
+from .base import DataScienceError
+
+
+class DataLoadingError(DataScienceError):
+    """
+    Raised when loading data fails.
+
+    Attributes:
+        source: data source description (file path, URL).
+        original: underlying exception.
+    """
+
+    def __init__(self, source: str, original: Exception) -> None:
+        if not isinstance(source, str):
+            raise TypeError(f"source must be str, got {type(source).__name__}")
+        if not isinstance(original, Exception):
+            raise TypeError(
+                f"original must be Exception, got {type(original).__name__}"
+            )
+
+        message = f"Failed to load data from {source!r}: {original}"
+        self.source = source
+        self.original = original
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[DataLoadingError] {self.source}"
+
+
+class DataFormatError(DataScienceError):
+    """Raised when input data is not in the expected format."""
+
+    def __init__(self, expected_formats: Sequence[str], found_format: str) -> None:
+        if not isinstance(found_format, str):
+            raise TypeError(
+                f"found_format must be str, got {type(found_format).__name__}"
+            )
+        if not isinstance(expected_formats, Sequence) or isinstance(
+            expected_formats, str
+        ):
+            raise TypeError("expected_formats must be a sequence of strings")
+        if not all(isinstance(fmt, str) for fmt in expected_formats):
+            raise TypeError("expected_formats must contain strings")
+
+        self.expected_formats = list(expected_formats)
+        self.found_format = found_format
+        fmt_list = ", ".join(self.expected_formats)
+        message = f"Expected data format {fmt_list}; got {found_format}"
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[DataFormatError] {self.message}"
+
+
+class DataValidationError(DataScienceError):
+    """
+    Raised when data fails validation rules.
+
+    Attributes:
+        field: name of invalid field.
+        value: the invalid value.
+    """
+
+    def __init__(self, field: str, value: Any, message: Optional[str] = None) -> None:
+        if not isinstance(field, str):
+            raise TypeError(f"field must be str, got {type(field).__name__}")
+
+        if message is None:
+            message = f"Invalid value for '{field}': {value!r}"
+        elif not isinstance(message, str):
+            raise TypeError(f"message must be str, got {type(message).__name__}")
+
+        self.field = field
+        self.value = value
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[DataValidationError:{self.field}] {self.message}"
+
+
+class MissingDataError(DataScienceError):
+    """
+    Raised when required data is missing.
+
+    Attributes:
+        feature: name of missing feature.
+    """
+
+    def __init__(self, feature: str, message: Optional[str] = None) -> None:
+        if not isinstance(feature, str):
+            raise TypeError(f"feature must be str, got {type(feature).__name__}")
+
+        if message is None:
+            message = f"Missing required feature: {feature!r}"
+        elif not isinstance(message, str):
+            raise TypeError(f"message must be str, got {type(message).__name__}")
+
+        self.feature = feature
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[MissingDataError] {self.feature}"
+
+
+class OutlierDetectionError(DataScienceError):
+    """
+    Raised when outlier detection fails.
+
+    Attributes:
+        method: detection method name.
+        details: optional extra info.
+    """
+
+    def __init__(self, method: str, details: Optional[str] = None) -> None:
+        if not isinstance(method, str):
+            raise TypeError(f"method must be str, got {type(method).__name__}")
+        if details is not None and not isinstance(details, str):
+            raise TypeError(
+                f"details must be str or None, got {type(details).__name__}"
+            )
+
+        msg = f"Outlier detection failed using method '{method}'"
+        if details:
+            msg += f": {details}"
+
+        self.method = method
+        self.details = details
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[OutlierDetectionError:{self.method}] {self.message}"
+
+
+class SchemaMismatchError(DataScienceError):
+    """
+    Raised when data schema does not match expected.
+
+    Attributes:
+        expected: expected schema description.
+        found: actual schema description.
+    """
+
+    def __init__(self, expected: str, found: str) -> None:
+        if not isinstance(expected, str):
+            raise TypeError(f"expected must be str, got {type(expected).__name__}")
+        if not isinstance(found, str):
+            raise TypeError(f"found must be str, got {type(found).__name__}")
+
+        message = f"Schema mismatch. Expected: {expected}, Found: {found}"
+        self.expected = expected
+        self.found = found
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[SchemaMismatchError] {self.message}"
+
+
+class FeatureEngineeringError(DataScienceError):
+    """
+    Raised during feature engineering steps.
+
+    Attributes:
+        step: description of the step that failed.
+        cause: optional underlying reason.
+    """
+
+    def __init__(self, step: str, cause: Optional[str] = None) -> None:
+        if not isinstance(step, str):
+            raise TypeError(f"step must be str, got {type(step).__name__}")
+        if cause is not None and not isinstance(cause, str):
+            raise TypeError(f"cause must be str or None, got {type(cause).__name__}")
+
+        msg = f"Feature engineering failed at step '{step}'"
+        if cause:
+            msg += f": {cause}"
+
+        self.step = step
+        self.cause = cause
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[FeatureEngineeringError] {self.message}"
+
+
+class DataNormalizationError(DataScienceError):
+    """Raised when data normalization fails.
+
+    Args:
+        method: Normalization technique identifier.
+        details: Optional explanation of the failure.
+    """
+
+    def __init__(self, method: str, details: Optional[str] = None) -> None:
+        if not isinstance(method, str):
+            raise TypeError(f"method must be str, got {type(method).__name__}")
+        if details is not None and not isinstance(details, str):
+            raise TypeError(
+                f"details must be str or None, got {type(details).__name__}"
+            )
+        # Build a helpful error message
+        msg = f"Normalization using '{method}' failed"
+        if details:
+            msg += f": {details}"
+        self.method = method
+        self.details = details
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DataNormalizationError:{self.method}] {self.message}"
+
+
+class DataImbalanceError(DataScienceError):
+    """Raised when class distribution is too imbalanced.
+
+    Args:
+        ratio: Observed minority-to-majority ratio.
+        threshold: Minimum acceptable ratio.
+        message: Optional custom error message.
+    """
+
+    def __init__(
+        self, ratio: float, threshold: float, message: Optional[str] = None
+    ) -> None:
+        if not isinstance(ratio, (int, float)):
+            raise TypeError(f"ratio must be numeric, got {type(ratio).__name__}")
+        if not isinstance(threshold, (int, float)):
+            raise TypeError(
+                f"threshold must be numeric, got {type(threshold).__name__}"
+            )
+        if message is not None and not isinstance(message, str):
+            raise TypeError(
+                f"message must be str or None, got {type(message).__name__}"
+            )
+        self.ratio = float(ratio)
+        self.threshold = float(threshold)
+        if message is None:
+            msg = (
+                f"Data imbalance detected: ratio={self.ratio:.3f} < "
+                f"threshold={self.threshold:.3f}"
+            )
+        else:
+            msg = message
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DataImbalanceError] {self.message}"
+
+
+class DataAugmentationError(DataScienceError):
+    """Raised when a data augmentation technique fails.
+
+    Args:
+        technique: Name of the augmentation technique.
+        details: Optional explanation of the failure.
+    """
+
+    def __init__(self, technique: str, details: Optional[str] = None) -> None:
+        if not isinstance(technique, str):
+            raise TypeError(f"technique must be str, got {type(technique).__name__}")
+        if details is not None and not isinstance(details, str):
+            raise TypeError(
+                f"details must be str or None, got {type(details).__name__}"
+            )
+
+        msg = f"Data augmentation '{technique}' failed"
+        if details:
+            msg += f": {details}"
+
+        self.technique = technique
+        self.details = details
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DataAugmentationError:{self.technique}] {self.message}"
+
+
+class DataLeakageError(DataScienceError):
+    """Raised when data leakage is detected between train and test sets.
+
+    Args:
+        feature: Name of the leaked feature.
+        stage: Stage where the leakage occurred.
+        message: Optional custom message.
+    """
+
+    def __init__(self, feature: str, stage: str, message: Optional[str] = None) -> None:
+        if not isinstance(feature, str):
+            raise TypeError(f"feature must be str, got {type(feature).__name__}")
+        if not isinstance(stage, str):
+            raise TypeError(f"stage must be str, got {type(stage).__name__}")
+        if message is not None and not isinstance(message, str):
+            raise TypeError(
+                f"message must be str or None, got {type(message).__name__}"
+            )
+
+        if message is None:
+            msg = f"Data leakage detected for '{feature}' during {stage}"
+        else:
+            msg = message
+
+        self.feature = feature
+        self.stage = stage
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DataLeakageError:{self.feature}] {self.message}"

dataexcept/datascience_exceptions/operations.py

@@ -0,0 +1,130 @@
+"""Operational and deployment errors for ML systems."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import DataScienceError
+
+
+class SerializationError(DataScienceError):
+    """
+    Raised when saving or loading a model fails.
+
+    Attributes:
+        path: file path involved.
+        original: underlying exception.
+    """
+
+    def __init__(self, path: str, original: Exception) -> None:
+        if not isinstance(path, str):
+            raise TypeError(f"path must be str, got {type(path).__name__}")
+        if not isinstance(original, Exception):
+            raise TypeError(
+                f"original must be Exception, got {type(original).__name__}"
+            )
+
+        message = f"Failed to serialize to {path!r}: {original}"
+        self.path = path
+        self.original = original
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[SerializationError] {self.path}"
+
+
+class DeploymentError(DataScienceError):
+    """
+    Raised when deploying a model or pipeline fails.
+
+    Attributes:
+        target: deployment target identifier.
+        cause: optional detail.
+    """
+
+    def __init__(self, target: str, cause: Optional[str] = None) -> None:
+        if not isinstance(target, str):
+            raise TypeError(f"target must be str, got {type(target).__name__}")
+        if cause is not None and not isinstance(cause, str):
+            raise TypeError(f"cause must be str or None, got {type(cause).__name__}")
+
+        msg = f"Deployment failed to '{target}'"
+        if cause:
+            msg += f": {cause}"
+
+        self.target = target
+        self.cause = cause
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DeploymentError] {self.target}"
+
+
+class DataDriftError(DataScienceError):
+    """
+    Raised when data drift is detected beyond threshold.
+
+    Attributes:
+        feature: feature name.
+        drift_score: computed drift metric.
+    """
+
+    def __init__(
+        self, feature: str, drift_score: float, message: Optional[str] = None
+    ) -> None:
+        if not isinstance(feature, str):
+            raise TypeError(f"feature must be str, got {type(feature).__name__}")
+        if not isinstance(drift_score, (int, float)):
+            raise TypeError(
+                f"drift_score must be number, got {type(drift_score).__name__}"
+            )
+
+        self.feature = feature
+        self.drift_score = float(drift_score)
+        if message is None:
+            message = f"Data drift detected on '{feature}', score={drift_score:.4f}"
+
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[DataDriftError:{self.feature}] {self.message}"
+
+
+class ResourceLimitError(DataScienceError):
+    """
+    Raised when computation exceeds resources (memory, CPU).
+
+    Attributes:
+        resource: 'memory', 'cpu', etc.
+        limit: threshold exceeded.
+    """
+
+    def __init__(self, resource: str, limit: Any) -> None:
+        if not isinstance(resource, str):
+            raise TypeError(f"resource must be str, got {type(resource).__name__}")
+
+        message = f"Resource limit exceeded: {resource} at {limit!r}"
+        self.resource = resource
+        self.limit = limit
+        super().__init__(message)
+
+    def __str__(self) -> str:
+        return f"[ResourceLimitError:{self.resource}] {self.message}"
+
+
+class DataExportError(DataScienceError):
+    """Failed to export or write data to destination."""
+
+    def __init__(self, destination: str, original: Exception) -> None:
+        if not isinstance(destination, str):
+            raise TypeError(
+                f"destination must be str, got {type(destination).__name__}"
+            )
+        if not isinstance(original, Exception):
+            raise TypeError(
+                f"original must be Exception, got {type(original).__name__}"
+            )
+        msg = f"Unable to export data to {destination}: {original}"
+        self.destination = destination
+        self.original = original
+        super().__init__(msg)