awesome-errors 0.3.0__py3-none-any.whl

awesome_errors/client/response_parser.py

@@ -0,0 +1,175 @@
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional, Protocol, Union, cast
+
+from .exceptions import BackendError
+from ..core.error_response import ErrorDetail, error_detail_from_mapping
+
+
+class _HasDetails(Protocol):
+    details: Dict[str, Any]
+
+
+class ErrorDetailMixin:
+    @property
+    def field(self) -> Any:
+        return cast(_HasDetails, self).details.get("field")
+
+    @property
+    def field_errors(self) -> Any:
+        return cast(_HasDetails, self).details.get("field_errors")
+
+    @property
+    def table(self) -> Any:
+        return cast(_HasDetails, self).details.get("table")
+
+    @property
+    def constraint(self) -> Any:
+        return cast(_HasDetails, self).details.get("constraint")
+
+    @property
+    def duplicate_value(self) -> Any:
+        return cast(_HasDetails, self).details.get("duplicate_value")
+
+
+class ErrorResponseParser:
+    """Parser for backend error responses."""
+
+    @classmethod
+    def parse_response(
+        cls,
+        response_body: Union[str, bytes, Dict[str, Any]],
+        status_code: int,
+        headers: Optional[Dict[str, str]] = None,
+    ) -> BackendError:
+        """
+        Parse error response from backend.
+
+        Args:
+            response_body: Response body (JSON string, bytes, or dict)
+            status_code: HTTP status code
+            headers: Response headers
+
+        Returns:
+            BackendError instance
+
+        Raises:
+            ValueError: If response cannot be parsed
+        """
+        try:
+            data = (
+                json.loads(response_body)
+                if isinstance(response_body, (str, bytes))
+                else response_body
+            )
+
+            if not isinstance(data, dict):
+                raise ValueError("Response body is not a JSON object")
+
+            detail_payload: Optional[Dict[str, Any]] = None
+            if cls.is_error_response(data):
+                error_block = data.get("error", {})
+                if isinstance(error_block, dict):
+                    detail_payload = dict(error_block)
+            elif cls.is_problem_response(data):
+                detail_payload = cls._problem_detail_to_error_payload(data)
+
+            if detail_payload is None:
+                raise ValueError("Unsupported error response shape")
+
+            request_id = detail_payload.get("request_id")
+            if not request_id:
+                request_id = headers.get("X-Request-ID") if headers else None
+                detail_payload["request_id"] = request_id or "unknown"
+
+            error_detail = error_detail_from_mapping(detail_payload)
+
+            return BackendError(
+                error=error_detail,
+                status_code=status_code,
+                response_headers=headers,
+            )
+
+        except (json.JSONDecodeError, ValueError, TypeError) as e:
+            # Fallback for non-standard error responses
+            return cls._create_fallback_error(response_body, status_code, headers, e)
+
+    @classmethod
+    def _create_fallback_error(
+        cls,
+        response_body: Any,
+        status_code: int,
+        headers: Optional[Dict[str, str]],
+        parse_error: Exception,
+    ) -> BackendError:
+        """Create fallback error when parsing fails."""
+        # Try to extract message from response
+        message = "Unknown error"
+        details: Dict[str, Any] = {
+            "parse_error": str(parse_error),
+            "response_type": type(response_body).__name__,
+        }
+
+        if isinstance(response_body, dict):
+            # Try common error fields
+            message = (
+                response_body.get("message")
+                or response_body.get("error")
+                or response_body.get("detail")
+                or str(response_body)
+            )
+            details["raw_response"] = response_body
+        elif isinstance(response_body, (str, bytes)):
+            message = str(response_body)[:200]  # Limit length
+            details["raw_response"] = message
+
+        # Create error detail
+        error_detail = ErrorDetail(
+            code="UNKNOWN_ERROR",
+            message=message,
+            details=details,
+            request_id=headers.get("X-Request-ID", "unknown") if headers else "unknown",
+        )
+
+        return BackendError(
+            error=error_detail, status_code=status_code, response_headers=headers
+        )
+
+    @classmethod
+    def is_error_response(cls, response_data: Dict[str, Any]) -> bool:
+        """
+        Check if response data is an error response.
+
+        Args:
+            response_data: Response data as dictionary
+
+        Returns:
+            True if this is an error response
+        """
+        return "error" in response_data and isinstance(response_data.get("error"), dict)
+
+    @classmethod
+    def is_problem_response(cls, response_data: Dict[str, Any]) -> bool:
+        """Check whether the payload follows RFC 7807 conventions."""
+
+        required = {"type", "title", "status", "code"}
+        return required.issubset(response_data.keys())
+
+    @staticmethod
+    def _problem_detail_to_error_payload(data: Dict[str, Any]) -> Dict[str, Any]:
+        payload = {
+            "code": str(data.get("code", "UNKNOWN_ERROR")),
+            "message": data.get("title") or data.get("detail") or "Unknown error",
+            "request_id": data.get("request_id", ""),
+            "timestamp": data.get("timestamp"),
+            "details": dict(data.get("details") or {}),
+        }
+
+        # Carry over common meta fields into details for debugging purposes
+        details = payload["details"]
+        if "detail" in data and "explanation" not in details:
+            details.setdefault("detail", data.get("detail"))
+        if "instance" in data:
+            details.setdefault("instance", data.get("instance"))
+        return payload

