flake8 - PEP(Python Enhancement Proposal) 검증 패키지 사용법

Python

Flake8은 Python 코드를 실행하지 않고 스타일 문제와 사용하지 않는 import 같은 오류 후보를 찾는 정적 검사 도구입니다. 프로젝트 환경에 설치한 뒤 python -m flake8 파일명.py로 검사하고, 출력된 위치와 오류 코드를 기준으로 수정합니다. 모든 PEP를 검증하거나 코드를 자동으로 고쳐 주는 도구는 아닙니다.

PEP와 PEP 8, Flake8의 관계

PEP는 Python Enhancement Proposal의 약자로, Python의 기능·절차·설계 등을 제안하고 설명하는 문서입니다. PEP 1의 문서 체계 가운데 PEP 8은 Python 코드의 스타일 지침입니다. 따라서 제목의 PEP 검증은 모든 제안 문서의 준수 검사라는 의미로 이해하면 안 됩니다.

Flake8은 pycodestyle의 스타일 검사, Pyflakes의 정적 분석, mccabe의 복잡도 검사를 통합합니다. 복잡도 검사는 --max-complexity 같은 기준을 설정해야 사용합니다. E·W 계열은 주로 스타일, F 계열은 Pyflakes 진단이며, 플러그인을 설치하면 검사 범위와 코드가 더해질 수 있습니다. 타입 검사기나 테스트 실행기를 대신하지 않습니다.

프로젝트 환경에 설치하기

아래는 Windows PowerShell에서 새 연습 폴더를 연 뒤 실행하는 명령입니다. Python과 Windows Python 실행기 py가 준비되어 있어야 합니다. 기존 프로젝트에 같은 이름의 가상환경이 있으면 새로 만들지 말고 그 환경의 실행기를 선택합니다. 가상환경을 활성화하지 않고 전체 경로를 사용하므로 활성화 스크립트의 실행 정책을 바꿀 필요가 없습니다.

py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install "flake8==7.4.1"
.\.venv\Scripts\python.exe -m flake8 --version

Flake8 7.4.1은 Python 3.10 이상을 요구합니다. 이 글의 명령과 진단은 Windows의 Python 3.12.14·Flake8 7.4.1에서 확인했습니다. 버전을 고정한 이유는 같은 검사 결과를 재현하기 위해서이며, 다른 버전을 쓰면 요구 Python과 진단 변화도 확인합니다. 마지막 명령은 Flake8과 구성 도구의 버전을 출력합니다.

macOS·Linux에서는 준비된 Python 3으로 가상환경을 만들고 그 안의 .venv/bin/python으로 pip와 Flake8 모듈을 실행합니다. 아래 Windows 실행기 경로를 그대로 사용하지 않습니다. 모듈 실행 방식은 설치한 Python과 검사하는 Python이 달라지는 문제를 줄입니다.

검사 결과의 위치와 오류 코드 읽기

프로젝트 폴더에 bad.py를 만들고 다음 전체 코드를 저장합니다. 마지막 줄 끝에도 줄바꿈을 넣습니다. 해당 환경의 Python으로 실행하면 결과는 1입니다.

import os
value=1
print(value)

실행에 성공한 파일도 스타일이나 불필요한 코드 문제를 포함할 수 있습니다. 같은 폴더에서 검사합니다.

.\.venv\Scripts\python.exe -m flake8 bad.py

bad.py:1:1: F401 'os' imported but unused
bad.py:2:6: E225 missing whitespace around operator

출력은 파일:행:열: 코드 설명 형식입니다. 첫 줄의 F401은 1행에서 불러온 os를 사용하지 않았다는 뜻입니다. 둘째 줄의 E225는 2행 6열의 대입 연산자 주변에 공백이 빠졌다는 뜻입니다. 이 검사 명령의 종료 코드는 1이며 문제가 발견되었음을 나타냅니다. Flake8 오류 코드 안내와 해당 검사 도구의 설명으로 원인을 확인합니다.

코드를 수정하고 다시 확인하기

사용하지 않는 import를 지우고 대입 기호 양쪽에 공백을 넣습니다. 별도 파일을 추가하는 대신 기존 bad.py 전체를 아래 코드로 바꿉니다. 저장 후 실행 결과는 여전히 1입니다.

value = 1
print(value)

같은 파일을 다시 검사합니다. --count는 마지막에 발견 건수를 출력하므로 통과 여부를 확인하기 쉽습니다.

.\.venv\Scripts\python.exe -m flake8 --count bad.py

이 예제는 진단 0건, 종료 코드 0으로 통과합니다. --count 없이 실행하면 문제가 없을 때 일반적으로 진단 출력이 없습니다. Flake8 자체는 위 코드를 자동 수정하지 않으므로 편집기에서 수정·저장한 뒤 재검사해야 합니다. 검사 통과와 실행 결과를 각각 확인합니다.

.flake8에 프로젝트 규칙 저장하기

프로젝트 루트에 .flake8 파일을 만들면 팀에서 같은 규칙을 사용할 수 있습니다. 아래는 INI 형식이며 Python 코드가 아닙니다. 줄 길이 88은 프로젝트가 선택한 예시 기준입니다. Flake8의 기본 최대 줄 길이는 79이며, 88이 PEP 8의 새 기본값이라는 뜻은 아닙니다.

[flake8]
max-line-length = 88
extend-exclude = .venv,build,dist

extend-exclude는 기본 제외 항목을 유지하면서 가상환경·빌드 결과 폴더를 추가합니다. 점검할 소스 파일을 무심코 제외하지 않도록 범위를 확인합니다. 설정 파일을 명시하여 앞에서 수정한 파일을 검사합니다.

.\.venv\Scripts\python.exe -m flake8 --config .flake8 --count bad.py

이 명령도 0건으로 통과합니다. 프로젝트 전체를 검사하려면 마지막 bad.py를 .으로 바꿉니다. 다른 파일이 있으면 그 파일의 진단도 나올 수 있습니다. 설정 문서는 .flake8, setup.cfg, tox.ini의 [flake8] 구역을 설명합니다. 명령줄 옵션은 설정 파일보다 우선하므로 편집기나 CI의 옵션도 확인합니다.

검사에서 제외하기 전에 확인할 점

오류를 숨기기 위해 전체 검사를 끄기보다 필요 없는 코드인지, 프로젝트 규칙과 충돌하는지 먼저 판단합니다. 불가피한 한 줄의 예외는 사유를 남기고 해당 진단 코드만 지정한 # noqa: F401처럼 범위를 좁힐 수 있습니다. ignore는 기본 무시 목록을 대체하고 extend-ignore는 추가하므로 옵션의 적용 범위를 확인한 뒤 선택합니다.

자동 검사인 지속적 통합(CI)에서는 검사 실패의 종료 코드를 그대로 사용해야 합니다. --exit-zero를 지정하면 진단이 있어도 성공으로 처리하므로 품질 통과 조건에는 맞지 않습니다. Flake8 버전과 필요한 플러그인은 프로젝트 의존성에 기록하고, 새 버전 적용 시 규칙 변화도 검토합니다. 정적 검사가 통과해도 입력·업무 로직·실행 환경의 오류는 남을 수 있으므로 프로그램 실행과 필요한 테스트를 함께 수행합니다.

Python