aiteamutils 0.2.32__tar.gz → 0.2.34__tar.gz

aiteamutils-0.2.34/.cursorrules

@@ -0,0 +1,90 @@
+- 에러 처리는 `core/app/utils/CustomException`의 `CustomException` 클래스를 사용:
+  - 형식: `CustomException(ErrorCode, detail=value, source_function="function_name")`
+  - **ErrorCode**: `core/app/utils/CustomException`에 정의된 값 사용.
+  - **detail**: 검증/처리 중인 값 자체만 포함 (예: 전화번호 검증 시 전화번호 값만)
+    - 단일 값: 해당 값만 포함 (예: `detail=phone_number`)
+    - 복합 값: 파이프(|)로 구분 (예: `detail=f"{table}|{column}|{value}"`)
+    - 추가 텍스트나 설명 없이 값만 포함
+  - **source_function**: 에러 발생 함수명을 문자열로 입력.
+  
+# 에러 처리 규칙
+1. 에러 응답 형식:
+   ```json
+   {
+       "error_code": 3003,        // 숫자 형식
+       "error_type": "DUPLICATE_ERROR",
+       "status_code": 409,
+       "path": "/companies",
+       "method": "POST",
+       "client_ip": "172.20.0.2",
+       "user_agent": "Mozilla/5.0..."
+   }
+   ```
+
+2. 에러 로그 형식:
+   ```json
+   {
+       "error_code": 3003,
+       "error_type": "DUPLICATE_ERROR",
+       "status_code": 409,
+       "path": "/companies",
+       "method": "POST",
+       "client_ip": "172.20.0.2",
+       "user_agent": "Mozilla/5.0...",
+       "detail": "companies|id|test-company",
+       "source_function": "DatabaseService.validate_unique_fields",
+       "error_chain": [
+           {
+               "error_code": "ErrorCode.DUPLICATE_ERROR",
+               "detail": "companies|id|test-company",
+               "source_function": "DatabaseService.validate_unique_fields",
+               "original_error": null
+           },
+           {
+               "error_code": "ErrorCode.DUPLICATE_ERROR",
+               "detail": "companies|id|test-company",
+               "source_function": "OrganizationRepository.create_company",
+               "original_error": null
+           }
+       ],
+       "original_error": null
+   }
+   ```
+
+3. detail 형식:
+   - 단일 필드 중복: `{테이블명}|{필드명}|{값}`
+   - 복수 필드 중복: `{테이블명}|{필드1}:{값1}|{필드2}:{값2}`
+   - 외래키 위반: `{참조테이블명}|{필드명}|{값}`
+   - 유효성 검사: `{검증값}`
+
+4. 에러 체인 구성:
+   - 에러는 최초 발생 지점부터 시작하여 호출 스택을 따라 전파
+   - 각 레이어는 자신의 컨텍스트 정보를 추가하여 에러를 상위로 전달
+   - `parent_source_function`을 통해 호출 경로 추적
+   - 원본 에러 정보는 `original_error`로 보존
+
+5. 레이어별 에러 처리:
+   - Database 레이어:
+     - 중복 검사: `DUPLICATE_ERROR`
+     - 외래키 위반: `FOREIGN_KEY_VIOLATION`
+     - 쿼리 실패: `DB_QUERY_ERROR`
+   - Repository 레이어:
+     - 원본 에러 보존 및 컨텍스트 추가
+   - Service 레이어:
+     - 비즈니스 로직 실패: `INTERNAL_ERROR`
+     - 트랜잭션 실패: `TRANSACTION_ERROR`
+   - API 레이어:
+     - 입력값 검증: `VALIDATION_ERROR`
+     - 권한 검증: `UNAUTHORIZED`, `FORBIDDEN`
+
+6. 에러 처리 원칙:
+   - 클라이언트 응답에서는 `detail`, `source_function`, `error_chain` 제외
+   - 로그에는 모든 정보를 포함하여 디버깅 용이성 확보
+   - 에러는 발생 지점에서 바로 처리하고 적절한 에러 코드 사용
+   - 중첩된 try-except 블록 대신 early return 패턴 사용
+   - 모든 예외는 `CustomException`으로 변환하여 일관된 처리
+
+7. 에러 코드 관리:
+   - 모든 에러 코드는 `ErrorCode` enum에 정의
+   - 도메인별로 구분된 에러 코드 범위 사용
+   - 각 에러 코드는 고유한 숫자 값과 HTTP 상태 코드 매핑

