[PYTHON] 내가 만든 .py 모듈 불러오기 : 프로젝트 구조 설계와 임포트 경로의 모든 것

.py 모듈 불러오기

 

파이썬을 사용하여 대규모 프로젝트를 진행하다 보면 하나의 파일에 모든 코드를 담는 것이 불가능해집니다. 코드의 가독성, 재사용성, 그리고 유지보수 효율을 높이기 위해 기능을 단위별로 쪼개어 별도의 .py 파일(모듈)로 관리하는 것은 필수적인 과정입니다. 하지만 초보 개발자들이 가장 많이 겪는 난관 중 하나가 바로 "내가 만든 파일을 왜 불러오지 못할까?"라는 경로(Path) 문제입니다. 본 가이드에서는 모듈 임포트의 기본 원리부터 패키지 구조 설계, 그리고 sys.path를 활용한 고급 경로 제어 기법까지 심도 있게 다룹니다.

1. 모듈 임포트의 기본 원리

파이썬에서 import 문을 실행하면 인터프리터는 정해진 순서에 따라 해당 모듈 파일을 탐색합니다. 이 탐색 경로를 이해하지 못하면 ModuleNotFoundError의 늪에서 벗어나기 어렵습니다.

1. Built-in Modules	파이썬 인터프리터에 내장된 표준 모듈 (예: sys, time)	항상 최우선 탐색
2. Current Directory	현재 실행 중인 스크립트가 위치한 경로	사용자 정의 파일 임포트의 핵심
3. PYTHONPATH	환경 변수에 설정된 경로 리스트	프로젝트 외부 경로 설정 시 사용
4. Standard Libraries	설치된 외부 패키지 및 표준 라이브러리 경로	site-packages 포함

2. 동일 디렉토리 내 모듈 불러오기

가장 단순한 형태입니다. 불러오려는 파일(mylib.py)과 불러오는 주체(main.py)가 같은 폴더에 있다면 파일명만으로 즉시 사용이 가능합니다.

구조:
project/
├── mylib.py
└── main.py

# mylib.py
def say_hello():
    return "안녕하세요! 커스텀 모듈입니다."

# main.py
import mylib

result = mylib.say_hello()
print(result) # 출력: 안녕하세요! 커스텀 모듈입니다.

3. 패키지(하위 폴더) 구조에서의 임포트

코드가 많아지면 폴더별로 기능을 묶게 됩니다. 이때부터는 도트 연산자(.)를 활용한 패키지 임포트 방식을 사용해야 합니다.

구조:
project/
├── main.py
└── utils/
    ├── __init__.py
    └── calculator.py

파이썬 3.3 버전 이후부터는 필수 사항은 아니지만, 특정 폴더를 패키지로 인식시키기 위해 __init__.py 파일을 생성하는 것이 관례입니다. main.py에서 calculator.py를 불러오는 방법은 다음과 같습니다.

# calculator.py (utils 폴더 내부)
def add(a, b):
    return a + b

# main.py (루트 폴더)
from utils.calculator import add

print(add(10, 20)) # 출력: 30

4. 상위 폴더 또는 외부 경로 모듈 불러오기

가장 까다로운 케이스입니다. 실행 시점의 현재 경로보다 상위에 있거나 아예 다른 경로에 있는 파일을 불러올 때는 파이썬의 시스템 경로 리스트인 sys.path에 해당 경로를 명시적으로 추가해주어야 합니다.

주의: 상대 경로(from .. import module) 방식은 해당 파일이 직접 실행되는 메인 스크립트일 경우 ImportError를 발생시킵니다. 따라서 절대 경로 설정을 권장합니다.

import sys
import os

# 현재 파일의 부모 디렉토리 경로를 시스템 경로에 추가
current_path = os.path.dirname(os.path.abspath(__file__))
parent_path = os.path.join(current_path, '..')
sys.path.append(parent_path)

# 이제 상위 폴더의 모듈을 임포트할 수 있습니다.
import my_parent_module

5. __name__ == "__main__"의 중요성

모듈을 임포트한다는 것은 해당 파일의 코드를 처음부터 끝까지 실행한다는 뜻입니다. 만약 모듈 파일 내부에 테스트용 print() 문이나 실행 코드가 있다면, 임포트하는 순간 의도치 않게 실행될 것입니다. 이를 방지하기 위해 모듈 하단에는 반드시 다음 구문을 사용해야 합니다.

# mylib.py
def core_logic():
    pass

if __name__ == "__main__":
    # 이 부분은 mylib.py를 직접 실행할 때만 동작합니다.
    # 다른 파일에서 import mylib 할 때는 실행되지 않습니다.
    print("모듈 테스트 코드 실행")

6. 결론: 효율적인 프로젝트 관리를 위하여

파이썬 모듈 시스템은 유연하지만 엄격한 규칙을 따릅니다. 첫째, 가능하면 프로젝트의 루트 디렉토리에서 메인 스크립트를 실행하십시오. 둘째, 폴더 구조를 명확히 하고 from 패키지.모듈 import 함수 형태를 애용하십시오. 셋째, 복잡한 경로 문제는 sys.path 조작보다는 PYTHONPATH 환경 변수 설정을 고려해보는 것도 좋은 대안입니다. 이러한 구조적 이해는 곧 견고한 소프트웨어 아키텍처의 밑바탕이 될 것입니다.

---

참고 문헌 및 출처 (Sources)

• Python Software Foundation. "Modules." The Python Tutorial.
• Python Software Foundation. "sys.path — Module search path." Library Reference.
• Luciano Ramalho. "Fluent Python." O'Reilly Media.
• Real Python. "Python Modules and Packages: An Introduction."