Python 프로젝트를 체계적으로 구성하면 유지보수가 쉬워지고 다른 개발자가 코드를 이해하기도 한결 수월해집니다. 이 글에서는 널리 알려진 모범 사례를 따르는 샘플 프로젝트인 kennethreitz/samplemod를 기준으로, 'sample' 모듈을 만들 때 권장되는 디렉터리 구조와 각 파일의 역할을 살펴봅니다.
권장 디렉터리 구조
README.rst LICENSE setup.py requirements.txt sample/__init__.py sample/core.py sample/helpers.py docs/conf.py docs/index.rst tests/test_basic.py tests/test_advanced.py
각 파일과 디렉터리의 역할
README.rst
모듈에 대한 간략한 소개, 설치 방법, 사용 예시 등을 담는 파일입니다. 프로젝트의 첫인상을 결정하는 문서이므로 핵심 정보를 명확하게 정리하는 것이 좋습니다.
LICENSE
라이선스 전문과 저작권 관련 내용이 포함됩니다. 오픈소스로 배포할 경우 어떤 조건으로 사용·수정·배포가 가능한지 명시하는 필수 요소입니다.
setup.py
Python 생태계에서 멀티 플랫폼 설치 및 빌드를 담당하는 파일입니다. 명령줄 빌드 도구에 익숙하다면 make && make install이 python setup.py build && python setup.py install에 해당한다고 이해하면 쉽습니다. 즉, 사용자 환경에서 프로젝트를 빌드하고 설치하는 데 사용됩니다.
requirements.txt
Pip 요구 사항 파일로, 프로젝트에 기여하는 데 필요한 의존성(테스트, 빌드, 문서 생성용 패키지)을 지정합니다. 개발용 의존성이 없거나 setup.py를 통해 개발 환경을 구성하는 것을 선호한다면 이 파일은 생략해도 무방합니다.
docs/
프로젝트의 공식 문서를 보관하는 디렉터리입니다. Sphinx 설정 파일(conf.py)과 진입점 문서(index.rst)를 두어 API 레퍼런스와 사용 가이드를 체계적으로 관리할 수 있습니다.
tests/
모든 테스트 코드가 위치하는 곳입니다. 처음에는 단일 테스트 파일로 시작하지만, 테스트가 늘어나면 모듈 디렉터리 구조와 동일하게 계층화하는 것이 좋습니다.
sample/
실제 모듈 코드가 들어가는 핵심 디렉터리입니다. 모듈이 단일 파일로 충분하다면 저장소 루트에 sample.py 형태로 바로 배치할 수도 있습니다. 다만 라이브러리 코드를 애매한 src나 python 같은 하위 디렉터리에 넣는 것은 피해야 합니다. 모듈을 하나의 패키지로 관리하고 싶다면 이 디렉터리 안에 __init__.py 파일을 포함시키면 됩니다.
마무리
위 구조는 Python 커뮤니티에서 오랫동안 검증된 표준적인 레이아웃입니다. README, LICENSE, setup.py, requirements.txt 같은 기본 파일을 갖추고 코드·문서·테스트를 각각의 디렉터리로 분리하면, 규모가 커져도 일관성 있는 프로젝트 관리가 가능합니다.