aiteamutils 0.2.164__py3-none-any.whl → 0.2.165__py3-none-any.whl

aiteamutils/database.py

@@ -8,10 +8,11 @@ from typing import (
     List, 
     Optional, 
     AsyncGenerator,
-    Union
+    Union,
+    Tuple
 )
 from sqlalchemy.ext.asyncio import AsyncSession
-from sqlalchemy import select, and_, or_
+from sqlalchemy import select, and_, or_, join
 from sqlalchemy.orm import DeclarativeBase, joinedload, selectinload, contains_eager
 from sqlalchemy.exc import SQLAlchemyError
 from datetime import datetime
@@ -20,12 +21,18 @@ from sqlalchemy.ext.asyncio import AsyncSession
 from fastapi import Request
 from ulid import ULID
 from sqlalchemy import MetaData, Table, insert
+from sqlalchemy.sql.elements import BinaryExpression
 
 #패키지 라이브러리
 from .exceptions import ErrorCode, CustomException
 
 ModelType = TypeVar("ModelType", bound=DeclarativeBase)
 
+JoinTarget = Union[
+    DeclarativeBase,  # 모델
+    Tuple[DeclarativeBase, BinaryExpression]  # (모델, 조인 조건)
+]
+
 ##################
 # 전처리 #
 ##################
@@ -428,7 +435,7 @@ async def list_entities(
     skip: int = 0,
     limit: int = 100,
     filters: Optional[List[Dict[str, Any]]] = None,
-    explicit_joins: Optional[List[Any]] = None,
+    explicit_joins: Optional[List[JoinTarget]] = None,
     loading_joins: Optional[List[Any]] = None,
     order: Optional[List[Dict[str, str]]] = None
 ) -> List[Dict[str, Any]]:
