DataExcept 0.1.0__py3-none-any.whl

dataexcept/exceptions/parsing.py

@@ -0,0 +1,31 @@
+# parsing.py
+from .base import JobError
+
+
+class ParsingError(JobError):
+    """Raised when parsing of input data fails."""
+
+    def __init__(self, text: str, message: str | None = None):
+        self.text = text
+        self.message = message or f"Failed to parse text: {text!r}"
+        super().__init__(self.message)
+
+
+class SerializationError(JobError):
+    """Raised when serialization of an object fails."""
+
+    def __init__(self, obj, format: str, message: str | None = None):
+        self.obj = obj
+        self.format = format
+        self.message = message or f"Failed to serialize object to {format}"
+        super().__init__(self.message)
+
+
+class DeserializationError(JobError):
+    """Raised when deserialization of data fails."""
+
+    def __init__(self, data: bytes, format: str, message: str | None = None):
+        self.data = data
+        self.format = format
+        self.message = message or f"Failed to deserialize data from {format}"
+        super().__init__(self.message)

dataexcept/exceptions/scheduling.py

@@ -0,0 +1,21 @@
+# scheduling.py
+from .base import JobError
+
+
+class ScheduleConflictError(JobError):
+    """Raised when two jobs have conflicting schedules."""
+
+    def __init__(self, job_name: str, schedule: str):
+        self.job_name = job_name
+        self.schedule = schedule
+        msg = f"Schedule conflict for job '{job_name}' on schedule '{schedule}'"
+        super().__init__(msg)
+
+
+class CronExpressionError(JobError):
+    """Raised when a cron expression is invalid."""
+
+    def __init__(self, expression: str, message: str | None = None):
+        self.expression = expression
+        self.message = message or f"Invalid cron expression: '{expression}'"
+        super().__init__(self.message)

dataexcept/exceptions/validation.py

@@ -0,0 +1,12 @@
+# validation.py
+from .base import JobError
+
+
+class ValidationError(JobError):
+    """Raised when input data fails validation."""
+
+    def __init__(self, field: str, value, message: str | None = None):
+        self.field = field
+        self.value = value
+        self.message = message or f"Validation failed for field '{field}': {value!r}"
+        super().__init__(self.message)

dataexcept/io_exceptions.py

@@ -0,0 +1,66 @@
+"""Custom exceptions for file and I/O operations."""
+
+from __future__ import annotations
+
+
+class CustomIOError(Exception):
+    """Base exception for I/O errors."""
+
+    pass
+
+
+class FileReadError(CustomIOError):
+    """Raised when reading a file fails."""
+
+    def __init__(self, path: str, original: Exception | None = None) -> None:
+        """Initialize FileReadError.
+
+        Args:
+            path: File path that could not be read.
+            original: Optional underlying exception.
+        """
+        self.path = path
+        self.original = original
+        msg = f"Failed to read file '{path}'"
+        if original:
+            msg += f": {original}"
+        super().__init__(msg)
+
+
+class FileWriteError(CustomIOError):
+    """Raised when writing to a file fails."""
+
+    def __init__(self, path: str, original: Exception | None = None) -> None:
+        """Initialize FileWriteError.
+
+        Args:
+            path: File path that could not be written to.
+            original: Optional underlying exception.
+        """
+        self.path = path
+        self.original = original
+        msg = f"Failed to write file '{path}'"
+        if original:
+            msg += f": {original}"
+        super().__init__(msg)
+
+
+class FileLockError(CustomIOError):
+    """Raised when a file lock cannot be acquired."""
+
+    def __init__(self, path: str) -> None:
+        """Initialize FileLockError.
+
+        Args:
+            path: Path of the lock file.
+        """
+        self.path = path
+        super().__init__(f"Unable to obtain lock for '{path}'")
+
+
+__all__ = [
+    "CustomIOError",
+    "FileReadError",
+    "FileWriteError",
+    "FileLockError",
+]

dataexcept/job_exceptions.py

