feat(types): add CrudFilter TypedDict definitions

[ywkim]

요약

• CrudFilter TypedDict 추가 (Refine 호환)
• protocols.py → types.py 이름 변경 (Python 커뮤니티 관례)
• _build_filter_conditions 반환 타입을 list[ColumnElement[bool]]로 명시

변경 사항

새 타입 정의 (types.py)

• LogicalFilter: 단일 필드 필터 (field, operator, value)
• ConditionalFilter: OR/AND 조합 필터
• CrudFilter: LogicalFilter | ConditionalFilter
• FilterOperator, ConditionalOperator: Literal 타입

타입 개선

• filters: list[dict[str, Any]] → list[CrudFilter]
• _build_filter_conditions 반환: list[Any] → list[ColumnElement[bool]]

Breaking Changes

• from aioia_core.protocols import ... → from aioia_core.types import ...
• from aioia_core import ...는 영향 없음 (re-export 유지)

체크리스트

• 테스트 통과
• pyright 타입 체크 통과

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This PR significantly enhances type safety by introducing TypedDict definitions for CrudFilter, renaming protocols.py to types.py, and explicitly typing the return of _build_filter_conditions. However, the implementation of dynamic filtering and sorting lacks proper validation of field names, which could lead to information exposure or Denial of Service. Additionally, the recursive processing of nested filters is susceptible to stack overflow attacks due to the absence of a recursion depth limit. To further improve type safety, consider clarifying the TypedDict definitions for LogicalFilter and ConditionalFilter.

[Copilot]

Pull request overview

이 PR은 CrudFilter TypedDict 정의를 추가하고 protocols.py를 types.py로 이름을 변경합니다. Refine 프레임워크와 호환되는 필터 구조를 정의하며, 타입 안정성을 개선하기 위해 제네릭 dict[str, Any] 대신 구조화된 타입을 도입합니다.

Changes:

• LogicalFilter와 ConditionalFilter TypedDict 정의 추가
• protocols.py → types.py 이름 변경 및 모든 import 경로 업데이트
• _build_filter_conditions 반환 타입을 list[ColumnElement[bool]]로 명시

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
python/aioia_core/types.py	새로운 필터 타입 정의 추가 (LogicalFilter, ConditionalFilter, CrudFilter) 및 프로토콜 정의 포함
python/aioia_core/repositories.py	필터 파라미터 타입을 CrudFilter로 변경하고 반환 타입 명시 개선
python/aioia_core/fastapi/base_crud_router.py	import 경로 업데이트 및 _decamelize_filter_fields에 타입 캐스팅 추가
python/tests/unit/test_base_repository.py	CrudFilter 타입 사용 및 테스트 변수명 개선
python/aioia_core/testing/crud_fixtures.py	import 경로 업데이트 및 필터 처리 로직 개선 (.get() 사용)
python/aioia_core/factories/base_repository_factory.py	import 경로 업데이트
python/aioia_core/factories/base_manager_factory.py	import 경로 업데이트
python/aioia_core/init.py	새로운 필터 타입 re-export 추가

Comments suppressed due to low confidence (2)

python/aioia_core/types.py:43

• TypedDict의 total=False 설정으로 인해 모든 필드가 optional이 됩니다. LogicalFilter의 경우 field, operator, value 필드가 모두 필수이며, ConditionalFilter의 경우 operator와 value 필드가 필수입니다.

total=False를 제거하고 선택적 필드만 NotRequired로 표시하는 것을 권장합니다. 또는 LogicalFilter의 경우 value 필드만 optional이고 (null/nnull 연산자는 value가 필요 없음), 나머지는 required로 정의해야 합니다.

예시:

class LogicalFilter(TypedDict):
    field: str
    operator: FilterOperator
    value: NotRequired[Any]

python/aioia_core/types.py:58

• TypedDict의 total=False 설정으로 인해 모든 필드가 optional이 됩니다. ConditionalFilter의 경우 operator와 value 필드가 모두 필수입니다.

total=False를 제거하여 모든 필드를 required로 만들어야 합니다.

예시:

class ConditionalFilter(TypedDict):
    operator: ConditionalOperator
    value: list[CrudFilter]