awesome_errors/converters/__init__.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .python_converter import PythonErrorConverter
+from .sql_converter import SQLErrorConverter
+from .universal_converter import UniversalErrorConverter
+
+PydanticErrorConverter: Any
+try:  # pragma: no cover - optional dependency
+    from .pydantic_converter import PydanticErrorConverter as PydanticErrorConverter
+except ImportError:  # pragma: no cover
+
+    class _FallbackPydanticErrorConverter:
+        """Placeholder raising a helpful message when pydantic is missing."""
+
+        @staticmethod
+        def convert(*_args: Any, **_kwargs: Any) -> Any:
+            raise ImportError(
+                "Install 'awesome-errors[pydantic]' to enable Pydantic error conversions."
+            )
+
+    PydanticErrorConverter = _FallbackPydanticErrorConverter
+
+
+__all__ = [
+    "SQLErrorConverter",
+    "PythonErrorConverter",
+    "PydanticErrorConverter",
+    "UniversalErrorConverter",
+]

awesome_errors/converters/generic.py

@@ -0,0 +1,23 @@
+from ..core.exceptions import AppError
+from ..core.error_codes import ErrorCode
+
+
+def generic_error_handler(error: Exception, debug: bool = False) -> AppError:
+    error_type = type(error).__name__
+    error_module = type(error).__module__
+    details: dict[str, object] = {
+        "error_type": error_type,
+        "error_module": error_module,
+    }
+    if debug:
+        details["error_str"] = str(error)
+        details["error_repr"] = repr(error)
+        if hasattr(error, "__dict__"):
+            details["error_attrs"] = {
+                k: str(v) for k, v in error.__dict__.items() if not k.startswith("_")
+            }
+    return AppError(
+        code=ErrorCode.INTERNAL_ERROR,
+        message=f"Unexpected error: {error_type}",
+        details=details,
+    )

awesome_errors/converters/pydantic_converter.py

@@ -0,0 +1,75 @@
+from typing import Any, Dict, List, Mapping, Sequence
+from pydantic import ValidationError as PydanticValidationError
+
+from ..core.error_codes import ErrorCode
+from ..core.exceptions import ValidationError
+
+
+class PydanticErrorConverter:
+    """Convert Pydantic validation errors to application errors."""
+
+    @classmethod
+    def convert(cls, error: PydanticValidationError) -> ValidationError:
+        """
+        Convert Pydantic ValidationError to application ValidationError.
+
+        Args:
+            error: Pydantic validation error
+
+        Returns:
+            Application ValidationError with detailed field information
+        """
+        errors = error.errors()
+
+        # Extract first error for main message
+        first_error: Mapping[str, Any] | None = errors[0] if errors else None
+        main_field = cls._get_field_path(first_error.get("loc", [])) if first_error else ""
+        main_message = first_error.get("msg", "Validation failed") if first_error else "Validation failed"
+
+        # Build detailed error information
+        field_errors = cls._build_field_errors(errors)
+
+        # Create validation error with detailed field information
+        validation_error = ValidationError(
+            message=f"Validation failed for field '{main_field}': {main_message}"
+            if main_field
+            else main_message,
+            code=ErrorCode.VALIDATION_FAILED,
+        )
+
+        # Add detailed field errors
+        validation_error.details = {
+            "field_errors": field_errors,
+            "error_count": len(errors),
+        }
+
+        return validation_error
+
+    @classmethod
+    def _build_field_errors(
+        cls, errors: Sequence[Mapping[str, Any]]
+    ) -> List[Dict[str, Any]]:
+        """Build detailed field error information."""
+        field_errors = []
+
+        for error in errors:
+            field_path = cls._get_field_path(error.get("loc", []))
+            field_error = {
+                "field": field_path,
+                "message": error.get("msg", "Invalid value"),
+                "type": error.get("type", "unknown"),
+                "context": error.get("ctx", {}),
+            }
+
+            # Add input value if available
+            if "input" in error:
+                field_error["input"] = error["input"]
+
+            field_errors.append(field_error)
+
+        return field_errors
+
+    @classmethod
+    def _get_field_path(cls, loc: Sequence[Any]) -> str:
+        """Convert location list to field path string."""
+        return ".".join(str(part) for part in loc) if loc else ""

