Python 강좌 / 패키지 구조와 프로그램 실행 진입점 이해하기

Python 강좌

패키지는 관련 모듈을 계층으로 묶는 단위입니다. 실행 코드를 main 함수와 명시적인 진입점에 두면 모듈을 import할 때 프로그램이 자동 실행되는 일을 피할 수 있습니다.

패키지 폴더와 실행 기준점

여기서는 __init__.py가 있는 일반 패키지를 만듭니다. 일부 패키지는 이 파일 없이 네임스페이스 패키지로 구성되지만, 입문 단계에서는 일반 패키지의 명시적인 구조를 사용합니다. 실행은 expense_app 폴더 안이 아니라 그 상위 프로젝트 폴더에서 합니다.

project/
  expense_app/
    __init__.py
    math_tools.py
    __main__.py

expense_app/__init__.py 파일의 전체 내용입니다.

"""지출 계산 패키지."""

expense_app/math_tools.py 파일의 전체 내용입니다.

def total(amounts):
    return sum(amounts)

expense_app/__main__.py 파일의 전체 내용입니다.

from .math_tools import total

def main():
    print(total([3500, 8000, 2500]))

if __name__ == "__main__":
    main()

project 폴더에서 다음 명령을 실행하면 14000이 출력됩니다.

python -m expense_app

-m은 모듈 탐색 규칙으로 대상을 찾아 실행합니다. __main__.py의 상대 import는 패키지 맥락이 필요하므로 python expense_app/__main__.py로 직접 파일을 실행하는 방식과 다릅니다.

실행 대상의 __name__은 __main__이 됩니다. 다른 곳에서 import한 모듈은 패키지·모듈 이름을 가집니다. 이 차이로 직접 실행할 때만 main을 호출합니다. 함수 정의만 최상위에 두어도 계산이나 파일 변경은 호출 시점까지 미룰 수 있습니다.

데이터 파일을 찾는 기준과 모듈을 찾는 기준은 다릅니다. 상대 파일 경로는 현재 작업 폴더의 영향을 받으므로 배포할 프로그램에서는 명시적인 경로 인수나 패키지 리소스 기능을 검토합니다.

python -c "import expense_app.__main__; print('imported')"

위 명령에서는 imported만 나와야 합니다. 합계까지 출력된다면 import 시 실행되는 코드가 남아 있는지 확인합니다. 프로그램 실행과 재사용 가능성을 따로 확인하는 간단한 방법입니다.

폴더 이름을 바꾸면 import 경로와 실행 명령도 함께 수정합니다. 패키지를 공개 저장소에 배포하는 과정은 파일 구조를 만드는 작업과 다르며 pyproject.toml·빌드·설치 검증이 추가로 필요합니다.

Python 강좌