crypticorn-utils 0.1.0rc1__py3-none-any.whl → 1.0.0rc1__py3-none-any.whl

crypticorn_utils/exceptions.py

@@ -1,29 +1,34 @@
-import json
 import logging
-from typing import Any, Optional
+from enum import Enum, StrEnum
+from typing import Any, Callable, Optional, Self, TypedDict, Union
 
 from crypticorn_utils.errors import (
-    ApiError,
-    ApiErrorIdentifier,
-    ApiErrorLevel,
-    ApiErrorType,
+    ErrorLevel,
+    ErrorType,
 )
 from fastapi import FastAPI
+from fastapi import HTTPException
 from fastapi import HTTPException as FastAPIHTTPException
-from fastapi import Request
+from fastapi import Request, WebSocketException
 from fastapi.exceptions import RequestValidationError, ResponseValidationError
 from fastapi.responses import JSONResponse
 from pydantic import BaseModel, Field
 
-try:
-    from enum import StrEnum
-except ImportError:
-    from strenum import StrEnum
-
 _logger = logging.getLogger("crypticorn")
 
+TError = TypedDict(
+    "TError",
+    {
+        "identifier": str,
+        "type": ErrorType,
+        "level": ErrorLevel,
+        "http_code": int,
+        "websocket_code": int,
+    },
+)
+
 
-class _ExceptionType(StrEnum):
+class ExceptionType(StrEnum):
     """The protocol the exception is called from"""
 
     HTTP = "http"
@@ -34,150 +39,250 @@ class ExceptionDetail(BaseModel):
     """Exception details returned to the client."""
 
     message: Optional[str] = Field(None, description="An additional error message")
-    code: ApiErrorIdentifier = Field(..., description="The unique error code")
-    type: ApiErrorType = Field(..., description="The type of error")
-    level: ApiErrorLevel = Field(..., description="The level of the error")
+    code: str = Field(..., description="The unique error code")
+    type: ErrorType = Field(..., description="The type of error")
+    level: ErrorLevel = Field(..., description="The level of the error")
     status_code: int = Field(..., description="The HTTP status code")
     details: Any = Field(None, description="Additional details about the error")
 
 
