파이썬 모듈과 패키지

파이썬에서 .py 파일 하나가 모듈(module)이고, 모듈을 모은 디렉터리가 패키지(package)다. import는 다른 모듈의 변수·함수·클래스에 접근할 수 있게 해 주고, 모듈은 처음 import될 때 한 번만 실행된 뒤 캐시된다(sys.modules).

import json
import numpy as np
from pathlib import Path
from .models import Movie        # 패키지 안 상대 import

모듈을 찾는 순서

1. 내장 모듈
2. sys.path의 디렉터리를 차례로: 실행한 스크립트의 디렉터리, PYTHONPATH 환경변수, 설치된 라이브러리(site-packages)

내 파일 이름을 json.py, random.py처럼 표준 모듈과 같게 지으면 표준 모듈 대신 내 파일이 import된다.

메인 모듈과 __name__

파이썬에는 main 함수가 따로 없다. 직접 실행한 파일이 메인 모듈이 되고 그 모듈의 __name__은 "__main__"이다. import된 모듈의 __name__은 모듈 이름이다.

def main(): ...
 
if __name__ == "__main__":       # 직접 실행할 때만
    main()

이렇게 두면 import할 때는 실행되지 않아 테스트나 재사용이 쉽다.

패키지

• 디렉터리에 __init__.py가 있으면 일반 패키지다. 파이썬 3.3부터는 없어도 네임스페이스 패키지(namespace package)로 import되지만, 명시적으로 두는 편이 혼란이 적다
• __init__.py는 보통 비워 두거나 공개 API를 다시 내보내는 데 쓴다. __all__은 from pkg import *가 가져올 이름 목록이다
• import *는 어떤 이름이 들어오는지 코드만 봐서는 알 수 없어 피한다

서드파티 모듈

pip로 PyPI(Python Package Index)에서 설치하고, 프로젝트마다 가상환경(virtual environment, python -m venv .venv → source .venv/bin/activate)으로 의존성을 분리한다(환경변수 스코프와 source). 요즘은 uv 같은 더 빠른 도구도 많이 쓴다(2026 기준).

공개 API를 한 곳에서 다시 내보내는 방식은 자바스크립트의 배럴 파일과 re-export과, 모듈 시스템 자체는 ES 모듈과 CommonJS와 비교해 보면 좋다. 이름이 어디서 오는지는 파이썬 스코프 (LEGB)를 본다.

출처: Python 튜토리얼: Modules · Module Search Path · Executing modules as scripts · Packages