awesome-errors 0.3.0__py3-none-any.whl

awesome_errors/converters/universal_converter.py

@@ -0,0 +1,123 @@
+from typing import Any, Optional
+
+from ..core.error_codes import ErrorCode
+from ..core.exceptions import AppError
+from .generic import generic_error_handler
+from .python_converter import PythonErrorConverter
+from .sql_converter import SQLErrorConverter
+
+SQLAlchemyErrorType: type[Exception] | None = None
+try:  # pragma: no cover - optional dependency
+    from sqlalchemy.exc import SQLAlchemyError as _LoadedSQLAlchemyError
+except ImportError:  # pragma: no cover
+    pass
+else:  # pragma: no cover
+    SQLAlchemyErrorType = _LoadedSQLAlchemyError
+
+PydanticValidationErrorType: type[Exception] | None = None
+try:  # pragma: no cover - optional dependency
+    from pydantic import ValidationError as _LoadedPydanticValidationError
+except ImportError:  # pragma: no cover
+    pass
+else:  # pragma: no cover
+    PydanticValidationErrorType = _LoadedPydanticValidationError
+
+_PydanticErrorConverter: Any = None
+try:  # pragma: no cover - optional dependency
+    from .pydantic_converter import PydanticErrorConverter as _LoadedPydanticErrorConverter
+except ImportError:  # pragma: no cover
+    pass
+else:  # pragma: no cover
+    _PydanticErrorConverter = _LoadedPydanticErrorConverter
+
+
+class UniversalErrorConverter:
+    """Universal error converter that handles any type of exception."""
+
+    @classmethod
+    def convert(cls, error: Exception, debug: bool = False) -> AppError:
+        """
+        Convert any exception to AppError.
+
+        Args:
+            error: Any exception
+            debug: Include debug information
+
+        Returns:
+            AppError instance with appropriate details
+        """
+        # Check if it's already an AppError
+        if isinstance(error, AppError):
+            return error
+
+        # Pydantic validation errors
+        if PydanticValidationErrorType is not None and isinstance(
+            error, PydanticValidationErrorType
+        ):
+            if _PydanticErrorConverter is None:
+                raise ImportError(
+                    "Install 'awesome-errors[pydantic]' to convert Pydantic validation errors."
+                ) from None
+            return _PydanticErrorConverter.convert(error)
+
+        # SQLAlchemy errors
+        if SQLAlchemyErrorType is not None and isinstance(error, SQLAlchemyErrorType):
+            return SQLErrorConverter.convert(error)
+
+        # Standard Python exceptions
+        if type(error) in PythonErrorConverter.EXCEPTION_MAP:
+            return PythonErrorConverter.convert(error)
+
+        # Handle other specific error types
+        app_error = cls._handle_special_cases(error)
+        if app_error:
+            return app_error
+
+        # Default handling for unknown errors
+        return generic_error_handler(error, debug)
+
+    @classmethod
+    def _handle_special_cases(cls, error: Exception) -> Optional[AppError]:
+        """Handle special error cases."""
+        error_type = type(error).__name__
+        error_str = str(error)
+
+        # Handle HTTP-related errors
+        if "HTTPError" in error_type:
+            return AppError(
+                code=ErrorCode.INTERNAL_ERROR,
+                message="HTTP request failed",
+                details={"error_type": error_type, "error": error_str},
+            )
+
+        # Handle JSON errors
+        if "JSONDecodeError" in error_type:
+            return AppError(
+                code=ErrorCode.INVALID_FORMAT,
+                message="Invalid JSON format",
+                details={"error_type": error_type, "error": error_str},
+            )
+
+        # Handle import errors
+        if isinstance(error, (ImportError, ModuleNotFoundError)):
+            return AppError(
+                code=ErrorCode.INTERNAL_ERROR,
+                message="Missing required module",
+                details={
+                    "module": error.name if hasattr(error, "name") else "unknown",
+                    "error": error_str,
+                },
+            )
+
+        return None
+
+    @staticmethod
+    def _is_serializable(value: Any) -> bool:
+        """Check if value can be safely serialized."""
+        try:
+            import json
+
+            json.dumps(value)
+            return True
+        except Exception:
+            return False

