Black·Ruff — 자동 포맷과 정적 분석

혼자 짠 코드도 한 달 뒤 보면 띄어쓰기·줄바꿈·import 순서가 제각각입니다. 동료 코드와 섞이면 더 심해요 — "여기는 4칸인데 저기는 2칸", "이 import 는 왜 본문 중간에". 이걸 일일이 손으로 맞추는 시대는 끝났습니다. 명령 하나로 코드 스타일이 통일되는 Black(자동 포맷)과 Ruff(린트 + 포맷, 2024년 이후 표준)가 답.

26편을 마치면 ① Black·Ruff 설치와 실행 ② pyproject.toml 설정 ③ VS Code 저장 시 자동 적용 ④ pre-commit 으로 커밋 차단 ⑤ CI 통합 — 5가지를 손에 익힙니다.

Ruff — 한 도구가 다 한다

2022년 등장한 Ruff(Rust 로 작성) 가 Black + isort + flake8 셋의 일을 한 번에, 10-100배 빠르게 합니다. 2026년 기준 새 프로젝트는 거의 다 Ruff.

(.venv) $ pip install ruff

# 1) 포맷팅 — Black 호환
$ ruff format .
5 files reformatted, 12 files unchanged

# 2) 린트 — 정적 분석
$ ruff check .
src/app.py:42:5: F841 Local variable 'x' is assigned but never used
src/api.py:7:1:  I001 Import block is un-sorted

# 3) 자동 수정 가능한 것은 fix
$ ruff check --fix .
Fixed 2 errors.

한 줄에 일어나는 일.

• ruff format — 들여쓰기·줄바꿈·따옴표·라인 길이를 Black 규칙으로 통일
• ruff check — 사용 안 한 변수·잘못된 import·중복 코드·미세 버그 찾기
• --fix — 자동 수정 가능한 건 그 자리에서 고침

pyproject.toml — 프로젝트 설정의 표준

# pyproject.toml — 프로젝트 루트에 한 파일
[tool.ruff]
line-length = 100               # 기본 88, 한국어 코드는 100 권장
target-version = "py312"

[tool.ruff.lint]
select = [
    "E", "F",      # 기본 오류 (pyflakes/pycodestyle)
    "I",           # isort — import 정렬
    "UP",          # 파이썬 신문법 권장
    "B",           # bugbear — 흔한 버그 패턴
    "SIM",         # simplify — 단순화 제안
]
ignore = ["E501"]                # 줄 길이는 format 이 처리

[tool.ruff.format]
quote-style = "double"           # 큰따옴표 통일
indent-style = "space"           # 스페이스 4칸 (PEP 8)

이 한 파일이 팀 전체의 스타일 단일 진실원. 깃에 커밋하면 모두가 같은 룰을 따릅니다.

Black 만 쓰고 싶다면

(.venv) $ pip install black
$ black .

# 같은 일을 한다 — 다만 린트는 별도 도구(flake8) 필요
[tool.black]
line-length = 100
target-version = ["py312"]

Black 은 더 오래된 표준, Ruff 는 새 표준. 기존 팀이 Black 을 쓰고 있으면 그대로, 신규 프로젝트는 Ruff 가 무난.

VS Code 저장 시 자동 적용

# .vscode/settings.json
{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll": "explicit",
      "source.organizeImports": "explicit"
    }
  }
}

이 두 줄로 파일을 저장하는 순간 자동 포맷팅 + import 정렬 + 자동 수정. 동료가 다른 스타일로 보내도 본인이 저장만 하면 정리됩니다.

pre-commit + CI 통합

pre-commit — 커밋 직전 자동 검증

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

# 설치
(.venv) $ pip install pre-commit
(.venv) $ pre-commit install

# 이제 git commit 할 때마다 자동 실행
$ git commit -m "feat: add user model"
ruff.................Passed
ruff-format..........Passed
[main 1a2b3c4] feat: add user model

실패하면 커밋이 차단됩니다. "이상한 코드가 깃에 들어가는 사고" 가 사라져요.

GitHub Actions CI

# .github/workflows/lint.yml
name: Lint
on: [push, pull_request]
jobs:
  ruff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/ruff-action@v1

PR 마다 자동 실행. 빨간 X 가 뜨면 머지 못 함. 코드 품질의 최소 안전망.

다음 미션: ① 본인 코드에 ruff format . + ruff check --fix . 돌려보기 ② pyproject.toml 작성 ③ VS Code 저장 시 자동 적용 설정.