@@ -441,31 +448,34 @@ async def list_entities(
         skip: 페이지네이션 시작 위치.
         limit: 페이지네이션 크기.
         filters: 필터 조건 딕셔너리.
-            예시:
-            filters = {
-                "search": {"field": "username", "operator": "like", "value": "%admin%"},
-                "name": {"field": "name", "operator": "like", "value": "%John%"},
-                "role_ulid": {"field": "role_ulid", "operator": "eq", "value": "1234"}
-            }
-
-        joins: 조인 옵션.
-            예시:
-            joins = [
-                selectinload(YourModel.related_field),  # 관련된 필드를 함께 로드
-                joinedload(YourModel.another_related_field)  # 다른 관계된 필드를 조인
-            ]
+        explicit_joins: 명시적 조인 대상 리스트
+            - 모델만 전달: 기본 outer join
+            - (모델, 조인조건): 조건부 outer join
+        loading_joins: 로딩 조인 옵션 리스트 (joinedload, selectinload 등)
+        order: 정렬 조건 리스트
 
     Returns:
         List[Dict[str, Any]]: 쿼리 결과 리스트.
     """
     try:
         # 기본 쿼리 생성
+        query = select(model)
+
+        # 명시적 조인 적용
         if explicit_joins:
-            query = select(model, *explicit_joins)
             for join_target in explicit_joins:
-                query = query.outerjoin(join_target)
-        else:
-            query = select(model)
+                if isinstance(join_target, tuple):
+                    # (모델, 조인조건)이 전달된 경우
+                    target_model, join_condition = join_target
+                    query = query.outerjoin(target_model, join_condition)
+                else:
+                    # 모델만 전달된 경우
+                    query = query.outerjoin(join_target)
+
+        # 로딩 조인 적용
+        if loading_joins:
+            for join_option in loading_joins:
+                query = query.options(join_option)
 
         # 필터 조건 적용
         if filters:
@@ -505,28 +515,51 @@ async def get_entity(
     session: AsyncSession,
     model: Type[ModelType],
     conditions: Dict[str, Any],
-    explicit_joins: Optional[List[Any]] = None,
+    explicit_joins: Optional[List[JoinTarget]] = None,
     loading_joins: Optional[List[Any]] = None
 ) -> ModelType:
+    """
+    조건에 맞는 단일 엔티티를 조회합니다.
+
+    Args:
+        session: SQLAlchemy AsyncSession
+        model: SQLAlchemy 모델
+        conditions: 조회 조건
+        explicit_joins: 명시적 조인 대상 리스트
+            - 모델만 전달: 기본 outer join
+            - (모델, 조인조건): 조건부 outer join
+        loading_joins: 로딩 조인 옵션 리스트 (joinedload, selectinload 등)
+
+    Returns:
+        ModelType: 조회된 엔티티 또는 None
+    """
     try:
+        # 기본 쿼리 생성
         query = select(model)
 
         # 명시적 조인 적용
         if explicit_joins:
             for join_target in explicit_joins:
-                query = query.outerjoin(join_target)
+                if isinstance(join_target, tuple):
+                    # (모델, 조인조건)이 전달된 경우
+                    target_model, join_condition = join_target
+                    query = query.outerjoin(target_model, join_condition)
+                else:
+                    # 모델만 전달된 경우
+                    query = query.outerjoin(join_target)
 
-        # 조인 로딩 적용
+        # 로딩 조인 적용
         if loading_joins:
             for join_option in loading_joins:
                 query = query.options(join_option)
 
+        # 조건 적용
         if conditions:
             for key, value in conditions.items():
                 query = query.where(getattr(model, key) == value)
 
         result = await session.execute(query)
-        return result.scalars().unique().one_or_none()
+        return result.unique().scalars().one_or_none()
 
     except SQLAlchemyError as e:
         raise CustomException(

aiteamutils/version.py

@@ -1,2 +1,2 @@
 """버전 정보"""
-__version__ = "0.2.164"
+__version__ = "0.2.165"

{aiteamutils-0.2.164.dist-info → aiteamutils-0.2.165.dist-info}/METADATA

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

{aiteamutils-0.2.164.dist-info → aiteamutils-0.2.165.dist-info}/RECORD

@@ -4,13 +4,13 @@ aiteamutils/base_repository.py,sha256=Oy2zE1i5qx60Xf1tnsaKLyFWapiPqt5JH8NejwNrPW
 aiteamutils/base_service.py,sha256=JIeRtFn1Ll4Qcq3v88pgS9lmEQLQoVyyOKqYR8n02S4,21192
 aiteamutils/cache.py,sha256=07xBGlgAwOTAdY5mnMOQJ5EBxVwe8glVD7DkGEkxCtw,1373
 aiteamutils/config.py,sha256=YdalpJb70-txhGJAS4aaKglEZAFVWgfzw5BXSWpkUz4,3232
-aiteamutils/database.py,sha256=msvBKtxWeQVOo0v2Q9i2azuTNtnUItuNNar52gdRZTo,20418
+aiteamutils/database.py,sha256=090b9M3o3nYsckVlfybC5LV7wUXS6n0Pve2yDOF_Y48,21669
 aiteamutils/enums.py,sha256=7WLqlcJqQWtETAga2WAxNp3dJTQIAd2TW-4WzkoHHa8,2498
 aiteamutils/exceptions.py,sha256=sgIVulllKMM9InTltaB7VD6i7DiQvCoycexsV-BiIBY,16570
 aiteamutils/files.py,sha256=fxnCu9rErd4vCovMi0jy4adLUiA7rx_q4RdOL4wSgsU,14258
 aiteamutils/security.py,sha256=McUl3t5Z5SyUDVUHymHdDkYyF4YSeg4g9fFMML4W6Kw,11630
 aiteamutils/validators.py,sha256=_WHN6jqJQzKM5uPTg-Da8U2qqevS84XeKMkCCF4C_lY,9591
-aiteamutils/version.py,sha256=-1PoiD8Z2iKKFhSAXH5iLm2cqOxR9FYl9lzaqFbsdAA,43
-aiteamutils-0.2.164.dist-info/METADATA,sha256=ex8xQEve_D8XGz7Kqk4yhcazmGqE8fxYzKqOVkbBp5E,1743
-aiteamutils-0.2.164.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-aiteamutils-0.2.164.dist-info/RECORD,,
+aiteamutils/version.py,sha256=TC_spO53XsoBjGPdVSQjcP1vTh3Fno23EerP6g6nB58,43
+aiteamutils-0.2.165.dist-info/METADATA,sha256=lRRin2H5r_RB8ha8ciB7hZo4fl-2M1C-L-c9V7SwOXA,1743
+aiteamutils-0.2.165.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+aiteamutils-0.2.165.dist-info/RECORD,,