awesome-errors 0.3.0__py3-none-any.whl

awesome_errors/core/renderers.py

@@ -0,0 +1,115 @@
+"""Utilities that render ``AppError`` instances into HTTP payloads."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Callable, Dict, Optional
+
+from ..core.exceptions import AppError
+from .error_response import ErrorDetail, ErrorResponse
+
+
+from datetime import timezone
+
+
+def _isoformat(dt):
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    else:
+        dt = dt.astimezone(timezone.utc)
+    return dt.isoformat().replace("+00:00", "Z")
+
+
+class ErrorResponseFormat(StrEnum):
+    """Supported HTTP error payload shapes."""
+
+    LEGACY = "legacy"
+    RFC7807 = "rfc7807"
+
+
+@dataclass
+class RenderResult:
+    payload: Dict[str, Any]
+    media_type: str
+
+
+class ErrorResponseRenderer:
+    """Render ``AppError`` objects into dictionaries ready for JSON encoding."""
+
+    def __init__(
+        self,
+        format: ErrorResponseFormat = ErrorResponseFormat.LEGACY,
+        *,
+        problem_type_resolver: Optional[Callable[[AppError], str]] = None,
+        problem_extension_builder: Optional[
+            Callable[[AppError], Dict[str, Any]]
+        ] = None,
+    ):
+        self.format = format
+        self._problem_type_resolver = problem_type_resolver
+        self._problem_extension_builder = problem_extension_builder
+
+    def render(
+        self,
+        error: AppError,
+        *,
+        message: str,
+        request: Optional[Any] = None,
+    ) -> RenderResult:
+        if self.format == ErrorResponseFormat.RFC7807:
+            return self._render_problem_detail(error, message=message, request=request)
+        return self._render_legacy(error, message=message)
+
+    def _render_legacy(self, error: AppError, *, message: str) -> RenderResult:
+        detail = ErrorDetail(
+            code=error.code.value,
+            message=message,
+            details=error.details,
+            timestamp=error.timestamp,
+            request_id=error.request_id or "unknown",
+        )
+        envelope = ErrorResponse(error=detail)
+        return RenderResult(payload=envelope.to_dict(), media_type="application/json")
+
+    def _render_problem_detail(
+        self,
+        error: AppError,
+        *,
+        message: str,
+        request: Optional[Any],
+    ) -> RenderResult:
+        problem_type = (
+            self._problem_type_resolver(error)
+            if self._problem_type_resolver
+            else "about:blank"
+        )
+        instance: Optional[str] = None
+        if request is not None:
+            instance = getattr(request, "url", None)
+            if instance is not None:
+                instance = str(instance)
+
+        payload: Dict[str, Any] = {
+            "type": problem_type,
+            "title": error.message,
+            "status": error.status_code,
+            "detail": message,
+            "instance": instance,
+            "code": error.code.value,
+            "timestamp": _isoformat(error.timestamp),
+            "request_id": error.request_id,
+            "details": error.details,
+        }
+        extensions = (
+            self._problem_extension_builder(error)
+            if self._problem_extension_builder
+            else None
+        )
+        if extensions:
+            payload.update(extensions)
+
+        return RenderResult(
+            payload=payload,
+            media_type="application/problem+json",
+        )

awesome_errors/i18n/locales/en/errors.json

@@ -0,0 +1,32 @@
+{
+  "UNKNOWN_ERROR": "An unknown error occurred",
+  "INTERNAL_ERROR": "Internal server error",
+  "VALIDATION_FAILED": "Validation failed",
+  "INVALID_INPUT": "Invalid input provided",
+  "MISSING_REQUIRED_FIELD": "Required field is missing",
+  "INVALID_FORMAT": "Invalid format",
+  "AUTH_REQUIRED": "Authentication required",
+  "AUTH_INVALID_TOKEN": "Invalid authentication token",
+  "AUTH_TOKEN_EXPIRED": "Authentication token has expired",
+  "AUTH_PERMISSION_DENIED": "Permission denied",
+  "AUTH_INSUFFICIENT_PRIVILEGES": "Insufficient privileges",
+  "RESOURCE_NOT_FOUND": "Resource not found",
+  "USER_NOT_FOUND": "User not found",
+  "ENTITY_NOT_FOUND": "Entity not found",
+  "DB_CONNECTION_ERROR": "Database connection error",
+  "DB_QUERY_ERROR": "Database query error",
+  "DB_CONSTRAINT_VIOLATION": "Database constraint violated",
+  "DB_DUPLICATE_ENTRY": "Duplicate entry",
+  "DB_INVALID_REFERENCE": "Invalid reference",
+  "DB_MISSING_REQUIRED": "Missing required field",
+  "BUSINESS_RULE_VIOLATION": "Business rule violated",
+  "INSUFFICIENT_BALANCE": "Insufficient balance",
+  "OPERATION_NOT_ALLOWED": "Operation not allowed",
+  "CUSTOM_ERROR": "Custom error in English",
+  "CUSTOM_ERROR_1": "First custom error",
+  "CUSTOM_ERROR_2": "Second custom error",
+  "USER_ERROR": "User {username} has {error_count} errors",
+  "TEMPLATE_ERROR": "User {username} has {missing_param} errors",
+  "SIMPLE_ERROR": "Simple error message",
+  "CUSTOM_TEST_ERROR": "Custom test error message"
+}

awesome_errors/i18n/locales/test/errors.json

@@ -0,0 +1,4 @@
+{
+  "UNICODE_ERROR": "Помилка з україськими символами 🇺🇦",
+  "EMOJI_ERROR": "Error with emojis 😊✨🚀"
+}

awesome_errors/i18n/locales/uk/errors.json

@@ -0,0 +1,26 @@
+{
+  "UNKNOWN_ERROR": "Сталася невідома помилка",
+  "INTERNAL_ERROR": "Внутрішня помилка сервера",
+  "VALIDATION_FAILED": "Помилка валідації",
+  "INVALID_INPUT": "Недопустимі вхідні дані",
+  "MISSING_REQUIRED_FIELD": "Відсутнє обов'язкове поле",
+  "INVALID_FORMAT": "Невірний формат",
+  "AUTH_REQUIRED": "Потрібна автентифікація",
+  "AUTH_INVALID_TOKEN": "Недійсний токен автентифікації",
+  "AUTH_TOKEN_EXPIRED": "Термін дії токена закінчився",
+  "AUTH_PERMISSION_DENIED": "Доступ заборонено",
+  "AUTH_INSUFFICIENT_PRIVILEGES": "Недостатньо прав",
+  "RESOURCE_NOT_FOUND": "Ресурс не знайдено",
+  "USER_NOT_FOUND": "Користувача не знайдено",
+  "ENTITY_NOT_FOUND": "Об'єкт не знайдено",
+  "DB_CONNECTION_ERROR": "Помилка підключення до бази даних",
+  "DB_QUERY_ERROR": "Помилка запиту до бази даних",
+  "DB_CONSTRAINT_VIOLATION": "Порушено обмеження бази даних",
+  "DB_DUPLICATE_ENTRY": "Дублюючий запис",
+  "DB_INVALID_REFERENCE": "Недійсне посилання",
+  "DB_MISSING_REQUIRED": "Відсутнє обов'язкове поле",
+  "BUSINESS_RULE_VIOLATION": "Порушено бізнес-правило",
+  "INSUFFICIENT_BALANCE": "Недостатній баланс",
+  "OPERATION_NOT_ALLOWED": "Операція не дозволена",
+  "CUSTOM_TEST_ERROR": "Повідомлення про власну тестову помилку"
+}

awesome_errors/i18n/translator.py

@@ -0,0 +1,150 @@
+import json
+from pathlib import Path
+from typing import Dict, Optional, Any
+
+
+class ErrorTranslator:
+    """Translator for error messages with i18n support."""
+
+    def __init__(self, locales_dir: Optional[Path] = None, default_locale: str = "en"):
+        """
+        Initialize translator.
+
+        Args:
+            locales_dir: Directory containing locale files
+            default_locale: Default locale to use
+        """
+        self.locales_dir = locales_dir or Path(__file__).parent / "locales"
+        self.default_locale = default_locale
+        self._translations: Dict[str, Dict[str, str]] = {}
+        self._load_translations()
+
+    def _load_translations(self) -> None:
+        """Load all translation files."""
+        if not self.locales_dir.exists():
+            self.locales_dir.mkdir(parents=True, exist_ok=True)
+            # Create default English translations
+            self._create_default_translations()
+
+        for locale_file in self.locales_dir.glob("*/errors.json"):
+            locale = locale_file.parent.name
+            try:
+                with open(locale_file, "r", encoding="utf-8") as f:
+                    self._translations[locale] = json.load(f)
+            except Exception:
+                # Skip invalid files
+                pass
+
+    def _create_default_translations(self) -> None:
+        """Create default English translations."""
+        en_dir = self.locales_dir / "en"
+        en_dir.mkdir(exist_ok=True)
+
+        default_translations = {
+            # General errors
+            "UNKNOWN_ERROR": "An unknown error occurred",
+            "INTERNAL_ERROR": "Internal server error",
+            # Validation errors
+            "VALIDATION_FAILED": "Validation failed",
+            "INVALID_INPUT": "Invalid input provided",
+            "MISSING_REQUIRED_FIELD": "Required field is missing",
+            "INVALID_FORMAT": "Invalid format",
+            # Authentication errors
+            "AUTH_REQUIRED": "Authentication required",
+            "AUTH_INVALID_TOKEN": "Invalid authentication token",
+            "AUTH_TOKEN_EXPIRED": "Authentication token has expired",
+            # Authorization errors
+            "AUTH_PERMISSION_DENIED": "Permission denied",
+            "AUTH_INSUFFICIENT_PRIVILEGES": "Insufficient privileges",
+            # Not found errors
+            "RESOURCE_NOT_FOUND": "Resource not found",
+            "USER_NOT_FOUND": "User not found",
+            "ENTITY_NOT_FOUND": "Entity not found",
+            # Database errors
+            "DB_CONNECTION_ERROR": "Database connection error",
+            "DB_QUERY_ERROR": "Database query error",
+            "DB_CONSTRAINT_VIOLATION": "Database constraint violated",
+            "DB_DUPLICATE_ENTRY": "Duplicate entry",
+            "DB_INVALID_REFERENCE": "Invalid reference",
+            "DB_MISSING_REQUIRED": "Missing required field",
+            # Business logic errors
+            "BUSINESS_RULE_VIOLATION": "Business rule violated",
+            "INSUFFICIENT_BALANCE": "Insufficient balance",
+            "OPERATION_NOT_ALLOWED": "Operation not allowed",
+        }
+
+        with open(en_dir / "errors.json", "w", encoding="utf-8") as f:
+            json.dump(default_translations, f, indent=2, ensure_ascii=False)
+
+        self._translations["en"] = default_translations
+
+    def translate(
+        self,
+        error_code: str,
+        locale: Optional[str] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """
+        Translate error code to message.
+
+        Args:
+            error_code: Error code to translate
+            locale: Locale to use (e.g., 'en', 'uk')
+            params: Parameters for message formatting
+
+        Returns:
+            Translated message
+        """
+        locale = locale or self.default_locale
+
+        # Try requested locale
+        if locale in self._translations:
+            message = self._translations[locale].get(error_code)
+            if message:
+                return self._format_message(message, params)
+
+        # Fallback to English if available and different from requested locale (case sensitive)
+        if "en" in self._translations and locale.lower() != "en":
+            message = self._translations["en"].get(error_code)
+            if message:
+                return self._format_message(message, params)
+
+        # Return error code if no translation found
+        return error_code
+
+    def _format_message(self, message: str, params: Optional[Dict[str, Any]]) -> str:
+        """Format message with parameters."""
+        if not params:
+            return message
+
+        try:
+            return message.format(**params)
+        except Exception:
+            # Return unformatted message if formatting fails
+            return message
+
+    def add_translations(
+        self, locale: str, translations: Dict[str, str], *, persist: bool = True
+    ) -> None:
+        """Add or update translations for a locale.
+
+        Args:
+            locale: Locale identifier
+            translations: Mapping of error codes to translated messages
+            persist: Persist changes to disk. Set to ``False`` for ephemeral usage.
+        """
+        if locale not in self._translations:
+            self._translations[locale] = {}
+
+        self._translations[locale].update(translations)
+
+        if persist:
+            locale_dir = self.locales_dir / locale
+            locale_dir.mkdir(exist_ok=True)
+
+            with open(locale_dir / "errors.json", "w", encoding="utf-8") as f:
+                json.dump(self._translations[locale], f, indent=2, ensure_ascii=False)
+
+    def get_available_locales(self) -> list[str]:
+        """Get list of available locales."""
+        return list(self._translations.keys())

awesome_errors/integrations/__init__.py

@@ -0,0 +1,11 @@
+from .fastapi_auto_docs import (
+    setup_automatic_error_docs,
+    apply_auto_error_docs_to_router,
+    auto_analyze_errors,
+)
+
+__all__ = [
+    "setup_automatic_error_docs",
+    "apply_auto_error_docs_to_router",
+    "auto_analyze_errors",
+]

awesome_errors/integrations/fastapi_auto_docs.py

@@ -0,0 +1,220 @@
+"""
+FastAPI automatic error documentation integration.
+Automatically analyzes routes and adds error response schemas to OpenAPI docs.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def auto_analyze_errors(func):
+    from ..analysis.decorators import analyze_errors
+
+    decorated_func = analyze_errors()(func)
+    decorated_func._auto_openapi = True
+    return decorated_func
+
+
+def setup_automatic_error_docs(app, **kwargs):
+    """
+    Setup automatic error documentation for all FastAPI routes.
+
+    This function analyzes all route functions using AST analysis to find
+    possible errors and automatically adds comprehensive error response
+    schemas to the OpenAPI documentation.
+
+    Args:
+        app: FastAPI application instance
+        **kwargs: Additional configuration options
+            - include_http_exceptions: Whether to analyze HTTPException (default: True)
+            - max_depth: Maximum analysis depth for function calls (default: 3)
+            - exclude_paths: List of path patterns to exclude from analysis
+    """
+    try:
+        from fastapi import FastAPI
+
+        if not isinstance(app, FastAPI):
+            logger.warning("setup_automatic_error_docs expects a FastAPI app instance")
+            return
+
+        logger.info("Setting up automatic error documentation for FastAPI routes...")
+
+        # Apply to all routes in the app
+        _apply_auto_error_docs_to_app(app, **kwargs)
+
+        logger.info("Automatic error documentation setup complete")
+
+    except ImportError:
+        logger.warning("FastAPI not available, skipping automatic error documentation")
+    except Exception as e:
+        logger.error(f"Failed to setup automatic error documentation: {e}")
+
+
+def _apply_auto_error_docs_to_app(app, **kwargs):
+    """Apply automatic error documentation to all routes in FastAPI app."""
+    from ..analysis.error_analyzer import ErrorAnalyzer
+    from ..analysis.decorators import _generate_openapi_responses
+
+    exclude_paths = kwargs.get("exclude_paths", [])
+    max_depth = kwargs.get("max_depth", 3)
+
+    routes_processed = 0
+    errors_found = 0
+
+    for route in app.routes:
+        # Skip if path is in exclude list
+        if any(pattern in route.path for pattern in exclude_paths):
+            continue
+
+        if hasattr(route, "endpoint") and hasattr(route, "methods"):
+            try:
+                endpoint_func = route.endpoint
+
+                # Analyze the function for possible errors
+                analyzer = ErrorAnalyzer(
+                    endpoint_func, max_depth=max_depth, analyze_decorators=True
+                )
+                analysis = analyzer.analyze()
+                error_codes = analysis.get("error_codes", set())
+
+                if error_codes:
+                    # Generate OpenAPI responses
+                    openapi_responses = _generate_openapi_responses(error_codes, {})
+
+                    # Apply responses to the route
+                    if not hasattr(route, "responses"):
+                        route.responses = {}
+
+                    # Merge with existing responses (don't overwrite existing)
+                    for status_code, response_schema in openapi_responses.items():
+                        if status_code not in route.responses:
+                            route.responses[status_code] = response_schema
+
+                    routes_processed += 1
+                    errors_found += len(error_codes)
+
+                    logger.debug(
+                        f"Applied error responses to {route.path} "
+                        f"({', '.join(route.methods)}): {list(openapi_responses.keys())}"
+                    )
+
+            except Exception as e:
+                logger.warning(f"Failed to analyze errors for route {route.path}: {e}")
+
+        # Also handle included routers
+        elif hasattr(route, "app") and hasattr(route.app, "routes"):
+            _process_sub_routes(route.app.routes, exclude_paths, max_depth)
+
+    logger.info(
+        f"Processed {routes_processed} routes, found {errors_found} total error codes"
+    )
+
+
+def _process_sub_routes(routes, exclude_paths, max_depth):
+    """Process routes in sub-applications/routers."""
+    from ..analysis.error_analyzer import ErrorAnalyzer
+    from ..analysis.decorators import _generate_openapi_responses
+
+    for sub_route in routes:
+        # Skip if path is in exclude list
+        if any(pattern in sub_route.path for pattern in exclude_paths):
+            continue
+
+        if hasattr(sub_route, "endpoint") and hasattr(sub_route, "methods"):
+            try:
+                endpoint_func = sub_route.endpoint
+
+                analyzer = ErrorAnalyzer(
+                    endpoint_func, max_depth=max_depth, analyze_decorators=True
+                )
+                analysis = analyzer.analyze()
+                error_codes = analysis.get("error_codes", set())
+
+                if error_codes:
+                    openapi_responses = _generate_openapi_responses(error_codes, {})
+
+                    if not hasattr(sub_route, "responses"):
+                        sub_route.responses = {}
+
+                    # Merge with existing responses
+                    for status_code, response_schema in openapi_responses.items():
+                        if status_code not in sub_route.responses:
+                            sub_route.responses[status_code] = response_schema
+
+                    logger.debug(
+                        f"Applied error responses to sub-route {sub_route.path}: "
+                        f"{list(openapi_responses.keys())}"
+                    )
+
+            except Exception as e:
+                logger.warning(
+                    f"Failed to analyze errors for sub-route {sub_route.path}: {e}"
+                )
+
+
+def apply_auto_error_docs_to_router(router, **kwargs):
+    """
+    Apply automatic error documentation to a specific FastAPI router.
+
+    Args:
+        router: FastAPI APIRouter instance
+        **kwargs: Configuration options (same as setup_automatic_error_docs)
+    """
+    try:
+        from fastapi import APIRouter
+
+        if not isinstance(router, APIRouter):
+            logger.warning(
+                "apply_auto_error_docs_to_router expects an APIRouter instance"
+            )
+            return
+
+        _apply_auto_error_docs_to_routes(router.routes, **kwargs)
+
+    except ImportError:
+        logger.warning("FastAPI not available for router error documentation")
+    except Exception as e:
+        logger.error(f"Failed to apply error docs to router: {e}")
+
+
+def _apply_auto_error_docs_to_routes(routes, **kwargs):
+    """Apply automatic error documentation to a list of routes."""
+    from ..analysis.error_analyzer import ErrorAnalyzer
+    from ..analysis.decorators import _generate_openapi_responses
+
+    exclude_paths = kwargs.get("exclude_paths", [])
+    max_depth = kwargs.get("max_depth", 3)
+
+    for route in routes:
+        # Skip if path is in exclude list
+        if any(pattern in route.path for pattern in exclude_paths):
+            continue
+
+        if hasattr(route, "endpoint") and hasattr(route, "methods"):
+            try:
+                endpoint_func = route.endpoint
+
+                analyzer = ErrorAnalyzer(
+                    endpoint_func, max_depth=max_depth, analyze_decorators=True
+                )
+                analysis = analyzer.analyze()
+                error_codes = analysis.get("error_codes", set())
+
+                if error_codes:
+                    openapi_responses = _generate_openapi_responses(error_codes, {})
+
+                    if not hasattr(route, "responses"):
+                        route.responses = {}
+
+                    # Merge with existing responses
+                    for status_code, response_schema in openapi_responses.items():
+                        if status_code not in route.responses:
+                            route.responses[status_code] = response_schema
+
+                    logger.debug(
+                        f"Applied error responses to {route.path}: {list(openapi_responses.keys())}"
+                    )
+
+            except Exception as e:
+                logger.warning(f"Failed to analyze errors for route {route.path}: {e}")