awesome_errors/converters/python_converter.py

@@ -0,0 +1,80 @@
+from typing import Dict, Type, Tuple
+
+from ..core.error_codes import ErrorCode
+from ..core.exceptions import AppError, ValidationError, AuthError, NotFoundError
+from .generic import generic_error_handler
+
+
+class PythonErrorConverter:
+    """Convert standard Python exceptions to application errors."""
+
+    # Mapping of Python exceptions to (ErrorCode, message) tuples
+    EXCEPTION_MAP: Dict[Type[Exception], Tuple[ErrorCode, str]] = {
+        # Value errors
+        ValueError: (ErrorCode.INVALID_INPUT, "Invalid value provided"),
+        TypeError: (ErrorCode.INVALID_INPUT, "Invalid type provided"),
+        AttributeError: (ErrorCode.INVALID_INPUT, "Invalid attribute access"),
+        # Key/Index errors
+        KeyError: (ErrorCode.RESOURCE_NOT_FOUND, "Key not found"),
+        IndexError: (ErrorCode.RESOURCE_NOT_FOUND, "Index out of range"),
+        # Permission errors
+        PermissionError: (ErrorCode.AUTH_PERMISSION_DENIED, "Permission denied"),
+        # File errors
+        FileNotFoundError: (ErrorCode.RESOURCE_NOT_FOUND, "File not found"),
+        # Arithmetic errors
+        ZeroDivisionError: (ErrorCode.INVALID_INPUT, "Division by zero"),
+        ArithmeticError: (ErrorCode.INVALID_INPUT, "Arithmetic error"),
+        # System errors
+        MemoryError: (ErrorCode.INTERNAL_ERROR, "Memory error"),
+        RecursionError: (ErrorCode.INTERNAL_ERROR, "Maximum recursion depth exceeded"),
+        # Connection errors
+        ConnectionError: (ErrorCode.DB_CONNECTION_ERROR, "Connection error"),
+        TimeoutError: (ErrorCode.DB_CONNECTION_ERROR, "Operation timed out"),
+    }
+
+    @classmethod
+    def convert(cls, error: Exception) -> AppError:
+        """
+        Convert Python exception to AppError.
+
+        Args:
+            error: Python exception
+
+        Returns:
+            AppError instance
+        """
+        error_type = type(error)
+
+        # Check if we have a specific mapping
+        for exc_type, (code, default_message) in cls.EXCEPTION_MAP.items():
+            if issubclass(error_type, exc_type):
+                return cls._create_app_error(error, code, default_message)
+
+        # Default to internal error
+        return generic_error_handler(error)
+
+    @classmethod
+    def _create_app_error(
+        cls, error: Exception, code: ErrorCode, default_message: str
+    ) -> AppError:
+        """Create appropriate AppError subclass."""
+        message = str(error) or default_message
+        details = {"exception_type": type(error).__name__}
+
+        # Add specific details based on exception type
+        if isinstance(error, KeyError):
+            details["key"] = str(error).strip("'\"")
+            return NotFoundError(resource="key", resource_id=details["key"], code=code)
+
+        elif isinstance(error, FileNotFoundError):
+            details["filename"] = error.filename
+            return NotFoundError(resource="file", resource_id=error.filename, code=code)
+
+        elif isinstance(error, (ValueError, TypeError, AttributeError)):
+            return ValidationError(message=message, code=code)
+
+        elif isinstance(error, PermissionError):
+            return AuthError(message=message, code=code)
+
+        # Default to AppError
+        return AppError(code=code, message=message, details=details)

awesome_errors/converters/sql_converter.py

