[Modern Python Project] 현대적 파이썬 프로젝트 관리, 개발법에 대하여

[Modern Python Project] 현대적 파이썬 프로젝트 관리, 개발법에 대하여

파이썬 프로젝트를 현대적으로 관리하고 개발하는 방법에 대해 이야기해보려 합니다.

 

여러 회사와 프로젝트에서 파이썬을 사용하면서 발견한 몇 가지 성가시고, 유지보수가 어렵고, 구식인 관행들이 있습니다. 이제 이런 낡은 방식은 그만두고, 더 나은 방법을 함께 알아보죠!

---

시작하기 전에

이 글에서 다룰 내용은 다음과 같습니다:

1. requirements.txt 대신 pyproject.toml 사용하기
2. Poetry나 UV 같은 파이썬 버전 및 프로젝트 관리자 활용
3. 타입 힌트(Type Hints) 적용
4. 함수 독스트링에 Raises 섹션 추가
5. Pydantic 모델로 데이터 관리
6. Ruff 같은 린터와 포맷터 도입
7. unittest 대신 Pytest 사용
8. 프로젝트에 몰래 적용해볼 만한 "핫 테이크" 팁

그럼 바로 시작해볼까요?

---

반응형

1. requirements.txt 대신 pyproject.toml을 사용하세요

이제 README.md에 “pip install -r requirements.txt로 종속성을 설치하세요”라고 쓰는 건 그만두세요. requirements.txt는 단순히 관행일 뿐입니다. 대신 pyproject.toml을 사용하세요!

왜 pyproject.toml인가요?

✅ 깔끔하다 – 프로젝트 정보와 종속성을 한 파일에서 관리할 수 있습니다.
✅ 유연하다 – 개발용(dev) 종속성이나 선택적 종속성을 쉽게 추가할 수 있습니다.
✅ 현대적이다 – 최신 파이썬 도구들과 완벽하게 호환됩니다.

사용법 예시

[project]
name = "my_app"
version = "0.1.0"
dependencies = [
    "fastapi>=0.68.0",
    "pandas>=1.3.0",
]

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

이제 pip install . 명령어로 프로젝트와 종속성을 설치할 수 있습니다.

---

2. Poetry나 UV 같은 파이썬 프로젝트 관리자를 사용하세요

venv를 직접 관리하는 대신 Poetry나 UV 같은 도구를 사용하세요. 프로젝트 관리를 훨씬 쉽게 만들어줍니다.

추천 이유

🚀 효율적이다 – 반복 작업을 자동화하여 시간을 절약할 수 있습니다.
🔒 안정적이다 – 전역 종속성 충돌을 방지할 수 있습니다.
⚡ 빠르다 – 특히 UV는 엄청나게 빠릅니다.

---

3. 타입 힌트(Type Hints)를 사용하세요

타입 힌트를 사용하면 코드 가독성이 향상되고, ruff나 mypy 같은 도구가 버그를 미리 잡을 수 있습니다.

예시

❌ 타입 힌트 없는 코드:

def check_scores(scores):
    total = 0
    for score in scores:
        total += score
    return total / len(scores)

✅ 타입 힌트를 추가한 코드:

from typing import List

def check_scores(scores: List[float]) -> float:
    """학생 점수 리스트의 평균을 계산합니다."""
    return sum(scores) / len(scores)

---

4. 함수 독스트링에 Raises 섹션을 추가하세요

예외를 문서화하면 유지보수가 훨씬 쉬워집니다.

예시

import csv
from typing import List

def read_csv_data(file_path: str) -> List[str]:
    """CSV 파일에서 첫 번째 열 데이터를 읽습니다.

    Args:
        file_path (str): CSV 파일 경로

    Raises:
        FileNotFoundError: 파일이 없을 경우
        csv.Error: CSV 형식이 맞지 않을 경우

    Returns:
        List[str]: 첫 번째 열 데이터 리스트
    """
    with open(file_path, 'r') as f:
        reader = csv.reader(f)
        return [row[0] for row in reader]

---

5. Pydantic 모델로 데이터를 전달하세요

딕셔너리 대신 Pydantic 모델을 사용하면 코드가 깔끔해지고 데이터 유효성 검사를 자동으로 수행할 수 있습니다.

예시

from pydantic import BaseModel

class UserSettings(BaseModel):
    username: str
    email: str
    active: bool

def update_user(settings: UserSettings):
    pass  # 사용자 설정 업데이트 로직

---

6. Ruff 같은 린터와 포맷터를 사용하세요

파이썬에서 코드 스타일을 깔끔하게 유지하려면 ruff를 추천합니다. 속도가 빠르고, Black 스타일을 따르며, 사소한 실수도 잘 잡아줍니다.

설정 예시

pyproject.toml에 이렇게 추가하세요:

[tool.ruff]
line-length = 88
select = ["E", "F", "W"]

---

7. unittest 대신 Pytest를 사용하세요

unittest도 나쁘지 않지만, pytest는 더 간결하고 강력합니다.

예시

def multiply(a, b):
    return a * b

def test_multiply():
    assert multiply(2, 3) == 6
    assert multiply(0, 5) == 0

터미널에서 pytest test_file.py를 실행하면 테스트가 시작됩니다.

---

8. 프로젝트에 몰래 넣을 수 있는 "핫 테이크"

🔥 orjson – 기본 json보다 훨씬 빠릅니다.
✨ f-strings – f"안녕 {name}"처럼 간결하게 작성하세요.
📂 pathlib – os.path 대신 사용하세요.
🖱 click – CLI 프로그램을 쉽게 만들 수 있습니다.
🚀 파이썬 3.8+ – 최신 버전으로 업그레이드하세요!

 

 

 

함께보면 좋은글

 

Python 성능 향상: 3배 더 빠른 스크립트로 바꾸는 방법

Python 성능 향상: 3배 더 빠른 스크립트로 바꾸는 방법

[Python 3.13] AI와 ML 혁신을 위한 새로운 기능들

[Python 3.13] AI와 ML 혁신을 위한 새로운 기능들

[Python]에서 MongoDB 집계 파이프 사용법 정리(MongoDB aggregation)

[Python]에서 MongoDB 집계 파이프 사용법 정리(MongoDB aggregation)