Python 프로젝트 폴더 구조 가이드

by

Python 프로젝트를 만들 때 코드 구조를 정리하면 유지보수와 확장성이 좋아집니다.
아래는 일반적인 폴더 구조, 웹 애플리케이션, 라이브러리 패키지의 구조를 설명합니다. 🚀

📌 1️⃣ 기본적인 파이썬 프로젝트 구조

일반적인 파이썬 프로젝트는 아래와 같은 구조를 가집니다.

my_project/               # 🔹 프로젝트 루트 디렉토리
│── src/                  # 🔹 실제 소스 코드 디렉토리
│   │── my_package/       #   ✅ 패키지 디렉토리
│   │   │── __init__.py   #   ✅ 패키지 초기화 파일
│   │   │── module1.py    #   ✅ 모듈 파일
│   │   │── module2.py
│
│── tests/                # 🔹 테스트 코드 디렉토리
│   │── test_module1.py
│   │── test_module2.py
│
│── pyproject.toml        # 🔹 패키지 설정 파일 (PEP 621)
│── setup.py              # 🔹 (구버전) 패키지 설정 파일
│── requirements.txt      # 🔹 의존성 목록
│── README.md             # 🔹 프로젝트 설명 파일
│── LICENSE               # 🔹 라이선스 파일
│── .gitignore            # 🔹 Git 제외할 파일 목록

📌 설명

  • src/ → 실제 코드가 있는 디렉토리
  • tests/ → 테스트 코드 (pytest 사용 권장)
  • pyproject.toml → 패키지 빌드/설정 파일 (추천)
  • setup.py → 패키지화할 때 사용 (구버전)
  • requirements.txt → 필요한 라이브러리 목록

✅ src/ 폴더 구조를 사용하는 것이 최근 Best Practice!

  • import 충돌 방지 (sys.path 문제 해결)
  • pip install -e . 사용 시 가독성 증가

📌 2️⃣ 웹 애플리케이션 구조 (FastAPI, Django, Flask 등)

웹 프레임워크를 사용하는 경우, 아래와 같은 구조를 추천합니다.

my_webapp/
│── src/
│   │── app/                # 🔹 웹 애플리케이션 코드
│   │   │── __init__.py
│   │   │── main.py         #   ✅ FastAPI/Django/Flask 엔트리포인트
│   │   │── routers/        #   ✅ API 엔드포인트 폴더 (FastAPI)
│   │   │   │── user.py
│   │   │   │── product.py
│   │   │── models/         #   ✅ 데이터베이스 모델 (ORM)
│   │   │── services/       #   ✅ 비즈니스 로직
│   │   │── config.py       #   ✅ 설정 파일 (.env 로드)
│   │
│── tests/                  # 🔹 테스트 코드
│── migrations/             # 🔹 DB 마이그레이션 (Alembic, Django)
│── pyproject.toml          # 🔹 프로젝트 설정
│── .env                    # 🔹 환경 변수 파일
│── README.md               # 🔹 설명 파일
│── Dockerfile              # 🔹 도커 설정 파일
│── .gitignore              # 🔹 Git 제외 목록

📌 설명

  • routers/ → API 엔드포인트
  • models/ → DB 모델 (SQLAlchemy, Django ORM 등)
  • services/ → 주요 로직 처리
  • .env → 환경 변수 저장

✅ 이 구조를 사용하면 유지보수가 편리하고 코드가 깔끔해집니다.

📌 3️⃣ 라이브러리/패키지 프로젝트 구조

라이브러리를 개발할 때는 아래 구조를 추천합니다.

my_library/
│── src/
│   │── my_library/         # 🔹 라이브러리 패키지
│   │   │── __init__.py
│   │   │── core.py         #   ✅ 주요 기능
│   │   │── utils.py        #   ✅ 유틸리티 함수
│   │
│── tests/                  # 🔹 테스트 코드
│── examples/               # 🔹 사용 예제 코드
│── docs/                   # 🔹 문서화 (Sphinx 등)
│── pyproject.toml          # 🔹 패키지 설정 파일
│── requirements.txt        # 🔹 의존성 목록
│── README.md               # 🔹 설명 파일
│── LICENSE                 # 🔹 라이선스 파일

📌 설명

  • my_library/ → 실제 패키지 코드
  • examples/ → 라이브러리 사용 예제
  • docs/ → 문서화 (Sphinx 사용 가능)
  • tests/ → 테스트 코드 (pytest 추천)

✅ 이 구조를 사용하면 PyPI 배포 시 깔끔한 패키지가 됩니다.

📌 4️⃣ CLI(Command Line Interface) 프로젝트

CLI 프로그램을 개발할 경우, 실행 가능한 스크립트를 포함해야 합니다.

my_cli_tool/
│── src/
│   │── cli_tool/           # 🔹 CLI 패키지
│   │   │── __init__.py
│   │   │── main.py         #   ✅ CLI 엔트리포인트
│   │   │── commands/       #   ✅ 명령어 모듈
│   │       │── start.py
│   │       │── stop.py
│
│── tests/                  # 🔹 테스트 코드
│── pyproject.toml          # 🔹 패키지 설정 파일
│── README.md               # 🔹 설명 파일
│── LICENSE                 # 🔹 라이선스 파일

📌 설명

  • cli_tool/main.py → CLI의 실행 파일
  • commands/ → 여러 명령어를 처리하는 모듈

✅ CLI 툴을 만들 때는 argparse 또는 click 라이브러리를 사용하면 편리합니다.

📌 5️⃣ 데이터 분석/머신러닝 프로젝트

데이터 분석, AI 모델을 다루는 경우 아래 구조를 추천합니다.

my_ml_project/
│── data/                   # 🔹 데이터 폴더 (원본 및 가공 데이터)
│   │── raw/                #   ✅ 원본 데이터
│   │── processed/          #   ✅ 가공된 데이터
│
│── notebooks/              # 🔹 Jupyter 노트북 폴더
│   │── exploration.ipynb   #   ✅ 데이터 분석
│   │── model_training.ipynb
│
│── src/                    # 🔹 ML 코드
│   │── ml_pipeline/        #   ✅ ML 파이프라인 코드
│   │   │── preprocess.py   #   ✅ 데이터 전처리
│   │   │── train.py        #   ✅ 모델 학습
│   │   │── predict.py      #   ✅ 예측
│
│── tests/                  # 🔹 테스트 코드
│── pyproject.toml          # 🔹 패키지 설정
│── requirements.txt        # 🔹 의존성 목록
│── README.md               # 🔹 설명 파일

📌 설명

  • data/ → 데이터 저장
  • notebooks/ → Jupyter 노트북
  • src/ml_pipeline/ → 모델 훈련, 예측 코드

✅ ML 프로젝트는 코드와 데이터를 명확하게 분리하는 것이 중요합니다.

📌 정리

프로젝트 유형 추천 폴더 구조
기본 파이썬 프로젝트 src/, tests/, pyproject.toml
웹 애플리케이션 routers/, models/, services/
라이브러리 패키지 examples/, docs/, tests/
CLI 도구 commands/, main.py
머신러닝/데이터 분석 data/, notebooks/, ml_pipeline/

✅ 프로젝트에 맞는 구조를 사용하면 유지보수와 확장성이 좋아집니다! 🚀

Leave a Comment