awesome_errors/litestar_utils.py

@@ -0,0 +1,55 @@
+"""Litestar-specific helpers for API error metadata."""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Tuple, Type, TypeVar, cast
+
+from .core.exceptions import APIError
+
+ErrorType = TypeVar("ErrorType", bound=APIError)
+
+
+def _is_http_route_handler(obj: object) -> bool:
+    try:  # pragma: no cover - optional dependency
+        from litestar.handlers.http_handlers import HTTPRouteHandler
+    except ImportError:  # pragma: no cover
+        return False
+    return isinstance(obj, HTTPRouteHandler)
+
+
+def raises_from(*errors: Type[APIError]) -> list[Type[APIError]]:
+    """Return a Litestar-compatible raises list from APIError classes."""
+    return list(errors)
+
+
+def errors(*errs: Type[APIError]):
+    """Attach OpenAPI error responses to a Litestar handler."""
+
+    def wrap(obj: Any) -> Any:
+        if _is_http_route_handler(obj):
+            current = getattr(obj, "raises", None) or []
+            if isinstance(current, dict):
+                current = []
+            obj.raises = cast(Any, [*list(current), *errs])
+            return obj
+        setattr(obj, "__api_errors__", errs)
+        return obj
+
+    return wrap
+
+
+def apply_api_errors(handlers: Iterable[object]) -> None:
+    """Apply deferred error metadata to handlers (optional helper)."""
+    for handler in handlers:
+        if not _is_http_route_handler(handler):
+            continue
+        typed_handler = cast(Any, handler)
+        errs: Tuple[Type[APIError], ...] | None = getattr(
+            typed_handler.fn, "__api_errors__", None
+        )
+        if not errs:
+            continue
+        current = typed_handler.raises or []
+        if isinstance(current, dict):
+            current = []
+        typed_handler.raises = cast(Any, [*list(current), *errs])