ProgrammingLanguagePython

Python 프로젝트 구조화 방법

, , , ,

잘 구성된 Python 프로젝트 구조는 코드베이스를 관리하기 쉽게 만들고 확장성과 이해도를 높여줍니다. 이는 개인 개발자는 물론, 팀으로 협업할 때도 필수적인 요소입니다. 이 글에서는 Python 프로젝트를 효과적으로 구성하는 방법에 대해 단계별로 설명하고, 각 단계에서 모범 사례와 예시를 함께 다룹니다.

1단계: 프로젝트 설정 🌳 루트 디렉터리

가장 먼저 프로젝트와 관련된 모든 파일을 포함할 루트(Root) 디렉터리를 생성합니다. 디렉터리 이름은 프로젝트의 목적이나 내용을 명확하게 나타내도록 설명적이고 의미 있는 이름으로 지정하는 것이 좋습니다. 일반적으로 프로젝트 이름을 디렉터리 이름으로 사용하는 것이 권장됩니다.

예시:

1
my_project/

이 디렉터리 안에 소스 코드, 문서, 설정 파일 등을 추가하며 프로젝트를 구성해 나가게 됩니다.

2단계: 가상 환경 생성 🌄

가상 환경은 프로젝트 간 종속성 충돌을 방지하고, 종속성을 격리하여 관리할 수 있도록 해줍니다. 이를 통해 프로젝트마다 필요한 패키지 버전을 다르게 설정할 수 있으며, 안정적인 개발 환경을 유지할 수 있습니다.

가상 환경 생성 방법

Linux/macOS 사용자:

1
2
cd my_project
python3 -m venv venv

Windows 사용자:

1
python -m venv venv

가상 환경 생성 후, 아래 명령어로 활성화할 수 있습니다.

Linux/macOS에서 활성화:

1
source venv/bin/activate

Windows에서 활성화:

1
venv\Scripts\activate

이제 가상 환경이 활성화되었으며, 모든 종속성(라이브러리 및 패키지)은 이 환경에 설치됩니다. 이렇게 하면 프로젝트가 특정 버전의 라이브러리에 종속되어도 다른 프로젝트에 영향을 주지 않게 됩니다.

3단계: 핵심 디렉터리 구조 정의 📗

Python 프로젝트의 핵심 프로젝트 구조는 패키지/모듈 디렉터리, 테스트 디렉터리, 그리고 루트 수준에 위치한 설정 및 구성 파일로 구성되어야 합니다. 이러한 구조는 프로젝트의 코드 관리와 확장을 용이하게 해줍니다.

예시 디렉터리 구조

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
my_project/
│
├── my_package/           # 메인 패키지 디렉터리
│   ├── __init__.py       # 디렉터리를 패키지로 인식시키는 파일
│   ├── module1.py
│   ├── module2.py
│   └── utils.py
│
├── tests/                # 각 모듈이나 기능에 대한 테스트 디렉터리
│   ├── __init__.py
│   ├── test_module1.py
│   ├── test_module2.py
│   └── test_utils.py
│
├── venv/                 # 가상 환경 디렉터리 (.gitignore에 추가하여 무시)
│
├── requirements.txt      # 프로젝트 종속성 목록
│
└── README.md             # 프로젝트 설명 및 사용법

구성 요소 설명

  • my_package/: 프로젝트의 핵심 코드를 포함하는 디렉터리입니다.
  • tests/: 각 모듈에 대한 단위 테스트가 포함된 디렉터리로, 테스트를 통해 코드의 안정성을 검증할 수 있습니다.
  • requirements.txt: 프로젝트에 필요한 라이브러리와 종속성 목록을 관리하는 파일입니다. pip freeze > requirements.txt 명령어로 자동 생성할 수 있습니다.
  • README.md: 프로젝트에 대한 설명과 사용법을 제공하는 문서로, 다른 사용자들이 프로젝트를 쉽게 이해하고 사용할 수 있도록 도와줍니다.