-class ExceptionContent(BaseModel):
-    """Exception content used when raising an exception."""
+class ExceptionHandler:
+    """This class is used to handle errors and exceptions. It is used to build exceptions and raise them.
 
-    error: ApiError = Field(..., description="The unique error code")
-    message: Optional[str] = Field(None, description="An additional error message")
-    details: Any = Field(None, description="Additional details about the error")
+    - Register the exception handlers to the FastAPI app.
+    - Configure the instance with a callback to get the error object from the error identifier.
+    - Build exceptions from error codes defined in the client code.
 
-    def enrich(
-        self, _type: Optional[_ExceptionType] = _ExceptionType.HTTP
-    ) -> ExceptionDetail:
-        return ExceptionDetail(
-            message=self.message,
-            code=self.error.identifier,
-            type=self.error.type,
-            level=self.error.level,
-            status_code=(
-                self.error.http_code
-                if _type == _ExceptionType.HTTP
-                else self.error.websocket_code
-            ),
-            details=self.details,
-        )
+    Example for the client code implementation:
+
+    ```python
+    from crypticorn_utils import ExceptionHandler, BaseError, ApiError
+
+    handler = ExceptionHandler(callback=ApiError.from_identifier)
+    handler.register_exception_handlers(app)
 
+    @app.get("/")
+    def get_root():
+        raise handler.build_exception(ApiErrorIdentifier.UNKNOWN_ERROR)
 
-class HTTPException(FastAPIHTTPException):
-    """A custom HTTP exception wrapper around FastAPI's HTTPException.
-    It allows for a more structured way to handle errors, with a message and an error code. The status code is being derived from the detail's error.
-        The ApiError class is the source of truth. If the error is not yet implemented, there are fallbacks in place.
+    class ApiErrorIdentifier(StrEnum):
+        ...
+
+    class ApiError(BaseError):
+        ...
+    ```
     """
 
     def __init__(
         self,
-        content: ExceptionContent,
-        headers: Optional[dict[str, str]] = None,
-        _type: Optional[_ExceptionType] = _ExceptionType.HTTP,
+        callback: Callable[[str], "BaseError"],
+        type: Optional[ExceptionType] = ExceptionType.HTTP,
     ):
-        self.content = content
-        self.headers = headers
-        assert isinstance(content, ExceptionContent)
-        body = content.enrich(_type)
-        super().__init__(
-            status_code=body.status_code,
-            detail=body.model_dump(mode="json"),
+        """
+        :param callback: The callback to use to get the error object from the error identifier.
+        :param type: The type of exception to raise. Defaults to HTTP.
+        """
+        self.callback = callback
+        self.type = type
+
+    def _http_exception(
+        self, content: ExceptionDetail, headers: Optional[dict[str, str]] = None
+    ) -> HTTPException:
+        return HTTPException(
+            detail=content.model_dump(mode="json"),
             headers=headers,
+            status_code=content.status_code,
         )
 
+    def _websocket_exception(self, content: ExceptionDetail) -> WebSocketException:
+        return WebSocketException(
+            reason=content.model_dump(mode="json"),
+            code=content.status_code,
+        )
 
-class WebSocketException(HTTPException):
-    """A WebSocketException is to be used for WebSocket connections. It is a wrapper around the HTTPException class to maintain the same structure, but using a different status code.
-    To be used in the same way as the HTTPException.
-    """
-
-    def __init__(
-        self, content: ExceptionContent, headers: Optional[dict[str, str]] = None
-    ):
-        super().__init__(content, headers, _type=_ExceptionType.WEBSOCKET)
+    def build_exception(  # type: ignore[return]
+        self,
+        code: str,
+        message: Optional[str] = None,
+        headers: Optional[dict[str, str]] = None,
+        details: Any = None,
+    ) -> Union[HTTPException, WebSocketException]:
+        """Build an exception, without raising it.
+        :param code: The error code to raise.
+        :param message: The message to include in the error.
+        :param headers: The headers to include in the error.
+        :param details: The details to include in the error.
+
+        :return: The exception to raise, either an HTTPException or a WebSocketException.
+
+        ```python
+        @app.get("/")
+        def get_root():
+            raise handler.build_exception(ApiErrorIdentifier.UNKNOWN_ERROR)
+        ```
+        """
+        error = self.callback(code)
+        content = ExceptionDetail(
+            message=message,
+            code=error.identifier,
+            type=error.type,
+            level=error.level,
+            status_code=error.http_code,
+            details=details,
+        )
+        if self.type == ExceptionType.HTTP:
+            return self._http_exception(content, headers)
+        elif self.type == ExceptionType.WEBSOCKET:
+            return self._websocket_exception(content)
+
+    async def _general_handler(request: Request, exc: Exception) -> JSONResponse:
+        """Default exception handler for all exceptions."""
+        body = ExceptionDetail(
+            message=str(exc),
+            code="unknown_error",
+            type=ErrorType.SERVER_ERROR,
+            level=ErrorLevel.ERROR,
+            status_code=500,
+        )
+        res = JSONResponse(
+            status_code=body.status_code,
+            content=body.model_dump(mode="json"),
+            headers=None,
+        )
+        _logger.error(f"General error: {str(exc)}")
+        return res
+
+    async def _request_validation_handler(
+        request: Request, exc: RequestValidationError
+    ) -> JSONResponse:
+        """Exception handler for all request validation errors."""
+        body = ExceptionDetail(
+            message=str(exc),
+            code="invalid_data_request",
+            type=ErrorType.USER_ERROR,
+            level=ErrorLevel.ERROR,
+            status_code=400,
+        )
+        res = JSONResponse(
+            status_code=body.status_code,
+            content=body.model_dump(mode="json"),
+            headers=None,
+        )
+        _logger.error(f"Request validation error: {str(exc)}")
+        return res
+
+    async def _response_validation_handler(
+        request: Request, exc: ResponseValidationError
+    ) -> JSONResponse:
+        """Exception handler for all response validation errors."""
+        body = ExceptionDetail(
+            message=str(exc),
+            code="invalid_data_response",
+            type=ErrorType.USER_ERROR,
+            level=ErrorLevel.ERROR,
+            status_code=400,
+        )
+        res = JSONResponse(
+            status_code=body.status_code,
+            content=body.model_dump(mode="json"),
+            headers=None,
+        )
+        _logger.error(f"Response validation error: {str(exc)}")
+        return res
 
-    @classmethod
-    def from_http_exception(cls, http_exception: HTTPException):
-        """Helper method to convert an HTTPException to a WebSocketException."""
-        return WebSocketException(
-            content=http_exception.content,
-            headers=http_exception.headers,
+    async def _http_handler(request: Request, exc: HTTPException) -> JSONResponse:
+        """Exception handler for HTTPExceptions. It unwraps the HTTPException and returns the detail in a flat JSON response."""
+        res = JSONResponse(
+            status_code=exc.status_code, content=exc.detail, headers=exc.headers
+        )
+        _logger.error(f"HTTP error: {str(exc)}")
+        return res
+
+    def register_exception_handlers(self, app: FastAPI):
+        """Utility to register serveral exception handlers in one go. Catches Exception, HTTPException and Data Validation errors, logs them and responds with a unified json body.
+
+        ```python
+        handler.register_exception_handlers(app)
+        ```
+        """
+        app.add_exception_handler(Exception, self._general_handler)
+        app.add_exception_handler(FastAPIHTTPException, self._http_handler)
+        app.add_exception_handler(
+            RequestValidationError, self._request_validation_handler
+        )
+        app.add_exception_handler(
+            ResponseValidationError, self._response_validation_handler
         )
 
 
-async def general_handler(request: Request, exc: Exception) -> JSONResponse:
-    """Default exception handler for all exceptions."""
-    body = ExceptionContent(message=str(exc), error=ApiError.UNKNOWN_ERROR)
-    http_exc = HTTPException(content=body)
-    res = JSONResponse(
-        status_code=http_exc.status_code,
-        content=http_exc.detail,
-        headers=http_exc.headers,
-    )
-    _logger.error(f"General error: {json.loads(res.__dict__.get('body'))}")
-    return res
-
-
-async def request_validation_handler(
-    request: Request, exc: RequestValidationError
-) -> JSONResponse:
-    """Exception handler for all request validation errors."""
-    body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_REQUEST)
-    http_exc = HTTPException(content=body)
-    res = JSONResponse(
-        status_code=http_exc.status_code,
-        content=http_exc.detail,
-        headers=http_exc.headers,
-    )
-    _logger.error(f"Request validation error: {json.loads(res.__dict__.get('body'))}")
-    return res
-
-
-async def response_validation_handler(
-    request: Request, exc: ResponseValidationError
-) -> JSONResponse:
-    """Exception handler for all response validation errors."""
-    body = ExceptionContent(message=str(exc), error=ApiError.INVALID_DATA_RESPONSE)
-    http_exc = HTTPException(content=body)
-    res = JSONResponse(
-        status_code=http_exc.status_code,
-        content=http_exc.detail,
-        headers=http_exc.headers,
-    )
-    _logger.error(f"Response validation error: {json.loads(res.__dict__.get('body'))}")
-    return res
-
-
-async def http_handler(request: Request, exc: HTTPException) -> JSONResponse:
-    """Exception handler for HTTPExceptions. It unwraps the HTTPException and returns the detail in a flat JSON response."""
-    res = JSONResponse(
-        status_code=exc.status_code, content=exc.detail, headers=exc.headers
-    )
-    _logger.error(f"HTTP error: {json.loads(res.__dict__.get('body'))}")
-    return res
-
-
-def register_exception_handlers(app: FastAPI):
-    """Utility to register serveral exception handlers in one go. Catches Exception, HTTPException and Data Validation errors, logs them and responds with a unified json body."""
-    app.add_exception_handler(Exception, general_handler)
-    app.add_exception_handler(FastAPIHTTPException, http_handler)
-    app.add_exception_handler(RequestValidationError, request_validation_handler)
-    app.add_exception_handler(ResponseValidationError, response_validation_handler)
-
-
-exception_response = {
-    "default": {"model": ExceptionDetail, "description": "Error response"}
-}
-
-
-class CrypticornException(Exception):
-    """A custom exception class for Crypticorn."""
-
-    def __init__(self, error: ApiError, message: str = None):
-        self.message = message
-        self.error = error
-
-    def __str__(self):
-        return f"{self.error.identifier}: {self.message}"
+class BaseError(Enum):
+    """Base API error for the API."""
+
+    @property
+    def identifier(self) -> str:
+        return self.value[0]
+
+    @property
+    def type(self) -> ErrorType:
+        return self.value[1]
+
+    @property
+    def level(self) -> ErrorLevel:
+        return self.value[2]
+
+    @property
+    def http_code(self) -> int:
+        return self.value[3]
+
+    @property
+    def websocket_code(self) -> int:
+        return self.value[4]
+
+    @classmethod
+    def from_identifier(cls, identifier: str) -> Self:
+        return next(error for error in cls if error.identifier == identifier)
+
+
+## Since enums don't support inheritance, you can copy these values to your own enum.
+
+# UNKNOWN_ERROR = "unknown_error"
+# INVALID_DATA_REQUEST = "invalid_data"
+# INVALID_DATA_RESPONSE = "invalid_data_response"
+# OBJECT_ALREADY_EXISTS = "object_already_exists"
+# OBJECT_NOT_FOUND = "object_not_found"
+
+# UNKNOWN_ERROR = (
+#     ErrorCodes.UNKNOWN_ERROR,
+#     ErrorType.SERVER_ERROR,
+#     ErrorLevel.ERROR,
+#     status.HTTP_500_INTERNAL_SERVER_ERROR,
+#     status.WS_1011_INTERNAL_ERROR,
+# )
+# INVALID_DATA_REQUEST = (
+#     ErrorCodes.INVALID_DATA_REQUEST,
+#     ErrorType.USER_ERROR,
+#     ErrorLevel.ERROR,
+#     status.HTTP_422_UNPROCESSABLE_ENTITY,
+#     status.WS_1007_INVALID_FRAME_PAYLOAD_DATA,
+# )
+# INVALID_DATA_RESPONSE = (
+#     ErrorCodes.INVALID_DATA_RESPONSE,
+#     ErrorType.SERVER_ERROR,
+#     ErrorLevel.ERROR,
+#     status.HTTP_422_UNPROCESSABLE_ENTITY,
+#     status.WS_1007_INVALID_FRAME_PAYLOAD_DATA,
+# )
+# OBJECT_ALREADY_EXISTS = (
+#     ErrorCodes.OBJECT_ALREADY_EXISTS,
+#     ErrorType.USER_ERROR,
+#     ErrorLevel.ERROR,
+#     status.HTTP_409_CONFLICT,
+#     status.WS_1008_POLICY_VIOLATION,
+# )
+# OBJECT_NOT_FOUND = (
+#     ErrorCodes.OBJECT_NOT_FOUND,
+#     ErrorType.USER_ERROR,
+#     ErrorLevel.ERROR,
+#     status.HTTP_404_NOT_FOUND,
+#     status.WS_1008_POLICY_VIOLATION,
+# )

crypticorn_utils/logging.py

@@ -4,18 +4,14 @@ import logging
 import os
 import sys
 from datetime import datetime
+from enum import StrEnum
 from logging.handlers import RotatingFileHandler
+from typing import Optional
 
 from crypticorn_utils.ansi_colors import AnsiColors as C
-from crypticorn_utils.mixins import ValidateEnumMixin
 
-try:
-    from enum import StrEnum
-except ImportError:
-    from strenum import StrEnum
 
-
-class LogLevel(ValidateEnumMixin, StrEnum):
+class LogLevel(StrEnum):
     DEBUG = "DEBUG"
     INFO = "INFO"
     WARNING = "WARNING"
@@ -38,16 +34,6 @@ class LogLevel(ValidateEnumMixin, StrEnum):
         else:
             return C.RESET
 
-    @staticmethod
-    def get_level(level: "LogLevel") -> int:
-        """Get the integer value from a log level name."""
-        return logging._nameToLevel.get(level, logging.INFO)
-
-    @staticmethod
-    def get_name(level: int) -> "LogLevel":
-        """Get the level name from the integer value of a log level."""
-        return LogLevel(logging._levelToName.get(level, "INFO"))
-
 
 _LOGFORMAT = (
     f"{C.CYAN_BOLD}%(asctime)s{C.RESET} - "
@@ -74,12 +60,12 @@ class _CustomFormatter(logging.Formatter):
 
 
 def configure_logging(
-    name: str = None,
+    name: Optional[str] = None,
     fmt: str = _LOGFORMAT,
     datefmt: str = _DATEFMT,
     stdout_level: int = logging.INFO,
     file_level: int = logging.INFO,
-    log_file: str = None,
+    log_file: Optional[str] = None,
     filters: list[logging.Filter] = [],
 ) -> None:
     """Configures the logging for the application.

crypticorn_utils/metrics.py

@@ -1,6 +1,6 @@
 # metrics/registry.py
-from prometheus_client import CollectorRegistry, Counter, Histogram
 from crypticorn_utils._migration import has_migrated
+from prometheus_client import CollectorRegistry, Counter, Histogram
 
 registry = CollectorRegistry()
 
@@ -23,7 +23,6 @@ if has_migrated:
         "http_request_size_bytes", "Size of HTTP request bodies", ["method", "endpoint"]
     )
 
-
     RESPONSE_SIZE = Histogram(
         "http_response_size_bytes",
         "Size of HTTP responses",

crypticorn_utils/middleware.py

@@ -1,22 +1,18 @@
 import time
-import warnings
-from contextlib import asynccontextmanager
 
-from crypticorn_utils.logging import configure_logging
-from crypticorn_utils.warnings import CrypticornDeprecatedSince217
+from crypticorn_utils.metrics import has_migrated
 from fastapi import FastAPI, Request
 from fastapi.middleware.cors import CORSMiddleware
 from starlette.middleware.base import BaseHTTPMiddleware
-from typing_extensions import deprecated
-from crypticorn_utils.metrics import has_migrated
 
 if has_migrated:
     from crypticorn_utils.metrics import (
-    HTTP_REQUEST_DURATION,
-    HTTP_REQUESTS_COUNT,
-    REQUEST_SIZE,
-    RESPONSE_SIZE,
-)
+        HTTP_REQUEST_DURATION,
+        HTTP_REQUESTS_COUNT,
+        REQUEST_SIZE,
+        RESPONSE_SIZE,
+    )
+
     # otherwise prometheus reqisters metrics twice, resulting in an exception
     class PrometheusMiddleware(BaseHTTPMiddleware):
         async def dispatch(self, request: Request, call_next):
@@ -80,25 +76,6 @@ if has_migrated:
             return response
 
 
-@deprecated("Use add_middleware instead", category=None)
-def add_cors_middleware(app: "FastAPI"):
-    warnings.warn(
-        "add_cors_middleware is deprecated. Use add_middleware instead.",
-        CrypticornDeprecatedSince217,
-    )
-    app.add_middleware(
-        CORSMiddleware,
-        allow_origins=[
-            "http://localhost:5173",  # vite dev server
-            "http://localhost:4173",  # vite preview server
-        ],
-        allow_origin_regex="^https://([a-zA-Z0-9-]+.)*crypticorn.(dev|com)/?$",  # matches (multiple or no) subdomains of crypticorn.dev and crypticorn.com
-        allow_credentials=True,
-        allow_methods=["*"],
-        allow_headers=["*"],
-    )
-
-
 def add_middleware(app: "FastAPI"):
     app.add_middleware(
         CORSMiddleware,
@@ -113,13 +90,3 @@ def add_middleware(app: "FastAPI"):
     )
     if has_migrated:
         app.add_middleware(PrometheusMiddleware)
-
-
-@asynccontextmanager
-async def default_lifespan(app: FastAPI):
-    """Default lifespan for the applications.
-    This is used to configure the logging for the application.
-    To override this, pass a different lifespan to the FastAPI constructor or call this lifespan within a custom lifespan.
-    """
-    configure_logging()
-    yield

crypticorn_utils/utils.py

@@ -2,32 +2,8 @@
 
 import random
 import string
-import warnings
 from datetime import datetime
-from decimal import Decimal
-from typing import Any, Union
-
-import typing_extensions
-from crypticorn_utils.exceptions import ApiError, ExceptionContent, HTTPException
-from crypticorn_utils.warnings import CrypticornDeprecatedSince25
-
-
-def throw_if_none(
-    value: Any,
-    message: str = "Object not found",
-) -> None:
-    """Throws an FastAPI HTTPException if the value is None. https://docs.python.org/3/library/stdtypes.html#truth-value-testing"""
-    if value is None:
-        raise HTTPException(content=ExceptionContent(error=ApiError.OBJECT_NOT_FOUND, message=message))
-
-
-def throw_if_falsy(
-    value: Any,
-    message: str = "Object not found",
-) -> None:
-    """Throws an FastAPI HTTPException if the value is False. https://docs.python.org/3/library/stdtypes.html#truth-value-testing"""
-    if not value:
-        raise HTTPException(content=ExceptionContent(error=ApiError.OBJECT_NOT_FOUND, message=message))
+from typing import Any
 
 
 def gen_random_id(length: int = 20) -> str:
@@ -37,33 +13,6 @@ def gen_random_id(length: int = 20) -> str:
     return "".join(random.choice(charset) for _ in range(length))
 
 
-@typing_extensions.deprecated(
-    "The `is_equal` method is deprecated; use `math.is_close` instead.", category=None
-)
-def is_equal(
-    a: Union[float, Decimal],
-    b: Union[float, Decimal],
-    rel_tol: float = 1e-9,
-    abs_tol: float = 0.0,
-) -> bool:
-    """
-    Compare two Decimal numbers for approximate equality.
-    """
-    warnings.warn(
-        "The `is_equal` method is deprecated; use `math.is_close` instead.",
-        category=CrypticornDeprecatedSince25,
-    )
-    if not isinstance(a, Decimal):
-        a = Decimal(str(a))
-    if not isinstance(b, Decimal):
-        b = Decimal(str(b))
-
-    # Convert tolerances to Decimal
-    return Decimal(abs(a - b)) <= max(
-        Decimal(str(rel_tol)) * max(abs(a), abs(b)), Decimal(str(abs_tol))
-    )
-
-
 def optional_import(module_name: str, extra_name: str) -> Any:
     """
     Tries to import a module. Raises `ImportError` if not found with a message to install the extra dependency.

crypticorn_utils/warnings.py

@@ -43,34 +43,6 @@ class CrypticornDeprecationWarning(DeprecationWarning):
         return message
 
 
-class CrypticornDeprecatedSince25(CrypticornDeprecationWarning):
-    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.5."""
-
-    def __init__(self, message: str, *args: object) -> None:
-        super().__init__(message, *args, since=(2, 5), expected_removal=(3, 0))
-
-
-class CrypticornDeprecatedSince28(CrypticornDeprecationWarning):
-    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.8."""
-
-    def __init__(self, message: str, *args: object) -> None:
-        super().__init__(message, *args, since=(2, 8), expected_removal=(3, 0))
-
-
-class CrypticornDeprecatedSince215(CrypticornDeprecationWarning):
-    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.15."""
-
-    def __init__(self, message: str, *args: object) -> None:
-        super().__init__(message, *args, since=(2, 15), expected_removal=(3, 0))
-
-
-class CrypticornDeprecatedSince217(CrypticornDeprecationWarning):
-    """A specific `CrypticornDeprecationWarning` subclass defining functionality deprecated since Crypticorn 2.17."""
-
-    def __init__(self, message: str, *args: object) -> None:
-        super().__init__(message, *args, since=(2, 17), expected_removal=(3, 0))
-
-
 class CrypticornExperimentalWarning(Warning):
     """A Crypticorn specific experimental functionality warning.