[Python Cheatsheet] 14. Modules & Imports - 구조/엔트리포인트

모듈과 패키지 구조는 프로젝트 규모가 커질수록 중요해집니다. 이 치트시트는 import 패턴, __name__ == "__main__" 가드, sys.path 함정, 순환 import 해결 등을 정리합니다.

언제 이 치트시트를 보나?

• “같은 파일인데 import가 안 된다” 같은 경로/패키지 문제를 만났을 때
• 스크립트 실행과 라이브러리 사용을 동시에 지원하고 싶을 때

핵심 패턴

• 엔트리포인트 가드:
  • if __name__ == "__main__": main()
• 상대 import는 패키지 내부에서만(스크립트로 직접 실행 시 깨질 수 있음)
• 순환 import가 나면 “공통 의존”을 분리하거나 import 위치를 조정

최소 예제

1
2
3
4
5

def main():
    print("run")

if __name__ == "__main__":
    main()

1
2
3

# 절대 import 예시
import json
from pathlib import Path

자주 하는 실수/주의점

• 실행 위치(cwd)에 따라 import가 우연히 되거나 깨질 수 있음 → 패키지 구조로 정리
• sys.path를 런타임에 수정하는 방식은 임시방편이 되기 쉬움
• 파일명이 json.py 같은 표준 라이브러리와 충돌하면 import가 꼬일 수 있음

관련 링크(공식 문서)

• Modules (Tutorial)
• The import system