@@ -0,0 +1,59 @@
+"""Backward compatible job-related exceptions.
+
+This module re-exports the core job exceptions defined in
+:mod:`dataexcept.exceptions`. Applications should import from that
+package directly going forward. Importing from :mod:`dataexcept.job_exceptions`
+will raise a :class:`DeprecationWarning`.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+from .exceptions import (
+    AuthenticationError,
+    AuthorizationError,
+    ConfigurationError,
+    ConnectionError,
+    CronExpressionError,
+    DependencyError,
+    DeserializationError,
+    EmailError,
+    JobCancellationError,
+    JobError,
+    NotificationError,
+    ParsingError,
+    ResourceNotFoundError,
+    ScheduleConflictError,
+    SerializationError,
+    TimeoutError,
+    ValidationError,
+    WebhookError,
+)
+
+__all__ = [
+    "JobError",
+    "ValidationError",
+    "ConfigurationError",
+    "ConnectionError",
+    "TimeoutError",
+    "ResourceNotFoundError",
+    "DependencyError",
+    "AuthenticationError",
+    "AuthorizationError",
+    "ParsingError",
+    "SerializationError",
+    "DeserializationError",
+    "ScheduleConflictError",
+    "CronExpressionError",
+    "NotificationError",
+    "EmailError",
+    "WebhookError",
+    "JobCancellationError",
+]
+
+warnings.warn(
+    "dataexcept.job_exceptions is deprecated; use dataexcept.exceptions instead",
+    DeprecationWarning,
+    stacklevel=2,
+)

dataexcept/logging_helpers.py

@@ -0,0 +1,76 @@
+"""Helper functions for logging exceptions consistently."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+from typing import Any, Iterator, Mapping, Optional
+
+Context = Mapping[str, Any]
+
+
+def _normalize_context_value(value: Any) -> Any:
+    try:
+        json.dumps(value)
+        return value
+    except TypeError:
+        try:
+            return json.loads(json.dumps(value, default=str))
+        except Exception:  # pragma: no cover - extremely defensive
+            return repr(value)
+
+
+def _build_extra(context: Context | None) -> dict[str, Any] | None:
+    if not context:
+        return None
+    serialized = {
+        key: _normalize_context_value(value) for key, value in context.items()
+    }
+    return {"dataexcept_context": serialized}
+
+
+def log_exception(
+    exc: Exception,
+    logger: Optional[logging.Logger] = None,
+    level: int = logging.ERROR,
+    context: Context | None = None,
+) -> None:
+    """Log *exc* at the given log *level* using *logger*.
+
+    If *logger* is ``None`` a module level logger is used.
+    """
+    if logger is None:
+        logger = logging.getLogger(__name__)
+    exc_info = (type(exc), exc, exc.__traceback__)
+    logger.log(level, "%s", exc, exc_info=exc_info, extra=_build_extra(context))
+
+
+@contextlib.contextmanager
+def log_and_raise(
+    logger: Optional[logging.Logger] = None,
+    level: int = logging.ERROR,
+    context: Context | None = None,
+) -> Iterator[None]:
+    """Context manager that logs and re-raises exceptions preserving traceback."""
+    try:
+        yield
+    except Exception as exc:
+        log_exception(exc, logger=logger, level=level, context=context)
+        raise
+
+
+def log_then_raise(
+    exc: Exception,
+    logger: Optional[logging.Logger] = None,
+    level: int = logging.ERROR,
+    context: Context | None = None,
+) -> None:
+    """Log *exc* and immediately raise it.
+
+    This helper mirrors the pre-context-manager API for scenarios where adding a
+    ``with`` block would be too intrusive. Prefer :func:`log_and_raise` whenever
+    possible so tracebacks remain untouched.
+    """
+    log_exception(exc, logger=logger, level=level, context=context)
+    raise exc

dataexcept/network_exceptions.py

@@ -0,0 +1,102 @@
+"""Custom exceptions for network operations."""
+
+from __future__ import annotations
+
+
+class NetworkError(Exception):
+    """Base exception for network-related errors.
+
+    Example:
+        >>> from dataexcept.network_exceptions import NetworkError
+        >>> try:
+        ...     raise NetworkError("Something went wrong")
+        ... except NetworkError:
+        ...     print("Caught network error")
+        Caught network error
+    """
+
+    pass
+
+
+class HostUnreachableError(NetworkError):
+    """Raised when a remote host cannot be reached.
+
+    Example:
+        >>> from dataexcept.network_exceptions import HostUnreachableError
+        >>> try:
+        ...     raise HostUnreachableError("api.example.com")
+        ... except HostUnreachableError as exc:
+        ...     print(exc)
+        Host 'api.example.com' is unreachable
+    """
+
+    def __init__(self, host: str, message: str | None = None) -> None:
+        """Initialize HostUnreachableError.
+
+        Args:
+            host: Host address that could not be reached.
+            message: Optional custom error message.
+        """
+        self.host = host
+        default = f"Host '{host}' is unreachable"
+        super().__init__(message or default)
+
+
+class ConnectionTimeoutError(NetworkError):
+    """Raised when a network connection attempt times out.
+
+    Example:
+        >>> from dataexcept.network_exceptions import ConnectionTimeoutError
+        >>> try:
+        ...     raise ConnectionTimeoutError("api.example.com", 30)
+        ... except ConnectionTimeoutError as exc:
+        ...     print(exc)
+        Connection to 'api.example.com' timed out after 30 seconds
+    """
+
+    def __init__(self, host: str, timeout: float) -> None:
+        """Initialize ConnectionTimeoutError.
+
+        Args:
+            host: Host address.
+            timeout: Timeout in seconds.
+        """
+        self.host = host
+        self.timeout = timeout
+        msg = f"Connection to '{host}' timed out after {timeout} seconds"
+        super().__init__(msg)
+
+
+class ProtocolError(NetworkError):
+    """Raised when an unexpected protocol error occurs.
+
+    Example:
+        >>> from dataexcept.network_exceptions import ProtocolError
+        >>> try:
+        ...     raise ProtocolError("HTTP", "Invalid status line")
+        ... except ProtocolError as exc:
+        ...     print(exc)
+        Protocol error in HTTP: Invalid status line
+    """
+
+    def __init__(self, protocol: str, details: str | None = None) -> None:
+        """Initialize ProtocolError.
+
+        Args:
+            protocol: Protocol name (e.g., HTTP).
+            details: Optional additional details about the failure.
+        """
+        self.protocol = protocol
+        self.details = details
+        msg = f"Protocol error in {protocol}"
+        if details:
+            msg += f": {details}"
+        super().__init__(msg)
+
+
+__all__ = [
+    "NetworkError",
+    "HostUnreachableError",
+    "ConnectionTimeoutError",
+    "ProtocolError",
+]