[Copilot]

line 562에서 이미 "field" in filter_item을 확인했으므로, filter_item.get("field", "")는 항상 값을 반환합니다. str() 변환이 불필요합니다.

다음과 같이 단순화할 수 있습니다:

"field": decamelize(filter_item["field"])

또는 타입 안정성을 위해:

"field": decamelize(str(filter_item["field"]))

Suggested change

	"field": decamelize(str(filter_item.get("field", ""))),
	"field": decamelize(str(filter_item["field"])),

[ywkim]

mypy는 in 체크로 TypedDict narrowing을 지원하지 않아 filter_item["field"] 직접 접근 시 typeddict-item 에러 발생.

aioia_core/fastapi/base_crud_router.py:566: error: TypedDict "ConditionalFilter" has no key "field"  [typeddict-item]

.get() 유지 필요.

suppressed 제안(NotRequired 패턴)은 b88e19f에서 적용 완료.

[ywkim]

/gemini review

[gemini-code-assist]

Code Review

이 PR은 CrudFilter TypedDict 정의를 추가하고 protocols.py를 types.py로 변경하여 코드의 타입 안정성과 가독성을 크게 향상시켰습니다. 필터 구조가 명확해지고, 관련 코드에서 타입 힌트가 개선되어 유지보수성이 높아졌습니다. 특히 _build_filter_conditions 메서드의 반환 타입 명시는 매우 훌륭한 개선입니다. 전반적으로 잘 구현된 변경사항입니다.

[gemini-code-assist]

filter_item이 LogicalFilter 타입인 경우, field는 필수 필드이므로 .get() 메서드 대신 filter_item["field"]와 같이 직접 접근하는 것이 TypedDict의 의도를 더 명확하게 반영합니다. elif "field" in filter_item: 조건문으로 이미 field 키의 존재 여부를 확인하고 있으므로 안전합니다. 또한 LogicalFilter의 field는 이미 str 타입이므로 str() 캐스팅도 불필요합니다.

Suggested change

	"field": decamelize(str(filter_item.get("field", ""))),
	"field": decamelize(filter_item["field"])

[ywkim]

mypy는 in 체크로 TypedDict narrowing을 지원하지 않아 filter_item["field"] 직접 접근 시 에러 발생:

aioia_core/fastapi/base_crud_router.py:566: error: TypedDict "ConditionalFilter" has no key "field"  [typeddict-item]

pyright는 통과하지만 mypy 호환을 위해 .get() 유지 필요.

[ywkim]

TypeGuard 적용으로 .get() 제거 및 직접 접근 사용.

def is_logical_filter(f: CrudFilter) -> TypeGuard[LogicalFilter]:
    return "field" in f

5930606, fa36524 커밋 참조.

[ywkim]

/gemini review

[gemini-code-assist]

Code Review

이 PR은 CrudFilter TypedDict 정의를 추가하고 protocols.py를 types.py로 이름을 변경하여 코드베이스 전반의 타입 안정성을 크게 향상시켰습니다. 새로운 타입을 도입하고 이를 코드 전체에 일관되게 적용하여 정적 분석을 용이하게 하고 유지보수성을 높인 점이 훌륭합니다. 한 가지 제안 사항으로, 테스트 목(mock) 객체가 프로토콜을 올바르게 준수하도록 수정하여 코드의 일관성과 신뢰성을 더욱 높일 수 있습니다.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (2)

python/aioia_core/types.py:231

• 타입 가드 함수 is_logical_filter와 is_conditional_filter가 __all__ 목록에 포함되지 않았습니다. 이 함수들은 __init__.py에서 re-export되고 있으므로, 일관성을 위해 types.py의 __all__에도 추가해야 합니다.
  python/aioia_core/types.py:82
• 새로 추가된 타입 가드 함수 is_logical_filter와 is_conditional_filter에 대한 테스트 커버리지가 없습니다. 다른 함수들과 마찬가지로 이 함수들도 테스트해야 합니다. 예를 들어, 각 타입 가드가 올바른 필터 구조를 식별하고 잘못된 구조를 거부하는지 테스트해야 합니다.

[github-actions]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