@@ -0,0 +1,258 @@
+import re
+from typing import Any, Dict, Optional, Tuple
+
+from ..core.error_codes import ErrorCode
+from ..core.exceptions import DatabaseError
+
+
+class SQLErrorConverter:
+    """Convert SQLAlchemy errors to application errors."""
+
+    # Regex patterns for common SQL errors
+    SQL_PATTERNS: Dict[re.Pattern, Tuple[ErrorCode, str]] = {
+        # PostgreSQL patterns
+        re.compile(r"duplicate key value violates unique constraint"): (
+            ErrorCode.DB_DUPLICATE_ENTRY,
+            "Record already exists",
+        ),
+        re.compile(r"violates foreign key constraint"): (
+            ErrorCode.DB_INVALID_REFERENCE,
+            "Invalid reference to related record",
+        ),
+        re.compile(r"violates not-null constraint"): (
+            ErrorCode.DB_MISSING_REQUIRED,
+            "Required field is missing",
+        ),
+        re.compile(r"violates check constraint"): (
+            ErrorCode.DB_CONSTRAINT_VIOLATION,
+            "Value violates constraint",
+        ),
+        # MySQL patterns
+        re.compile(r"Duplicate entry .* for key"): (
+            ErrorCode.DB_DUPLICATE_ENTRY,
+            "Record already exists",
+        ),
+        re.compile(
+            r"Cannot add or update a child row: a foreign key constraint fails"
+        ): (ErrorCode.DB_INVALID_REFERENCE, "Invalid reference to related record"),
+        re.compile(r"Column .* cannot be null"): (
+            ErrorCode.DB_MISSING_REQUIRED,
+            "Required field is missing",
+        ),
+        # SQLite patterns
+        re.compile(r"UNIQUE constraint failed"): (
+            ErrorCode.DB_DUPLICATE_ENTRY,
+            "Record already exists",
+        ),
+        re.compile(r"FOREIGN KEY constraint failed"): (
+            ErrorCode.DB_INVALID_REFERENCE,
+            "Invalid reference to related record",
+        ),
+        re.compile(r"NOT NULL constraint failed"): (
+            ErrorCode.DB_MISSING_REQUIRED,
+            "Required field is missing",
+        ),
+    }
+
+    @classmethod
+    def convert(cls, error: Exception) -> DatabaseError:
+        """Convert SQLAlchemy error to DatabaseError.
+
+        SQLAlchemy is imported lazily so the rest of the library can be used
+        without SQLAlchemy installed (install the ``sqlalchemy`` extra to use
+        this converter).
+        """
+        from sqlalchemy.exc import (
+            IntegrityError,
+            DataError,
+            OperationalError,
+            ProgrammingError,
+            DatabaseError as SQLAlchemyDatabaseError,
+        )
+
+        if isinstance(error, IntegrityError):
+            return cls._convert_integrity_error(error)
+        elif isinstance(error, DataError):
+            return cls._convert_data_error(error)
+        elif isinstance(error, OperationalError):
+            return cls._convert_operational_error(error)
+        elif isinstance(error, ProgrammingError):
+            return cls._convert_programming_error(error)
+        elif isinstance(error, SQLAlchemyDatabaseError):
+            return cls._convert_generic_database_error(error)
+        else:
+            return DatabaseError(
+                message=str(error), code=ErrorCode.DB_QUERY_ERROR, sql_error=str(error)
+            )
+
+    @classmethod
+    def _convert_integrity_error(cls, error: Any) -> DatabaseError:
+        """Convert IntegrityError to DatabaseError with detailed field information."""
+        error_str = str(error.orig) if error.orig else str(error)
+
+        # Check patterns
+        for pattern, (code, message) in cls.SQL_PATTERNS.items():
+            if pattern.search(error_str):
+                db_error = DatabaseError(
+                    message=message,
+                    code=code,
+                    sql_error=error_str,
+                    table=cls._extract_table_name(error_str),
+                )
+
+                # Add detailed field information
+                field_name = cls._extract_field_name(error_str)
+                if field_name:
+                    db_error.details["field"] = field_name
+
+                constraint_name = cls._extract_constraint_name(error_str)
+                if constraint_name:
+                    db_error.details["constraint"] = constraint_name
+
+                # For duplicate entries, extract the duplicate value
+                if code == ErrorCode.DB_DUPLICATE_ENTRY:
+                    duplicate_value = cls._extract_duplicate_value(error_str)
+                    if duplicate_value:
+                        db_error.details["duplicate_value"] = duplicate_value
+                        db_error.message = (
+                            f"{message}: {field_name}={duplicate_value}"
+                            if field_name
+                            else f"{message}: {duplicate_value}"
+                        )
+
+                # For missing required fields
+                elif code == ErrorCode.DB_MISSING_REQUIRED and field_name:
+                    db_error.message = f"{message}: {field_name}"
+
+                # For invalid references
+                elif code == ErrorCode.DB_INVALID_REFERENCE and field_name:
+                    db_error.message = f"{message} in field: {field_name}"
+
+                if db_error.details.get("table"):
+                    db_error.details["table"] = db_error.details["table"]
+
+                return db_error
+
+        # Default integrity error
+        return DatabaseError(
+            message="Database integrity constraint violated",
+            code=ErrorCode.DB_CONSTRAINT_VIOLATION,
+            sql_error=error_str,
+        )
+
+    @classmethod
+    def _convert_data_error(cls, error: Any) -> DatabaseError:
+        """Convert DataError to DatabaseError."""
+        return DatabaseError(
+            message="Invalid data format",
+            code=ErrorCode.INVALID_FORMAT,
+            sql_error=str(error.orig) if error.orig else str(error),
+        )
+
+    @classmethod
+    def _convert_operational_error(cls, error: Any) -> DatabaseError:
+        """Convert OperationalError to DatabaseError."""
+        error_str = str(error.orig) if error.orig else str(error)
+
+        if "connection" in error_str.lower():
+            return DatabaseError(
+                message="Database connection error",
+                code=ErrorCode.DB_CONNECTION_ERROR,
+                sql_error=error_str,
+            )
+
+        return DatabaseError(
+            message="Database operational error",
+            code=ErrorCode.DB_QUERY_ERROR,
+            sql_error=error_str,
+        )
+
+    @classmethod
+    def _convert_programming_error(cls, error: Any) -> DatabaseError:
+        """Convert ProgrammingError to DatabaseError."""
+        return DatabaseError(
+            message="Database programming error",
+            code=ErrorCode.DB_QUERY_ERROR,
+            sql_error=str(error.orig) if error.orig else str(error),
+        )
+
+    @classmethod
+    def _convert_generic_database_error(
+        cls, error: Any
+    ) -> DatabaseError:
+        """Convert generic DatabaseError to DatabaseError."""
+        return DatabaseError(
+            message="Database error occurred",
+            code=ErrorCode.DB_QUERY_ERROR,
+            sql_error=str(error.orig) if error.orig else str(error),
+        )
+
+    @classmethod
+    def _extract_table_name(cls, error_str: str) -> Optional[str]:
+        """Extract table name from error string."""
+        # PostgreSQL pattern
+        match = re.search(r'relation "([^"]+)"', error_str)
+        if match:
+            return match.group(1)
+
+        # MySQL pattern
+        match = re.search(r"`([^`]+)`\.`([^`]+)`", error_str)
+        if match:
+            return match.group(2)
+
+        # SQLite pattern
+        match = re.search(r"table (\w+)", error_str)
+        if match:
+            return match.group(1)
+
+        return None
+
+    @classmethod
+    def _extract_field_name(cls, error_str: str) -> Optional[str]:
+        """Extract field/column name from error string."""
+        # PostgreSQL patterns
+        match = re.search(r'column "([^"]+)"', error_str)
+        if match:
+            return match.group(1)
+
+        # MySQL patterns
+        match = re.search(r"Column '([^']+)'", error_str)
+        if match:
+            return match.group(1)
+
+        # SQLite patterns
+        match = re.search(r"column (\w+)", error_str)
+        if match:
+            return match.group(1)
+
+        return None
+
+    @classmethod
+    def _extract_constraint_name(cls, error_str: str) -> Optional[str]:
+        """Extract constraint name from error string."""
+        # PostgreSQL pattern
+        match = re.search(r'constraint "([^"]+)"', error_str)
+        if match:
+            return match.group(1)
+
+        # MySQL pattern
+        match = re.search(r"key '([^']+)'", error_str)
+        if match:
+            return match.group(1)
+
+        return None
+
+    @classmethod
+    def _extract_duplicate_value(cls, error_str: str) -> Optional[str]:
+        """Extract duplicate value from error string."""
+        # PostgreSQL pattern
+        match = re.search(r"Key \([^)]+\)=\(([^)]+)\)", error_str)
+        if match:
+            return match.group(1)
+
+        # MySQL pattern
+        match = re.search(r"Duplicate entry '([^']+)'", error_str)
+        if match:
+            return match.group(1)
+
+        return None