Python 프로젝트를 체계적으로! 디렉터리 구조와 모듈 관리 방법

 

 

Python 프로젝트를 효율적으로 관리하려면 체계적인 디렉터리 구조와 모듈 관리를 이해하는 것이 중요합니다. 이번 글에서는 디렉터리 구조와 함께, __init__.py 파일의 역할과 최신 Python 버전에서의 변화, 모듈 임포트 방식, 그리고 패키지 배포 방법까지 자세히 알아보겠습니다.

 

---

1. Python 프로젝트 디렉터리 구조 예시

효율적인 Python 프로젝트는 명확하고 직관적인 디렉터리 구조를 갖추는 것이 핵심입니다. 다음은 일반적인 Python 프로젝트 디렉터리 구조의 예입니다:

 

my_project/
│
├── src/                # 메인 코드 디렉터리
│   ├── __init__.py     # 패키지 초기화 파일
│   ├── module1.py      # 첫 번째 모듈
│   └── module2.py      # 두 번째 모듈
│
├── tests/              # 테스트 코드
│   ├── __init__.py
│   └── test_module1.py
│
├── docs/               # 프로젝트 문서
│   └── README.md
│
├── setup.py            # 패키지 배포 설정 파일
├── pyproject.toml      # 빌드 시스템 구성 파일
├── requirements.txt    # 의존성 목록
└── .gitignore          # Git 무시 파일

 

---

2. __init__.py와 모듈의 개념

__init__.py 파일의 역할

__init__.py 파일은 디렉터리를 Python 패키지로 인식하게 하는 역할을 합니다.
Python 3.3 이전 버전에서는 반드시 __init__.py가 있어야 패키지로 간주되었으나, Python 3.3 이후부터는 __init__.py가 없어도 패키지로 인식됩니다.

하지만, 여전히 __init__.py는 다음과 같은 이유로 유용합니다:

 

  1. 패키지 초기화: 모듈 간 공유 변수나 초기 설정을 정의할 수 있습니다.

  2. 모듈 노출 제한: __all__ 리스트를 정의하여 특정 모듈만 노출할 수 있습니다

# src/__init__.py
__all__ = ['module1']

 

  3. 명확한 패키지 구조: 디렉터리가 패키지임을 직관적으로 보여줍니다.

 

---

3. 상대 경로 vs 절대 경로 임포트

1) 절대 경로 임포트

최상위 디렉터리부터 전체 경로를 명시하는 방식으로, 가독성이 높고 충돌 가능성이 낮습니다.

 

# src/module1.py에서 module2 임포트
from src.module2 import some_function

 

2) 상대 경로 임포트

현재 파일 기준으로 경로를 지정하며, 프로젝트 구조가 변경될 경우 관리가 어려울 수 있습니다.

 

# src/module1.py에서 module2 임포트
from .module2 import some_function

 

권장 사항

일반적으로 절대 경로 임포트를 권장합니다. 상대 경로는 모듈 간 참조가 강하게 연결될 때 사용하는 것이 적합합니다.

 

---

4. 패키지 배포 기본 예제

1) setup.py 설정 예시

setup.py는 전통적인 패키지 배포 스크립트입니다.

from setuptools import setup, find_packages

setup(
    name="my_project",
    version="0.1.0",
    packages=find_packages(where="src"),
    package_dir={"": "src"},
    install_requires=[
        "numpy>=1.20.0"
    ],
)

 

2) pyproject.toml 구성 예시

최근에는 pyproject.toml을 사용하는 것이 표준으로 자리 잡았습니다.

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my_project"
version = "0.1.0"
dependencies = ["numpy>=1.20.0"]

 

 

---

마무리

Python 프로젝트를 체계적으로 관리하려면 적절한 디렉터리 구조를 설정하고, __init__.py 파일의 필요 여부를 판단하며, 임포트 방식을 명확히 해야 합니다. 또한, 최신 배포 방식을 익혀 배포 프로세스를 간소화하세요.

이제 여러분의 Python 프로젝트를 더욱 깔끔하고 체계적으로 만들어 보세요! 🚀