aioia-core 0.1.0__py3-none-any.whl

aioia_core/__init__.py

@@ -0,0 +1,47 @@
+"""
+AIoIA Core - Core infrastructure for AIoIA projects.
+
+Provides:
+- Database: SQLAlchemy base models and CRUD manager
+- Errors: Standardized error codes and responses
+- Settings: Common settings classes
+"""
+
+__version__ = "0.1.0"
+
+from aioia_core.errors import (
+    INTERNAL_SERVER_ERROR,
+    RESOURCE_NOT_FOUND,
+    UNAUTHORIZED,
+    VALIDATION_ERROR,
+    ErrorResponse,
+    extract_error_code_from_exception,
+    get_error_detail_from_exception,
+)
+from aioia_core.factories.base_manager_factory import BaseManagerFactory
+from aioia_core.managers import BaseManager
+from aioia_core.models import Base, BaseModel
+from aioia_core.protocols import CrudManagerProtocol, DatabaseManagerProtocol
+from aioia_core.settings import DatabaseSettings, JWTSettings, OpenAIAPISettings
+
+__all__ = [
+    # Database
+    "Base",
+    "BaseModel",
+    "BaseManager",
+    "BaseManagerFactory",
+    "CrudManagerProtocol",
+    "DatabaseManagerProtocol",
+    # Errors
+    "ErrorResponse",
+    "UNAUTHORIZED",
+    "VALIDATION_ERROR",
+    "RESOURCE_NOT_FOUND",
+    "INTERNAL_SERVER_ERROR",
+    "extract_error_code_from_exception",
+    "get_error_detail_from_exception",
+    # Settings
+    "DatabaseSettings",
+    "OpenAIAPISettings",
+    "JWTSettings",
+]

aioia_core/auth.py

@@ -0,0 +1,46 @@
+"""Authentication and authorization utilities for AIoIA projects."""
+
+from enum import Enum
+from typing import Protocol
+
+from sqlalchemy.orm import Session
+
+
+class UserRole(str, Enum):
+    """Standard user roles for all AIoIA projects."""
+
+    ADMIN = "admin"
+    USER = "user"
+
+
+class UserRoleProvider(Protocol):
+    """
+    Protocol for retrieving user roles and context.
+
+    Projects implement this to integrate their user management system
+    with BaseCrudRouter's authentication/authorization.
+    """
+
+    def get_user_role(  # pylint: disable=unnecessary-ellipsis
+        self, user_id: str, db: Session
+    ) -> UserRole | None:
+        """
+        Get user's role by ID.
+
+        Args:
+            user_id: User identifier
+            db: Database session
+        """
+        ...
+
+    def get_user_context(  # pylint: disable=unnecessary-ellipsis
+        self, user_id: str, db: Session
+    ) -> dict | None:
+        """
+        Get user context for monitoring/observability tools.
+
+        Args:
+            user_id: User identifier
+            db: Database session
+        """
+        ...

aioia_core/errors/__init__.py

@@ -0,0 +1,56 @@
+"""
+Error handling infrastructure for AIoIA projects.
+
+Provides standardized error codes and responses for FastAPI applications.
+"""
+
+# Error codes
+from aioia_core.errors.error_codes import (
+    DATABASE_ERROR,
+    EXTERNAL_SERVICE_ERROR,
+    FORBIDDEN,
+    INTERNAL_SERVER_ERROR,
+    INVALID_JSON,
+    INVALID_QUERY_PARAMS,
+    INVALID_TOKEN,
+    JWT_SECRET_NOT_CONFIGURED,
+    MISSING_REQUIRED_FIELD,
+    RESOURCE_CREATION_FAILED,
+    RESOURCE_DELETE_FAILED,
+    RESOURCE_NOT_FOUND,
+    RESOURCE_UPDATE_FAILED,
+    TOKEN_EXPIRED,
+    UNAUTHORIZED,
+    VALIDATION_ERROR,
+)
+
+# Error responses
+from aioia_core.errors.error_responses import (
+    ErrorResponse,
+    extract_error_code_from_exception,
+    get_error_detail_from_exception,
+)
+
+__all__ = [
+    # Error codes
+    "UNAUTHORIZED",
+    "FORBIDDEN",
+    "INVALID_TOKEN",
+    "TOKEN_EXPIRED",
+    "JWT_SECRET_NOT_CONFIGURED",
+    "VALIDATION_ERROR",
+    "INVALID_JSON",
+    "MISSING_REQUIRED_FIELD",
+    "INVALID_QUERY_PARAMS",
+    "RESOURCE_NOT_FOUND",
+    "RESOURCE_CREATION_FAILED",
+    "RESOURCE_UPDATE_FAILED",
+    "RESOURCE_DELETE_FAILED",
+    "INTERNAL_SERVER_ERROR",
+    "DATABASE_ERROR",
+    "EXTERNAL_SERVICE_ERROR",
+    # Error responses
+    "ErrorResponse",
+    "extract_error_code_from_exception",
+    "get_error_detail_from_exception",
+]