{aiteamutils-0.2.32 → aiteamutils-0.2.34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiteamutils
-Version: 0.2.32
+Version: 0.2.34
 Summary: AI Team Utilities
 Project-URL: Homepage, https://github.com/yourusername/aiteamutils
 Project-URL: Issues, https://github.com/yourusername/aiteamutils/issues

{aiteamutils-0.2.32 → aiteamutils-0.2.34}/aiteamutils/config.py

@@ -1,6 +1,7 @@
 """설정 모듈."""
 from typing import Union
 from .database import init_database_service
+from .exceptions import CustomException, ErrorCode
 
 class Settings:
     """기본 설정 클래스"""
@@ -74,8 +75,12 @@ def get_settings() -> Settings:
         Settings: 설정 객체
         
     Raises:
-        RuntimeError: 설정이 초기화되지 않은 경우
+        CustomException: 설정이 초기화되지 않은 경우
     """
     if _settings is None:
-        raise RuntimeError("Settings not initialized. Call init_settings first.")
+        raise CustomException(
+            ErrorCode.INTERNAL_ERROR,
+            detail="settings",
+            source_function="get_settings"
+        )
     return _settings 

{aiteamutils-0.2.32 → aiteamutils-0.2.34}/aiteamutils/database.py

@@ -26,10 +26,14 @@ def get_database_service() -> 'DatabaseService':
         DatabaseService: DatabaseService 인스턴스
         
     Raises:
-        RuntimeError: DatabaseService가 초기화되지 않은 경우
+        CustomException: DatabaseService가 초기화되지 않은 경우
     """
     if _database_service is None:
-        raise RuntimeError("DatabaseService not initialized. Call init_settings with db_url first.")
+        raise CustomException(
+            ErrorCode.DB_CONNECTION_ERROR,
+            detail="database_service",
+            source_function="get_database_service"
+        )
     return _database_service
 
 async def get_db() -> AsyncGenerator[AsyncSession, None]:
@@ -100,13 +104,21 @@ class DatabaseService:
             )
             self.db = session
         else:
-            raise ValueError("Either db_url or session must be provided")
+            raise CustomException(
+                ErrorCode.DB_CONNECTION_ERROR,
+                detail="db_url|session",
+                source_function="DatabaseService.__init__"
+            )
 
     @asynccontextmanager
     async def get_session(self) -> AsyncGenerator[AsyncSession, None]:
         """데이터베이스 세션을 생성하고 반환하는 비동기 컨텍스트 매니저."""
         if self.session_factory is None:
-            raise RuntimeError("Session factory not initialized")
+            raise CustomException(
+                ErrorCode.DB_CONNECTION_ERROR,
+                detail="session_factory",
+                source_function="DatabaseService.get_session"
+            )
         
         async with self.session_factory() as session:
             try:

{aiteamutils-0.2.32 → aiteamutils-0.2.34}/aiteamutils/dependencies.py

@@ -26,10 +26,14 @@ class ServiceRegistry:
             service_class (Type): Service 클래스
 
         Raises:
-            ValueError: 이미 등록된 서비스인 경우
+            CustomException: 이미 등록된 서비스인 경우
         """
         if name in self._services:
-            raise ValueError(f"Service '{name}' is already registered.")
+            raise CustomException(
+                ErrorCode.INTERNAL_ERROR,
+                detail=f"service|{name}",
+                source_function="ServiceRegistry.register"
+            )
         self._services[name] = (repository_class, service_class)
 
     def get(self, name: str) -> Tuple[Type, Type]:
@@ -42,10 +46,14 @@ class ServiceRegistry:
             Tuple[Type, Type]: (Repository 클래스, Service 클래스) 튜플
 
         Raises:
-            ValueError: 등록되지 않은 서비스인 경우
+            CustomException: 등록되지 않은 서비스인 경우
         """
         if name not in self._services:
-            raise ValueError(f"Service '{name}' is not registered.")
+            raise CustomException(
+                ErrorCode.NOT_FOUND,
+                detail=f"service|{name}",
+                source_function="ServiceRegistry.get"
+            )
         return self._services[name]
 
 # ServiceRegistry 초기화

{aiteamutils-0.2.32 → aiteamutils-0.2.34}/aiteamutils/security.py

@@ -157,8 +157,19 @@ def verify_password(plain_password: str, hashed_password: str) -> bool:
         
     Returns:
         bool: 비밀번호 일치 여부
+        
+    Raises:
+        CustomException: 비밀번호 검증 실패 시
     """
-    return pwd_context.verify(plain_password, hashed_password)
+    try:
+        return pwd_context.verify(plain_password, hashed_password)
+    except Exception as e:
+        raise CustomException(
+            ErrorCode.INVALID_PASSWORD,
+            detail=plain_password,
+            source_function="security.verify_password",
+            original_error=e
+        )
 
 def hash_password(password: str) -> str:
     """비밀번호를 해시화합니다.
@@ -168,8 +179,19 @@ def hash_password(password: str) -> str:
         
     Returns:
         str: 해시된 비밀번호
+        
+    Raises:
+        CustomException: 비밀번호 해시화 실패 시
     """
-    return pwd_context.hash(password)
+    try:
+        return pwd_context.hash(password)
+    except Exception as e:
+        raise CustomException(
+            ErrorCode.INTERNAL_ERROR,
+            detail=password,
+            source_function="security.hash_password",
+            original_error=e
+        )
 
 def rate_limit(
     max_requests: int,
@@ -177,7 +199,7 @@ def rate_limit(
     key_func: Optional[Callable] = None
 ):
     """Rate limiting 데코레이터."""
-    limiter = RateLimiter(max_requests, window_seconds)
+    rate_limits: Dict[str, Dict[str, Any]] = {}
     
     def decorator(func: Callable) -> Callable:
         @wraps(func)
@@ -194,39 +216,56 @@ def rate_limit(
                         request = arg
                         break
             if not request:
-                raise SecurityError(
+                raise CustomException(
                     ErrorCode.INTERNAL_ERROR,
                     detail="Request object not found",
                     source_function="rate_limit"
                 )
             
-            # Rate limit 키 생성
+            # 레이트 리밋 키 생성
             if key_func:
                 rate_limit_key = f"rate_limit:{key_func(request)}"
             else:
                 client_ip = request.client.host
                 rate_limit_key = f"rate_limit:{client_ip}:{func.__name__}"
             
-            try:
-                if not limiter.is_allowed(rate_limit_key):
-                    remaining_time = limiter.get_remaining_time(rate_limit_key)
+            now = datetime.now(UTC)
+            
+            # 현재 rate limit 정보 가져오기
+            rate_info = rate_limits.get(rate_limit_key)
+            
+            if rate_info is None or (now - rate_info["start_time"]).total_seconds() >= window_seconds:
+                # 새로운 rate limit 설정
+                rate_limits[rate_limit_key] = {
+                    "count": 1,
+                    "start_time": now
+                }
+            else:
+                # 기존 rate limit 업데이트
+                if rate_info["count"] >= max_requests:
+                    # rate limit 초과
+                    remaining_seconds = window_seconds - (now - rate_info["start_time"]).total_seconds()
                     raise RateLimitExceeded(
-                        detail=f"Rate limit exceeded. Try again in {int(remaining_time)} seconds",
+                        detail=rate_limit_key,
                         source_function=func.__name__,
-                        remaining_seconds=remaining_time,
+                        remaining_seconds=remaining_seconds,
                         max_requests=max_requests,
                         window_seconds=window_seconds
                     )
-                
+                rate_info["count"] += 1
+            
+            try:
+                # 원래 함수 실행
                 return await func(*args, **kwargs)
-                    
-            except (RateLimitExceeded, SecurityError) as e:
+            except CustomException as e:
+                # CustomException은 그대로 전파
                 raise e
             except Exception as e:
-                raise SecurityError(
+                # 다른 예외는 INTERNAL_ERROR로 래핑
+                raise CustomException(
                     ErrorCode.INTERNAL_ERROR,
                     detail=str(e),
-                    source_function="rate_limit",
+                    source_function=func.__name__,
                     original_error=e
                 )
                 
@@ -288,10 +327,10 @@ async def create_jwt_token(
         required_fields = {"username", "ulid"}
         missing_fields = required_fields - set(user_data.keys())
         if missing_fields:
-            raise TokenCreationError(
-                detail=f"Missing required fields: {', '.join(missing_fields)}",
-                source_function="create_jwt_token",
-                token_type=token_type
+            raise CustomException(
+                ErrorCode.REQUIRED_FIELD_MISSING,
+                detail="|".join(missing_fields),
+                source_function="security.create_jwt_token"
             )
         
         if token_type == "access":
@@ -337,10 +376,10 @@ async def create_jwt_token(
                 algorithm=settings.JWT_ALGORITHM
             )
         except Exception as e:
-            raise TokenCreationError(
-                detail="Failed to encode JWT token",
-                source_function="create_jwt_token",
-                token_type=token_type,
+            raise CustomException(
+                ErrorCode.INTERNAL_ERROR,
+                detail=f"token|{token_type}",
+                source_function="security.create_jwt_token",
                 original_error=e
             )
         
@@ -362,13 +401,13 @@ async def create_jwt_token(
         
         return token
         
-    except (TokenCreationError, SecurityError) as e:
+    except CustomException as e:
         raise e
     except Exception as e:
-        raise SecurityError(
+        raise CustomException(
             ErrorCode.INTERNAL_ERROR,
             detail=str(e),
-            source_function="create_jwt_token",
+            source_function="security.create_jwt_token",
             original_error=e
         )
 
@@ -376,7 +415,18 @@ async def verify_jwt_token(
     token: str,
     expected_type: Optional[Literal["access", "refresh"]] = None
 ) -> Dict[str, Any]:
-    """JWT 토큰을 검증합니다."""
+    """JWT 토큰을 검증합니다.
+    
+    Args:
+        token: 검증할 JWT 토큰
+        expected_type: 예상되는 토큰 타입
+        
+    Returns:
+        Dict[str, Any]: 토큰 페이로드
+        
+    Raises:
+        CustomException: 토큰 검증 실패 시
+    """
     try:
         settings = get_settings()
         # 토큰 디코딩
@@ -390,25 +440,27 @@ async def verify_jwt_token(
         
         # 토큰 타입 검증 (expected_type이 주어진 경우에만)
         if expected_type and payload.get("token_type") != expected_type:
-            raise TokenError(
-                detail=f"Expected {expected_type} token but got {payload.get('token_type')}",
-                source_function="verify_jwt_token"
+            raise CustomException(
+                ErrorCode.INVALID_TOKEN,
+                detail=f"token|{expected_type}|{payload.get('token_type')}",
+                source_function="security.verify_jwt_token"
             )
         
         return payload
         
     except JWTError as e:
-        raise TokenError(
-            detail=str(e),
-            source_function="verify_jwt_token",
+        raise CustomException(
+            ErrorCode.INVALID_TOKEN,
+            detail=token[:10] + "...",
+            source_function="security.verify_jwt_token",
             original_error=e
         )
-    except (TokenError, SecurityError) as e:
+    except CustomException as e:
         raise e
     except Exception as e:
-        raise SecurityError(
+        raise CustomException(
             ErrorCode.INTERNAL_ERROR,
             detail=str(e),
-            source_function="verify_jwt_token",
+            source_function="security.verify_jwt_token",
             original_error=e
         ) 

aiteamutils-0.2.34/aiteamutils/version.py

@@ -0,0 +1,2 @@
+"""버전 정보"""
+__version__ = "0.2.34"

aiteamutils-0.2.32/aiteamutils/version.py

@@ -1,2 +0,0 @@
-"""버전 정보"""
-__version__ = "0.2.32"