dataexcept/pandas_exceptions.py

@@ -0,0 +1,143 @@
+"""Custom exceptions for pandas DataFrame operations."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+
+class PandasError(Exception):
+    """Base exception for pandas-related errors."""
+
+
+class MissingColumnError(PandasError):
+    """Raised when a required DataFrame column is missing.
+
+    Args:
+        column: Name of the missing column.
+        dataframe: Optional name of the DataFrame being inspected.
+    """
+
+    def __init__(self, column: str, dataframe: Optional[str] = None) -> None:
+        if not isinstance(column, str):
+            raise TypeError(f"column must be str, got {type(column).__name__}")
+        if dataframe is not None and not isinstance(dataframe, str):
+            raise TypeError(
+                "dataframe must be str or None, " f"got {type(dataframe).__name__}"
+            )
+
+        self.column = column
+        self.dataframe = dataframe
+        name = f" in DataFrame '{dataframe}'" if dataframe else ""
+        msg = f"Missing required column '{column}'{name}"
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[MissingColumnError] {self.args[0]}"
+
+
+class DtypeMismatchError(PandasError):
+    """Raised when a column has an unexpected dtype.
+
+    Args:
+        column: Name of the column.
+        expected: Sequence of allowed dtypes.
+        found: Detected dtype for the column.
+    """
+
+    def __init__(self, column: str, expected: Sequence[str], found: str) -> None:
+        if not isinstance(column, str):
+            raise TypeError(f"column must be str, got {type(column).__name__}")
+        if not isinstance(found, str):
+            raise TypeError(f"found must be str, got {type(found).__name__}")
+        if not isinstance(expected, Sequence) or isinstance(expected, str):
+            raise TypeError("expected must be a sequence of strings")
+        if not all(isinstance(dt, str) for dt in expected):
+            raise TypeError("expected must contain strings")
+
+        self.column = column
+        self.expected = list(expected)
+        self.found = found
+        expected_fmt = ", ".join(self.expected)
+        msg = f"Column '{column}' has dtype {found}; expected {expected_fmt}"
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[DtypeMismatchError:{self.column}] {self.args[0]}"
+
+
+class IndexAlignmentError(PandasError):
+    """Raised when DataFrame indices are misaligned for an operation.
+
+    Args:
+        details: Optional details about the misalignment.
+    """
+
+    def __init__(self, details: Optional[str] = None) -> None:
+        if details is not None and not isinstance(details, str):
+            raise TypeError(
+                f"details must be str or None, got {type(details).__name__}"
+            )
+        msg = "DataFrame indices are misaligned"
+        if details:
+            msg += f": {details}"
+        self.details = details
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[IndexAlignmentError] {self.args[0]}"
+
+
+class MergeKeyError(PandasError):
+    """Raised when merging DataFrames fails due to key issues.
+
+    Args:
+        left_keys: Keys from the left DataFrame.
+        right_keys: Keys from the right DataFrame.
+    """
+
+    def __init__(self, left_keys: Sequence[str], right_keys: Sequence[str]) -> None:
+        if not all(isinstance(k, str) for k in left_keys):
+            raise TypeError("left_keys must be a sequence of strings")
+        if not all(isinstance(k, str) for k in right_keys):
+            raise TypeError("right_keys must be a sequence of strings")
+        self.left_keys = list(left_keys)
+        self.right_keys = list(right_keys)
+        msg = f"Failed to merge on keys {self.left_keys} and {self.right_keys}"
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[MergeKeyError] {self.args[0]}"
+
+
+class PandasIOError(PandasError):
+    """Raised when reading from or writing to disk with pandas fails.
+
+    Args:
+        path: File path involved in the operation.
+        original: The underlying exception that was raised.
+    """
+
+    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__}"
+            )
+        self.path = path
+        self.original = original
+        msg = f"Pandas I/O operation failed on {path!r}: {original}"
+        super().__init__(msg)
+
+    def __str__(self) -> str:
+        return f"[PandasIOError] {self.args[0]}"
+
+
+__all__ = [
+    "PandasError",
+    "MissingColumnError",
+    "DtypeMismatchError",
+    "IndexAlignmentError",
+    "MergeKeyError",
+    "PandasIOError",
+]