초보자를 위한 품질 커맨드 4편: requirements-dev.txt + setup.cfg로 개발용 코드 품질 도구 세트 꾸리기

1. 왜 “개발용 requirements”를 따로 두는 걸까?

지금까지는

  • 2편: quality_check.bat 안에서 무슨 일이 돌아가는지
  • 3편: py_compile_all.py로 Python 구문 체크를 어떻게 하는지

를 살펴봤죠.

이번 4편부터는 “품질 커맨드를 지원해 주는 도구들” 이야기를 합니다.
특히 두 가지 파일에 집중할 거예요.

  • requirements-dev.txt
  • setup.cfg

먼저 이런 고민부터 해볼게요.

“운영 서버에서 꼭 필요한 패키지”랑
“개발할 때만 쓰는 코드 품질 도구들”
같은 파일에 섞어두면 어떨까?

  • 운영 서버에는 black, isort, flake8, mypy가 사실 필요 없을 수 있고
  • bandit, coveragedegree 개발 단계용 도구죠.
  • 그런데 이걸 전부 requirements.txt 하나에 섞어두면,
    • 운영 서버도 쓸데없이 다 설치해야 하고
    • 설치 시간, 이미지 크기(도커), 의존성 충돌 위험도 커집니다.

그래서 보통은 이렇게 정리합니다.

  • requirements.txt → Β 운영에 필요한 최소 패키지
  • requirements-dev.txt → Β 개발 + 품질 도구 전용 패키지

오늘의 포커스는 바로 이 두 번째,
개발용 코드 품질 도구 전용 리스트인 requirements-dev.txt.

2. requirements-dev.txt 안에는 누가 살고 있을까?

requirements-dev tools image

예시로, requirements-dev.txt 안에 들어갈 수 있는 품질 도구들을 정리해 볼게요.

📦 품질 도구 후보들

  • black==23.12.1 → 코드 자동 포매터
  • isort==5.13.2 → import 정렬기
  • flake8==7.0.0 → 코드 스타일 검사기
  • pylint → 좀 더 엄격한 정적 분석기
  • mypy → 타입 힌트 검사기
  • bandit==1.7.6 → 보안 취약점 패턴 검사
  • coverage → 테스트 커버리지 측정
  • pre-commit → git 커밋 전에 자동으로 도구 실행

이 도구들이 하는 일은 각각 조금씩 다르지만,
한 줄로 정리하면 이렇습니다.

“내 코드를 더 안전하게, 읽기 좋게, 유지보수하기 쉽게 만들어주는 도우미들”

이걸 한 파일에 모아서 관리하는 게 requirements-dev.txtAnswer.

3. 초보자 입장에서 보는 사용 흐름

requirements-dev.txt를 만들었을 때,
실제 사용하는 흐름은 보통 이렇게 됩니다.
(깃을 사용한다고 했다는 가정하에 운영과 개발 각각 분리되었다면)

  1. 개발 환경(로컬 PC, 가상환경 등)을 새로 만들었다.
  2. 프로젝트를 git clone 했다.
  3. 다음 두 줄만 실행하면 된다.
pip install -r requirements.txt
pip install -r requirements-dev.txt

그러면

  • 운영에 필요한 기본 패키지 +
  • 개발용 품질 도구 세트까지
    한 번에 준비 완료 🎉

초보자 입장에서는,

“개발 환경 세팅 = requirements 두 개를 순서대로 설치하면 된다”

는 굉장히 단순한 룰이 생깁니다.

4. setup.cfg

requirements-dev image 2

requirements-dev.txtThe
“도구 목록”이라면,

setup.cfgThe
“이 도구들을 어떻게 사용할지에 대한 공통 규칙서”입니다.

여기에는 예를 들어 이런 것들을 적어둘 수 있어요.

4-1. flake8 설정

  • 최대 라인 길이: 120자
  • 일부 규칙은 무시(E203, W503 등)
    • 예: 블랙(black) 포매터와 충돌하는 스타일 규칙들

예시 느낌

[flake8]
max-line-length = 120
extend-ignore = E203, W503
exclude =
    .venv,
    migrations,
    __pycache__