awesome_errors/core/error_codes.py

@@ -0,0 +1,104 @@
+from enum import StrEnum
+from typing import Dict
+
+
+class ErrorCode(StrEnum):
+    # General errors
+    UNKNOWN_ERROR = "UNKNOWN_ERROR"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+    # Validation errors (400)
+    VALIDATION_FAILED = "VALIDATION_FAILED"
+    INVALID_INPUT = "INVALID_INPUT"
+    MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD"
+    INVALID_FORMAT = "INVALID_FORMAT"
+
+    # Authentication errors (401)
+    AUTH_REQUIRED = "AUTH_REQUIRED"
+    AUTH_INVALID_TOKEN = "AUTH_INVALID_TOKEN"
+    AUTH_TOKEN_EXPIRED = "AUTH_TOKEN_EXPIRED"
+    REFRESH_TOKEN_REUSE = "REFRESH_TOKEN_REUSE"
+    SESSION_EXPIRED = "SESSION_EXPIRED"
+
+    # Authorization errors (403)
+    AUTH_PERMISSION_DENIED = "AUTH_PERMISSION_DENIED"
+    AUTH_INSUFFICIENT_PRIVILEGES = "AUTH_INSUFFICIENT_PRIVILEGES"
+
+    # Not found errors (404)
+    RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"
+    RESOURCE_ALREADY_EXISTS = "RESOURCE_ALREADY_EXISTS"
+    USER_NOT_FOUND = "USER_NOT_FOUND"
+    ENTITY_NOT_FOUND = "ENTITY_NOT_FOUND"
+    OAUTH_PROVIDER_UNKNOWN = "OAUTH_PROVIDER_UNKNOWN"
+
+    # Database errors (500)
+    DB_CONNECTION_ERROR = "DB_CONNECTION_ERROR"
+    DB_QUERY_ERROR = "DB_QUERY_ERROR"
+    DB_TRANSACTION_ERROR = "DB_TRANSACTION_ERROR"
+    DB_CONSTRAINT_VIOLATION = "DB_CONSTRAINT_VIOLATION"
+    DB_DUPLICATE_ENTRY = "DB_DUPLICATE_ENTRY"
+    DB_INVALID_REFERENCE = "DB_INVALID_REFERENCE"
+    DB_MISSING_REQUIRED = "DB_MISSING_REQUIRED"
+
+    # Business logic errors
+    BUSINESS_RULE_VIOLATION = "BUSINESS_RULE_VIOLATION"
+    INSUFFICIENT_BALANCE = "INSUFFICIENT_BALANCE"
+    OPERATION_NOT_ALLOWED = "OPERATION_NOT_ALLOWED"
+    RATE_LIMIT_EXCEEDED = "RATE_LIMIT_EXCEEDED"
+    SERVICE_UNAVAILABLE = "SERVICE_UNAVAILABLE"
+
+    @classmethod
+    def _missing_(cls, value):
+        """Create new ErrorCode for unknown values."""
+        if isinstance(value, str):
+            # Create a pseudo member for custom values
+            pseudo_member = str.__new__(cls, value)
+            pseudo_member._name_ = value
+            pseudo_member._value_ = value
+            return pseudo_member
+        return None
+
+
+ERROR_HTTP_STATUS_MAP: Dict[ErrorCode, int] = {
+    # 400 Bad Request
+    ErrorCode.VALIDATION_FAILED: 400,
+    ErrorCode.INVALID_INPUT: 400,
+    ErrorCode.MISSING_REQUIRED_FIELD: 400,
+    ErrorCode.INVALID_FORMAT: 400,
+    # 401 Unauthorized
+    ErrorCode.AUTH_REQUIRED: 401,
+    ErrorCode.AUTH_INVALID_TOKEN: 401,
+    ErrorCode.AUTH_TOKEN_EXPIRED: 401,
+    ErrorCode.REFRESH_TOKEN_REUSE: 401,
+    ErrorCode.SESSION_EXPIRED: 401,
+    # 403 Forbidden
+    ErrorCode.AUTH_PERMISSION_DENIED: 403,
+    ErrorCode.AUTH_INSUFFICIENT_PRIVILEGES: 403,
+    # 404 Not Found
+    ErrorCode.RESOURCE_NOT_FOUND: 404,
+    ErrorCode.RESOURCE_ALREADY_EXISTS: 409,
+    ErrorCode.USER_NOT_FOUND: 404,
+    ErrorCode.ENTITY_NOT_FOUND: 404,
+    ErrorCode.OAUTH_PROVIDER_UNKNOWN: 404,
+    # 422 Unprocessable Entity
+    ErrorCode.BUSINESS_RULE_VIOLATION: 422,
+    ErrorCode.INSUFFICIENT_BALANCE: 422,
+    ErrorCode.OPERATION_NOT_ALLOWED: 422,
+    ErrorCode.RATE_LIMIT_EXCEEDED: 429,
+    # 500 Internal Server Error
+    ErrorCode.UNKNOWN_ERROR: 500,
+    ErrorCode.INTERNAL_ERROR: 500,
+    ErrorCode.SERVICE_UNAVAILABLE: 503,
+    ErrorCode.DB_CONNECTION_ERROR: 500,
+    ErrorCode.DB_QUERY_ERROR: 500,
+    ErrorCode.DB_TRANSACTION_ERROR: 500,
+    ErrorCode.DB_CONSTRAINT_VIOLATION: 409,  # Conflict
+    ErrorCode.DB_DUPLICATE_ENTRY: 409,
+    ErrorCode.DB_INVALID_REFERENCE: 422,
+    ErrorCode.DB_MISSING_REQUIRED: 422,
+}
+
+
+def get_http_status(error_code: ErrorCode) -> int:
+    """Get HTTP status code for an error code."""
+    return ERROR_HTTP_STATUS_MAP.get(error_code, 500)

