Python에서 네임스페이스 패키지와 일반 패키지 비교 — mypy가 실패하는 이유

카테고리

프로그래밍/소프트웨어 개발

서브카테고리

개발 툴

대상자

AI 개발자, 데이터 팀, 모듈형 파이프라인/공유 도구 개발자 — 중급 이상의 Python 경험자

핵심 요약

• 네임스페이스 패키지는 init.py 파일이 없어도 다중 폴더/리포지토리에서 사용 가능하지만, mypy나 정적 분석 도구와 호환성 문제 발생 가능
• mypy 구성 변경(--namespace-packages, MYPYPATH 설정) 및 가상 init.pyi 파일 추가가 해결 방안
• 모듈형 AI/ML 시스템 및 공유 도구 개발 시 네임스페이스 패키지 사용이 일반적

섹션별 세부 요약

1. 일반 패키지 vs 네임스페이스 패키지

• 일반 패키지: init.py 필수, 단일 폴더 내 자가포함 구조, mypy/IDE 분석 용이
• 네임스페이스 패키지: init.py 불필요, 다중 폴더/리포지토리 간 공유 가능, 정적 분석 도구 호환성 저하
• 예시 구조:

```python

src/coretools/featurestore/encoder.py

libs/featurestore/scaler.py

```

→ coretools.featurestore.encoder와 libs.featurestore.scaler 동일한 import 경로 사용 가능

2. AI/데이터 팀이 반드시 알아야 할 이유

• 모듈형 파이프라인: 학습 로직과 피처 저장소가 다른 리포지토리에 분리된 경우
• 플러그인 시스템: 실험 추적, 커스텀 메트릭, 전처리 레이어 구현 시
• 공유 AI 도구: 내부 라이브러리 간 이미 네임스페이스 사용 중인 경우

3. mypy가 네임스페이스 패키지에서 실패하는 이유

• 정적 분석 도구의 인식 불가: 네임스페이스 패키지의 다중 폴더 구조로 인해 모듈 경로 추적 실패
• 타입 추론 오류: mypy가 init.py 파일이 없는 폴더의 모듈을 인식하지 못함

4. mypy 문제 해결 체크리스트

• 네임스페이스 지원 활성화

```bash

mypy --namespace-packages

# 또는 mypy.ini에 [mypy] namespace_packages = true 설정

```

• 모듈 경로 명시: -p your.package.name 사용

```bash

mypy -p featurestore.encoder

```

• 비표준 구조 대응: MYPYPATH 설정 + --explicit-package-bases

```bash

export MYPYPATH=src

mypy --explicit-package-bases -p yourpkg.module

```

• 가상 init.pyi 파일 추가: 도구가 구조를 추론하도록 도움

결론

• 네임스페이스 패키지 사용 시 mypy 구성 변경 및 init.pyi 파일 추가가 필수, 모듈형 AI/ML 시스템 개발자에게 핵심 팁
• "Namespace packages는 정적 분석 도구와의 호환성을 위해 명시적인 설정이 필요하다"