aioia_core/errors/error_codes.py

@@ -0,0 +1,26 @@
+# Error codes for consistent error handling across FastAPI endpoints
+# These constants ensure standardized error identification for frontend applications
+
+# Authentication & Authorization errors
+UNAUTHORIZED = "UNAUTHORIZED"  # User is not authenticated
+FORBIDDEN = "FORBIDDEN"  # User lacks permission for the requested resource
+INVALID_TOKEN = "INVALID_TOKEN"  # JWT token is invalid or malformed
+TOKEN_EXPIRED = "TOKEN_EXPIRED"  # JWT token has expired
+JWT_SECRET_NOT_CONFIGURED = "JWT_SECRET_NOT_CONFIGURED"  # Server configuration error
+
+# Validation & Request errors
+VALIDATION_ERROR = "VALIDATION_ERROR"  # Request data validation failed
+INVALID_JSON = "INVALID_JSON"  # Request body contains invalid JSON
+MISSING_REQUIRED_FIELD = "MISSING_REQUIRED_FIELD"  # Required field is missing
+INVALID_QUERY_PARAMS = "INVALID_QUERY_PARAMS"  # Query parameters are invalid
+
+# Resource Management errors
+RESOURCE_NOT_FOUND = "RESOURCE_NOT_FOUND"  # Requested resource does not exist
+RESOURCE_CREATION_FAILED = "RESOURCE_CREATION_FAILED"  # Failed to create resource
+RESOURCE_UPDATE_FAILED = "RESOURCE_UPDATE_FAILED"  # Failed to update resource
+RESOURCE_DELETE_FAILED = "RESOURCE_DELETE_FAILED"  # Failed to delete resource
+
+# System & Server errors
+INTERNAL_SERVER_ERROR = "INTERNAL_SERVER_ERROR"  # Unexpected server error
+DATABASE_ERROR = "DATABASE_ERROR"  # Database operation failed
+EXTERNAL_SERVICE_ERROR = "EXTERNAL_SERVICE_ERROR"  # External service unavailable

aioia_core/errors/error_responses.py