이렇게 해두면

  • 팀원 누구든 flake8을 돌리면
    같은 규칙으로 검사합니다.
  • “내 flake8이랑 네 flake8이랑 결과가 왜 달라?”
    이런 말이 없어져요.

4-2. isort 설정

isort는 import 정렬 도구인데,
Django 프로젝트에서 많이 쓰는 패턴을 이렇게 맞출 수 있어요.

[isort]
profile = django
line_length = 120
skip = migrations

이렇게 설정해두면

  • isort를 어떤 사람이 돌리든
    • import 줄 길이,
    • Django 관련 그룹 순서,
    • 마이그레이션 폴더 제외 등
      동일한 스타일로 정렬됩니다.

4-3. coverage 설정

테스트 커버리지를 볼 때도,
마이그레이션이나 테스트 파일 자체는
커버리지 계산에서 제외하는 경우가 많아요.

[coverage:run]
omit =
    */migrations/*
    */tests/*
    */__init__.py

This will make the

  • 실제 비즈니스 로직이 담긴 코드들만
    커버리지 통계에 집중할 수 있습니다.

5. requirements-dev.txt + setup.cfg + 품질 커맨드의 관계

이제까지 들은 내용을 하나의 그림으로 한번 묶어볼게요.

  1. requirements-dev.txt
    • 품질 도구가 뭉쳐 있는 “개발용 장비 창고”
    • pip install -r requirements-dev.txt 한 번이면
      black, isort, flake8, mypy, bandit, coverage, pre-commit 등
      한꺼번에 설치 완료
  2. setup.cfg
    • black은 “이런 스타일로”
    • isort는 “이렇게 정렬하고”
    • flake8은 “라인 길이 120자에, E203/W503은 무시하고”
    • coverage는 “마이그레이션/테스트는 빼고 커버리지 계산”
      → 이런 공통 규칙을 적어두는 “룰북”
  3. 품질 커맨드 (quality_check.bat / pre-commit 등)
    • 위의 도구들을 실제로 순서대로 실행해 주는 스크립트들
    • 초보자는 도구 이름이나 옵션을 몰라도,
      품질 커맨드만 실행하면 전부 돌게 설계

한 줄로 정리하면

requirements-dev.txt + setup.cfg + 품질 커맨드
→ “우리 팀 개발환경과 코드 품질 기준을
파일로 표준화한 것”

이라고 볼 수 있습니다.

6. 초보자에게 추천하는 실전 사용 루틴

앞으로 새 개발자가 프로젝트에 합류했다고 가정하고,
이렇게 안내할 수 있어요.

  1. 레포지토리 클론 git clone [프로젝트 주소] cd [프로젝트 폴더]
  2. Virtual Environments 만들고 활성화python -m venv .venv .venv\Scripts\activate (Windows 기준)
  3. 운영용 + 개발용 requirements 설치 pip install -r requirements.txt, pip install -r requirements-dev.txt
  4. 처음 품질 커맨드 실행quality_check.bat orpre-commit install
  5. 이후부터는
    • 코드를 수정하고
    • 품질 커맨드를 돌려보고
    • 깔끔하게 통과하면 커밋/푸시

이렇게만 적어줘도,
초보자도 “어디서부터 손대야 하는지” 방향을 잡기 쉬워집니다.

7. 용어 정리

  • requirements-dev.txt
    개발 단계에서만 필요한 도구들(포매터, 린터, 타입체커, 보안 스캐너, pre-commit 등)을
    모아 둔 개발용 패키지 목록 파일.
  • requirements.txt
    주로 운영/실행에 필요한 패키지를 적어두는 기본 의존성 목록.
  • setup.cfg
    여러 Python 도구(예: flake8, isort, coverage 등)의 공통 설정을 모아 두는 파일.
    ini 형식으로 섹션을 나누어 옵션을 적습니다.
  • 린터(linter)
    코드 스타일/잠재적 오류를 분석해 주는 도구의 총칭.
    예: flake8, pylint.
  • 포매터(formatter)
    코드 스타일을 자동으로 맞춰주는 도구.
    예: black.
  • 테스트 커버리지(coverage)
    테스트를 실행했을 때, 전체 코드 중 어느 부분까지 실행됐는지 비율로 보여주는 지표.

Similar Posts