awesome_errors/core/error_response.py

@@ -0,0 +1,61 @@
+"""Core error response models built on msgspec."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any, Dict, Mapping
+
+import msgspec
+
+
+def _now_utc() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class ErrorDetail(msgspec.Struct, kw_only=True, omit_defaults=True):
+    """Serializable representation of an application error."""
+
+    code: str
+    message: str
+    request_id: str
+    details: Dict[str, Any] = msgspec.field(default_factory=dict)
+    timestamp: datetime = msgspec.field(default_factory=_now_utc)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to builtin types, ensuring ISO timestamps."""
+        data = msgspec.to_builtins(self, builtin_types=None)
+        timestamp = data.get("timestamp")
+        if isinstance(timestamp, datetime):
+            data["timestamp"] = timestamp.isoformat().replace("+00:00", "Z")
+        elif isinstance(timestamp, str):
+            data["timestamp"] = timestamp
+        else:
+            data["timestamp"] = _now_utc().isoformat().replace("+00:00", "Z")
+        return data
+
+
+class ErrorResponse(msgspec.Struct, kw_only=True, omit_defaults=True):
+    """Legacy `{"error": {...}}` envelope."""
+
+    error: ErrorDetail
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {"error": self.error.to_dict()}
+
+
+def error_detail_from_mapping(data: Mapping[str, Any]) -> ErrorDetail:
+    """Construct an ``ErrorDetail`` from mapping data."""
+    timestamp = data.get("timestamp")
+    if isinstance(timestamp, str):
+        try:
+            timestamp = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+        except ValueError:
+            timestamp = _now_utc()
+
+    return ErrorDetail(
+        code=str(data.get("code", "UNKNOWN_ERROR")),
+        message=str(data.get("message", "")),
+        details=dict(data.get("details") or {}),
+        timestamp=timestamp if isinstance(timestamp, datetime) else _now_utc(),
+        request_id=str(data.get("request_id", "")),
+    )