Python 프로젝트 구조화의 표준
Python 모듈을 체계적으로 구성하면 유지보수성과 협업 효율이 크게 향상됩니다. Kenneth Reitz가 공개한 samplemod 샘플 프로젝트는 Python 프로젝트를 구조화하는 매우 훌륭한 예시로 널리 알려져 있습니다. 이 프로젝트는 '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 requirements 파일에는 프로젝트에 기여하는 데 필요한 의존성, 즉 테스트, 빌드, 문서 생성에 필요한 패키지들을 지정해야 합니다. 개발 의존성이 없거나 setup.py를 통해 개발 환경을 구성하는 것을 선호한다면 이 파일은 생략해도 무방합니다.
docs/: 프로젝트 문서를 보관하는 디렉터리입니다. Sphinx와 같은 문서화 도구와 함께 사용하면 API 레퍼런스와 가이드를 체계적으로 관리할 수 있습니다.
tests/: 모든 테스트 코드가 위치하는 곳입니다. 처음에는 단일 테스트 파일로 시작하겠지만, 테스트가 늘어나면 모듈 디렉터리 구조와 유사하게 테스트를 계층화하는 것이 좋습니다.
sample/: 실제 모듈 코드가 들어 있는 핵심 디렉터리입니다. 모듈이 단일 파일로 구성된다면 저장소 루트에 sample.py 형태로 바로 배치할 수 있습니다. 라이브러리 코드를 모호한 src나 python 같은 하위 디렉터리에 넣지 않는 것이 원칙입니다. 또한 모듈을 하나의 패키지로 취급하고 싶다면 이 디렉터리 안에 __init__.py 파일을 포함시켜야 합니다.
정리
이 구조는 문서, 테스트, 배포 설정, 실제 코드를 명확히 분리함으로써 프로젝트의 확장성과 가독성을 동시에 확보합니다. 새로운 Python 프로젝트를 시작할 때 이 표준 구조를 따르면 다른 개발자들도 코드베이스를 쉽게 파악할 수 있습니다.