Python 프로젝트 구성

파이썬 프로젝트 구조와 테스트 설정

많은 파이썬 프로젝트에서는 실제 코드와 테스트 코드를 명확히 분리하기 위해 다음과 같은 구조를 사용

기본 디렉터리 구조

project_name/
├── src/
│   └── my_module/
│       ├── __init__.py
│       └── person.py
├── tests/
│   ├── conftest.py
│   └── test_person.py
├── main.py
├── pytest.ini
├── pyproject.toml
└── setup.py

설계적 고찰

1. 객체지향 프로그래밍 원칙 반영

클래스는 본질적으로 하나의 책임(SRP: Single Responsibility Principle)을 가지도록 설계해야 함

이 책임을 잘 구분하려면 파일 단위로 논리적 경계를 나누는 것이 필요

• person.py에 Person 클래스만 정의하는 이유는 “사람”이라는 하나의 책임만 다루기 위함
• Animal, Plant 같은 다른 클래스를 추가할 경우에도 각자의 모듈로 독립시켜야 유지보수가 쉬워짐

이러한 방식은 캡슐화(encapsulation)와도 연결됨

즉, 각 클래스는 내부 구현을 감추고 외부에는 필요한 기능만 노출함

모듈 단위로 클래스를 분리하면 이 구조가 자연스럽게 반영됨

2. 유지보수성과 확장성 향상

하나의 파일에 여러 클래스나 기능이 뒤섞여 있을 경우

• 코드 파악이 어려움
• 협업 중 충돌 가능성이 높음
• 테스트하기 까다로움

반면, 클래스를 모듈 단위로 나누면 다음과 같은 이점이 있음

• 필요한 파일만 열어서 수정 가능 (탐색 비용 ↓)
• Git 충돌 방지 (병렬 작업 효율 ↑)
• 리팩토링 시 영향 범위 최소화

또한 대규모 프로젝트에서 폴더 구조만 봐도 시스템의 전체적인 개념도를 파악할 수 있음

3. 테스트 편의성

테스트는 기능별로 명확히 나뉜 모듈일수록 작성과 실행이 용이함

예를 들어 test_person.py에서 person.py를 전담 테스트 → 테스트의 직관성과 신뢰도 향상

아래와 같이 자동화 가능

• pytest로 전체 테스트 일괄 실행
• CI/CD에서 테스트 경로 명시 (tests/만 실행)

✅ 결론: 설계와 구조는 생산성을 위한 도구

클래스를 모듈로 분리하고, src/ 구조를 사용하는 것은 단순한 스타일 선택이 아닙니다. 이는 코드의 명확성, 테스트 용이성, 확장성, 협업의 효율성 등 실질적인 개발 생산성과 품질을 높이기 위한 방법입니다.

이러한 설계 철학은 소규모 프로젝트에서도 유효하며, 규모가 커질수록 그 진가를 발휘합니다.