Ruff 설정 관리

Ruff 린터/포맷터 환경을 구성하고 관리한다.

목적

• Ruff 린터/포맷터 설정
• 프로젝트별 규칙 세트 최적화
• pyproject.toml 설정 관리
• 기존 도구(Flake8, isort, Black) 마이그레이션

사용법

/quality-ruff init      # 초기 설정
/quality-ruff check     # 린트 검사
/quality-ruff fix       # 자동 수정
/quality-ruff format    # 코드 포맷팅

표준 설정

pyproject.toml

# =============================================================================
# Ruff Configuration
# Documentation: https://docs.astral.sh/ruff/configuration/
# =============================================================================

[tool.ruff]
# 기본 설정
target-version = "py311"
line-length = 100
indent-width = 4

# 검사 대상
src = ["src", "tests"]
include = ["*.py", "*.pyi"]
exclude = [
    ".git",
    ".ruff_cache",
    ".venv",
    "__pycache__",
    "build",
    "dist",
    "*.egg-info",
]

# 캐시 설정
cache-dir = ".ruff_cache"

# 출력 형식
output-format = "concise"

# =============================================================================
# Lint 설정
# =============================================================================
[tool.ruff.lint]
# 규칙 세트
select = [
    "E",      # pycodestyle errors
    "W",      # pycodestyle warnings
    "F",      # Pyflakes
    "I",      # isort
    "B",      # flake8-bugbear
    "C4",     # flake8-comprehensions
    "UP",     # pyupgrade
    "ARG",    # flake8-unused-arguments
    "SIM",    # flake8-simplify
    "TCH",    # flake8-type-checking
    "PTH",    # flake8-use-pathlib
    "RUF",    # Ruff-specific rules
]

# 무시 규칙
ignore = [
    "E501",   # line too long (포맷터가 처리)
    "B008",   # function call in default argument (FastAPI Depends)
    "B904",   # raise without from (불필요한 경우 많음)
]

# 자동 수정 가능 규칙
fixable = ["ALL"]
unfixable = []

# 더미 변수 패턴
dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"

# =============================================================================
# isort 설정 (I 규칙)
# =============================================================================
[tool.ruff.lint.isort]
known-first-party = ["src"]
force-single-line = false
lines-after-imports = 2
section-order = [
    "future",
    "standard-library",
    "third-party",
    "first-party",
    "local-folder",
]

# =============================================================================
# flake8-bugbear 설정 (B 규칙)
# =============================================================================
[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = [
    "fastapi.Depends",
    "fastapi.Query",
    "fastapi.Path",
    "fastapi.Body",
]

# =============================================================================
# 파일별 규칙 오버라이드
# =============================================================================
[tool.ruff.lint.per-file-ignores]
"tests/**/*.py" = [
    "S101",   # assert 허용
    "ARG001", # 미사용 인자 허용 (fixtures)
    "ARG002", # 미사용 인자 허용
]
"__init__.py" = ["F401"]  # 미사용 import 허용
"conftest.py" = ["ARG001"]

# =============================================================================
# Format 설정
# =============================================================================
[tool.ruff.format]
quote-style = "double"
indent-style = "space"
skip-magic-trailing-comma = false
line-ending = "auto"
docstring-code-format = true
docstring-code-line-length = 80

규칙 세트 가이드

핵심 규칙

E

W

F

I

B

C4

UP

추가 권장 규칙

SIM

TCH

PTH

RUF

ARG

Data Science 추가 규칙

NPY

PD

프로젝트 유형별 설정

1. 일반 Python

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM", "RUF"]

2. Data Science

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "NPY", "PD", "RUF"]
ignore = ["E501", "PD901"]  # df 변수명 허용

3. FastAPI/API 서버

[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "ARG", "SIM", "TCH", "RUF"]
ignore = ["B008"]  # Depends 허용

[tool.ruff.lint.flake8-bugbear]
extend-immutable-calls = ["fastapi.Depends", "fastapi.Query"]

실행 명령

린트 검사

# 기본 검사
uv run ruff check .

# 상세 출력
uv run ruff check . --verbose

# 자동 수정
uv run ruff check . --fix

# 안전하지 않은 수정 포함
uv run ruff check . --fix --unsafe-fixes

# 특정 규칙만 검사
uv run ruff check . --select E,W,F

포맷팅

# 포맷 검사 (변경 없이)
uv run ruff format --check .

# 포맷 적용
uv run ruff format .

# diff 출력
uv run ruff format --diff .

VS Code 통합

settings.json

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true,
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit",
            "source.organizeImports.ruff": "explicit"
        }
    },
    "ruff.lint.args": ["--config=pyproject.toml"],
    "ruff.format.args": ["--config=pyproject.toml"]
}

마이그레이션

Flake8 → Ruff

# Flake8 규칙을 Ruff로 변환
ruff rule --all | grep "Flake8"

isort → Ruff

# 기존 isort 설정
[tool.isort]
profile = "black"

# Ruff isort 설정으로 변환
[tool.ruff.lint.isort]
known-first-party = ["src"]

Black → Ruff

# Ruff 포맷터는 Black과 99% 호환
uv run ruff format .

규칙 무시

파일 수준

# ruff: noqa: E501

라인 수준

x = "long line"  # noqa: E501

특정 규칙만 무시

# noqa: E501, F401

트러블슈팅

캐시 초기화

rm -rf .ruff_cache

규칙 설명 확인

ruff rule E501

설정 검증

ruff check --show-settings

관련 스킬

Changelog

Gotchas (실패 포인트)

• ruff format

  (포맷)과

  ruff check

  (린트)는 별개 명령 — 둘 다 실행 필요
• Black과 충돌: ruff format은 Black 호환이나 rule 일부 충돌 가능

• # noqa

  주석 남용 금지 — 근본 원인 수정 후 제거

• E501

  비활성화 후 line-length 설정 누락 시 모순