4단계: __init__.py 파일 작성 📝

__init__.py 파일은 디렉터리를 Python 패키지로 인식하게 만듭니다. 또한, 이 파일을 통해 특정 모듈이나 함수에 대한 임포트를 간소화할 수 있습니다.

예시 __init__.py 파일 (my_package/ 디렉터리):

1
2
3
# my_package/__init__.py
from .module1 import function1
from .module2 import function2

이렇게 하면 다음과 같이 간단하게 임포트할 수 있습니다.

1
from my_package import function1

5단계: 설정 파일 추가 ⚙️

테스트, 코드 스타일 검사, 배포 등을 자동화하려면 설정 파일을 추가하는 것이 좋습니다.

1. .gitignore

.gitignore 파일을 통해 Git에서 관리하지 않을 파일과 디렉터리를 지정할 수 있습니다.

1
2
3
venv/
__pycache__/
*.pyc

2. requirements.txt

requirements.txt 파일은 프로젝트 종속성을 관리하며, 동일한 개발 환경을 쉽게 재현할 수 있도록 도와줍니다.

1
2
# 생성 방법
pip freeze > requirements.txt

6단계: 테스트 설정 ⚓️

테스트는 프로젝트의 품질을 보장하는 중요한 요소입니다. Python에서는 pytest 또는 unittest를 사용하여 테스트를 작성할 수 있습니다.

테스트 파일은 일반적으로 tests/ 디렉터리에 배치하며, 파일 이름은 test_로 시작하는 것이 관례입니다.

1
2
3
4
5
6
7
# 예시 테스트 파일: tests/test_module1.py
import pytest
from my_package.module1 import function1

def test_function1():
    result = function1()
    assert result == expected_output  # 실제 예상 결과로 교체

명령어로 테스트 실행

1
pytest tests/

7단계: 패키징을 위한 setup.py 작성 📦 (선택 사항)

배포 가능한 Python 패키지를 만들려면 setup.py 파일을 추가해야 합니다.
이 파일은 Python이 패키지를 빌드하고 설치하는 방법을 정의합니다.

1
2
3
4
5
6
7
8
9
10
11
# 예시
from setuptools import setup, find_packages

setup(
    name="my_project",
    version="0.1",
    packages=find_packages(),
    install_requires=[
        "some_package>=1.0.0",
    ],
)

로컬에서 패키지 설치 방법

1
pip install -e .

이제 프로젝트를 다른 Python 환경에서도 쉽게 설치하고 사용할 수 있습니다.

8단계: 프로젝트 문서화 📜

문서화는 프로젝트를 더 이해하기 쉽게 만들어 줍니다.
README.md 파일을 업데이트하여 프로젝트 개요, 설치 방법, 사용 예시 등을 포함하세요.

1
2
3
4
5
6
7
8
9
10
11
12
13
# My Project

## Overview

This project does XYZ.

## Installation

1. Clone the repository.
2. Install dependencies:
   ```bash
      pip install -r requirements.txt
   ```

최종

최종 프로젝트 구조 예시입니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
my_project/
│
├── my_package/           # 메인 패키지 디렉터리
│   ├── __init__.py
│   ├── module1.py
│   ├── module2.py
│   └── utils.py
│
├── tests/                # 테스트 디렉터리
│   ├── __init__.py
│   ├── test_module1.py
│   ├── test_module2.py
│   └── test_utils.py
│
├── venv/                 # 가상 환경 디렉터리
│
├── requirements.txt      # 종속성 목록
│
├── README.md             # 프로젝트 설명 및 사용법
│
└── setup.py              # 선택 사항: 패키징 설정 파일

이러한 구조는 프로젝트를 체계적으로 관리할 수 있도록 도와주며, 개발, 테스트, 유지보수를 더 효율적으로 할 수 있게 만듭니다.

Share