@@ -0,0 +1,92 @@
+"""Error response models and utility functions for FastAPI applications."""
+
+from typing import Any, cast
+
+from fastapi import HTTPException
+from pydantic import BaseModel, Field
+
+from aioia_core.errors import error_codes
+
+
+class ErrorResponse(BaseModel):
+    """
+    Standardized error response model following RFC 9457 Problem Details for HTTP APIs.
+    This model provides consistent error information across all FastAPI endpoints.
+    """
+
+    status: int = Field(
+        ...,
+        description="HTTP status code",
+    )
+    detail: str = Field(
+        ...,
+        description="Human-readable error message",
+    )
+    code: str = Field(
+        ...,
+        description="Machine-readable error code for client-side error handling",
+    )
+
+    class Config:
+        json_schema_extra = {
+            "examples": [
+                {
+                    "status": 401,
+                    "detail": "Invalid authentication credentials",
+                    "code": "INVALID_TOKEN",
+                },
+                {
+                    "status": 404,
+                    "detail": "Resource not found: item_123",
+                    "code": "RESOURCE_NOT_FOUND",
+                },
+                {
+                    "status": 422,
+                    "detail": "Validation error in field 'email': Invalid email format",
+                    "code": "VALIDATION_ERROR",
+                },
+            ]
+        }
+
+
+def extract_error_code_from_exception(exc: HTTPException) -> str:
+    """
+    HTTPException에서 에러 코드를 추출합니다.
+    detail이 dict 형태인 경우 code 필드를 찾고, 없으면 기본값 반환
+
+    Args:
+        exc: HTTPException 인스턴스
+
+    Returns:
+        str: 에러 코드
+    """
+    if isinstance(exc.detail, dict) and "code" in exc.detail:
+        return cast(dict[str, Any], exc.detail)["code"]
+
+    # 상태 코드별 기본 에러 코드 매핑
+    default_codes = {
+        401: error_codes.UNAUTHORIZED,
+        403: error_codes.FORBIDDEN,
+        404: error_codes.RESOURCE_NOT_FOUND,
+        422: error_codes.VALIDATION_ERROR,
+        500: error_codes.INTERNAL_SERVER_ERROR,
+    }
+
+    return default_codes.get(exc.status_code, error_codes.INTERNAL_SERVER_ERROR)
+
+
+def get_error_detail_from_exception(exc: HTTPException) -> str:
+    """
+    HTTPException에서 에러 상세 메시지를 추출합니다.
+
+    Args:
+        exc: HTTPException 인스턴스
+
+    Returns:
+        str: 에러 상세 메시지
+    """
+    if isinstance(exc.detail, dict) and "detail" in exc.detail:
+        return cast(dict[str, Any], exc.detail)["detail"]
+    if isinstance(exc.detail, str):
+        return exc.detail
+    return str(exc.detail)

aioia_core/factories/__init__.py

@@ -0,0 +1,5 @@
+"""Factory patterns for AIoIA projects."""
+
+from aioia_core.factories.base_manager_factory import BaseManagerFactory
+
+__all__ = ["BaseManagerFactory"]

aioia_core/factories/base_manager_factory.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from abc import ABC
+from typing import Generic, TypeVar
+
+from sqlalchemy.orm import Session, sessionmaker
+
+from aioia_core.protocols import DatabaseManagerProtocol
+
+# ManagerType을 DatabaseManagerProtocol에 바인딩
+ManagerType = TypeVar("ManagerType", bound=DatabaseManagerProtocol)
+
+
+class BaseManagerFactory(ABC, Generic[ManagerType]):
+    """
+    기본 매니저 팩토리 클래스
+
+    이 클래스는 데이터베이스 저장소를 사용하는 매니저 인스턴스를 생성하기 위한
+    기본 팩토리 패턴을 구현합니다.
+
+    Args:
+        db_session_factory: SQLAlchemy 세션 팩토리
+        manager_class: 생성할 매니저 클래스
+    """
+
+    def __init__(
+        self,
+        db_session_factory: sessionmaker,
+        manager_class: type[ManagerType],
+    ):
+        """
+        BaseManagerFactory 초기화
+
+        Args:
+            db_session_factory: SQLAlchemy 세션 팩토리
+            manager_class: 생성할 매니저 클래스
+        """
+        self.db_session_factory = db_session_factory
+        self.manager_class = manager_class
+
+    def create_manager(self, db_session: Session | None = None) -> ManagerType:
+        """
+        매니저 인스턴스를 생성합니다.
+
+        이 메서드는 매니저 클래스의 인스턴스를 생성하고 반환합니다.
+        db_session이 제공되지 않은 경우 새로운 세션을 생성합니다.
+
+        Args:
+            db_session: 선택적 데이터베이스 세션. None인 경우 새로운 세션을 생성합니다.
+
+        Returns:
+            생성된 매니저 인스턴스
+        """
+        session = db_session if db_session is not None else self.db_session_factory()
+        return self.manager_class(session)

aioia_core/fastapi/__init__.py

@@ -0,0 +1,15 @@
+"""FastAPI utilities for AIoIA projects."""
+
+from aioia_core.fastapi.base_crud_router import (
+    BaseCrudRouter,
+    DeleteResponse,
+    PaginatedResponse,
+    SingleItemResponse,
+)
+
+__all__ = [
+    "BaseCrudRouter",
+    "PaginatedResponse",
+    "SingleItemResponse",
+    "DeleteResponse",
+]