Python의 폴더 구조와 import 정리

1. Python 기본 모듈 검색 원리

Python은 현재 작업 디렉토리(os.getcwd())와 sys.path에 포함된 경로에서 모듈을 검색합니다.
import가 작동하려면 다음 조건이 충족되어야 합니다:

1. 모듈 또는 패키지가 Python이 검색할 수 있는 경로에 있어야 합니다.
2. 패키지 폴더에는 __init__.py 파일이 있어야 패키지로 인식됩니다. (Python 3.3 이상에서는 선택 사항)

 

2. 추천 프로젝트 구조

Python 프로젝트에서 흔히 사용하는 기본 디렉토리 구조는 다음과 같습니다.

 

project/
├── main.py           # 진입점 파일
├── core/             # 모듈과 패키지 폴더
│   ├── __init__.py   # core를 패키지로 인식시키는 파일 (빈 파일 가능)
│   ├── strategy.py   # 실제 모듈 파일
│   └── utils.py      # 기타 유틸리티 파일
└── requirements.txt  # 의존성 패키지 (옵션)

 

 

3. 폴더 구조와 import 매칭

 

폴더 구조와 import는 다음과 같이 매핑됩니다.

예시 1: 같은 폴더 안의 파일

project/
├── main.py
├── strategy.py

 

main.py에서 strategy.py를 가져오기

import strategy
# 또는
from strategy import SomeClass

 

예시 2: 하위 폴더의 파일

project/
├── main.py
├── core/
│   ├── __init__.py
│   └── strategy.py

 

main.py에서 core/strategy.py를 가져오기

from core.strategy import SomeClass

 

4. __init__.py의 역할

• __init__.py 파일은 폴더를 패키지로 만들어줍니다.
• Python 3.3 이상에서는 없어도 작동하지만, 명시적으로 넣는 것이 좋습니다.
• 예를 들어, core/__init__.py를 작성하면 core를 모듈처럼 가져올 수 있습니다.

from core import strategy

 

5. 코드 실행 위치의 중요성

Python의 현재 디렉토리 기준

• Python은 현재 디렉토리를 기준으로 경로를 찾습니다.
• 예를 들어, main.py를 실행할 때

cd path/to/project
python main.py

• 중요: 현재 디렉토리가 main.py가 있는 project 폴더여야 합니다.

 

6. import 문제를 예방하는 팁

sys.path를 수정

문제가 계속된다면, sys.path에 프로젝트 루트를 명시적으로 추가할 수 있습니다.이 코드를 main.py의 최상단에 넣어 경로 문제를 방지합니다.

import sys
import os
sys.path.append(os.path.dirname(os.path.abspath(__file__)))

 

모듈 이름 중복 피하기

core.py, strategy.py 같은 파일 이름이 Python 기본 라이브러리와 충돌하지 않도록 주의하세요.