초보자를 위한 품질 커맨드 3편: py_compile_all.py로 python syntax check 검사하기

python syntax check image

1. 왜 Python syntax check부터 해야 할까?

1편和 2편에서 우리는 quality_check.bat 안에서
여러 가지 검사를 한 번에 돌리는 큰 그림을 봤죠.

그 중 제일 앞에 오는 게 바로 “Python 구문 체크”입니다.
이게 뭘 의미하냐면, 한마디로

“프로젝트 안에 있는 모든 .py 파일이
최소한 문법 에러 없이 읽히기라도 하는지 먼저 확인해 보자”

라는 뜻이에요.

테스트를 돌리기 전에,
Django 서버를 띄워 보기 전에,

  • 괄호가 빠졌는지
  • 콜론이 빠졌는지
  • 인덴트(들여쓰기)가 엉망인 곳이 있는지

를 먼저 잡을 수 있다면,
“당연히 그게 더 낫지 않냐?” 하는 접근입니다.

그래서 품질 커맨드 시퀀스에서
가장 초반에 py_compile_all.py 같은 구문(syntax) 검사 스크립트가 배치되는 거예요.

2. py_compile_all.py가 하는 일 한 줄 요약

이 스크립트를 아주 짧게 정의하면 이렇게 말할 수 있습니다.

프로젝트 전체를 돌아다니면서 모든 .py 파일을 컴파일해보고,
문법 에러가 나는 파일을 찾아서 알려주는 “구문 검진기”

python syntax check image2

여기서 “컴파일”은
바이트코드로 변환해서 실행 가능한지 확인하는 수준으로 이해하시면 됩니다.

실행 흐름은 대략 이렇게 생각하시면 돼요.

  1. 프로젝트 폴더 전체를 스캔한다.
  2. 무시해야 할 폴더/파일은 건너뛴다.
  3. 남은 .py 파일들을 하나씩 py_compile로 컴파일 시도한다.
  4. 에러가 나면 어느 파일에서, 어떤 문법 에러인지 모아서 보여준다.
  5. 에러가 하나라도 있으면 품질 커맨드에서 실패로 처리한다.

3. 어떤 파일은 “검사에서 제외”할까

실제 프로젝트에는
검사해 봐야 의미 없는 파일들이 꽤 많습니다.

그래서 py_compile_all.py 안에는 보통 이런 제외 규칙(무시 목록)이 들어가요.

  • venv / .venv 같은 가상환경 폴더
  • __pycache__
  • 마이그레이션 자동 생성 폴더 (필요에 따라)
  • 도구용 스크립트나 예제 폴더 중, 일부러 제외하고 싶은 것들

이유는 간단합니다.

  1. 虚拟环境은 프로젝트 코드가 아니라, 설치된 라이브러리들이라
    구문 에러를 우리가 책임질 이유가 없고,
  2. 캐시 폴더는 자동 생성 파일이라 굳이 검사할 필요가 없고,
  3. 마이그레이션 같은 경우는 자동 생성 코드라
    본 코드보다 우선순위가 낮을 수 있기 때문이에요.

초보자 입장에서는 이렇게 기억해두면 편합니다.

“내가 직접 관리하는 코드들만 검사하고,
나머지는 최대한 제외한다.”

4. py_compile_all.py 내부 동작 흐름

python syntax check image4

이제 내부에서 어떤 순서로 돌아가는지
코드 없이 개념으로 정리해볼게요.

4-1. 폴더 전체 순회

  1. 기준이 되는 프로젝트 루트 경로를 하나 정합니다.
  2. os.walk 같은 걸 써서
    • 루트 폴더
    • 그 하위의 모든 폴더들
    • 그리고 거기에 속한 파일들
      至 하나씩 전부 순회用于以下方面

여기까지는 그냥 “전체 검사 대상 수집” 단계라고 보면 돼요.

4-2. 무시 대상 필터링

폴더를 하나씩 볼 때마다

  • 폴더 이름이 venv, .venv, __pycache__ 等等
    무시 목록에 들어 있으면 그 아래는 아예 들어가지 않습니다.
  • 파일을 볼 때도
    • .py 확장자가 아닌 파일은 바로 패스.

이렇게 걸러내고 나면,
결국 “검사해야 할 .py 파일 리스트”만 남게 되죠.

4-3. 실제 컴파일 시도

이제 각 .py 파일마다

  1. py_compile.compile("파일경로", doraise=True) 같은 식으로
    컴파일을 실제로 시도합니다.
  2. 문법이 올바르면 → 조용히 통과
  3. 문법 오류가 있다면 →
    예외(Exception)가 발생하고,
    이 파일 경로와 에러 메시지를 리스트에 쌓아둡니다.

이 과정이 끝나면

  • 전체 .py 파일 수
  • 그 중 문법 에러가 난 파일 목록

을 한 번에 정리해서 보여줄 수 있어요.

python syntax check image3

4-4. 결과 출력 & 종료 코드

그리고 마지막에

  • 에러가 하나도 없으면 →
    “모든 Python 파일이 구문 체크를 통과했습니다” 같은 메시지를 표시하고
    종료 코드(Exit code)를 0으로 반환합니다.
  • 에러가 하나라도 있으면 →
    에러 난 파일 목록 + 에러 내용들을 출력하고
    종료 코드(Exit code)를 1로 반환합니다.

이 “Exit code 0/1”이 중요한 이유는,
quality_check.bat 같은 상위 품질 커맨드에서 성공/실패 판단 기준으로 활용되기 때문이에요.

5. 실제로 에러가 났을 때, 초보자는 뭘 보면 될까?

예를 들어, 어떤 파일에 이런 식의 코드가 있었다고 가정해 볼게요.

def add(a, b)
    return a + b

여기에는 콜론(:)이 빠져 있죠.

py_compile_all.py를 실행하면, 출력은 대략 이런 형태가 됩니다. (형식은 구현에 따라 조금씩 다를 수 있어요.)

[Syntax Error] path/to/file/example.py
  File "path/to/file/example.py", line 1
    def add(a, b)
                 ^
SyntaxError: invalid syntax

초보자는 이 중에서 딱 두 가지만 보면 됩니다.

  1. 어느 파일에서 에러가 났는지
    → Β path/to/file/example.py
  2. 몇 번째 줄(line)에서 문제인지
    → Β line 1

이 두 가지 정보만으로 에디터에서 해당 파일을 열고, 해당 줄로 점프해서 수정하면 돼요.

그리고 다시 한 번 py_compile_all.py를 돌려보면

“이번에는 에러 없이 잘 지나간다 →
문법 오류가 제거되었다”

라고 이해하시면 됩니다.

6. 어떻게 실행하면 되나요?

실제 흐름을 Windows 기준으로 써 보면

6-1. 가상환경 활성화 (있다면)

C:\> cd 프로젝트\폴더\경로
C:\프로젝트\폴더\경로> your_venv_activate_script

(예: conda activate myenv 或 .venv\Scripts\activate)

6-2. 스크립트 직접 실행

(venv) C:\프로젝트\폴더\경로> python scripts\py_compile_all.py
  • 이걸 품질 커맨드 바깥에서 단독으로도 실행해 볼 수 있고,
  • 나중에는 quality_check.bat 안에서
    맨 처음 단계로 자동 호출하도록 연결해두면 됩니다.

6-3. 품질 커맨드 안에서 실행되는 버전

  • quality_check.bat 안에는 보통 다음과 비슷한 한 줄이 들어갑니다.
python scripts\py_compile_all.py
IF ERRORLEVEL 1 GOTO FAIL
  • 这样 구문 체크에서 에러가 나면
    FAIL 레이블로 점프해서 이후 검사(테스트 등)를 건너뛰고
    “품질 체크 실패” 메시지를 내보낼 수 있어요.

초보자 입장에서는

“quality_check.bat가 돌다가,
만약 구문 에러가 있으면 중간에 멈추는 구조구나”

정도만 이해해도 충분합니다.

7. Q&A – 초보자가 자주 할 만한 질문들

Q1. 테스트나 Django 체크만 하면 안 되나요?
A. 할 수는 있지만, 문법 에러는 가장 빨리 잡는 게 이득是
테스트를 돌리다가 문법 에러가 터져서 중간에 멈추는 것보다,
구문 체크에서 미리 “이 파일부터 고치세요”라고 알려주는 게 훨씬 친절하죠.

Q2. 구문 체크를 통과했는데, 여전히 버그가 있어요.
A. 구문 체크 = 문법 에러만 보는 것是
로직 버그(계산 실수, 조건 실수 등)는 테스트와 코드 리뷰가 잡아야 합니다.
구문 체크는 기본 건강검진이라고 생각하면 이해가 쉬워요.

Q3. venv 폴더까지 검사하면 안 되나요?
A. 가상환경은 내가 쓴 코드가 아니라 설치된 라이브러리 코드라
매번 모두 검사하면 속도도 느려지고, 의미도 크지 않습니다.
그래서 보통 venv 같은 폴더는 검사 대상에서 빼는 게 기본是

8. 용어 정리 (3편 버전)

  • Python 구문 체크 (Python syntax check)
    Python 코드가 문법적으로 올바른지,
    실행 전 단계에서 미리 확인하는 작업.
  • py_compile_all.py
    프로젝트 전체 .py 파일을 찾아서
    py_compile로 컴파일을 시도해보는 구문 검사 전용 스크립트.
  • py_compile 모듈
    파이썬 표준 라이브러리 중 하나로,
    .py 파일을 .pyc 바이트코드로 컴파일할 때 쓰이는 모듈.
    doraise=True 옵션을 주면, 에러가 있으면 예외를 던져줍니다.
  • Exit code (종료 코드)
    프로그램이 끝날 때 돌려주는 숫자.
    0이면 성공, 0 이외면 실패로 간주하는 관례가 있고,
    quality_check.bat 같은 상위 스크립트에서
    성공/실패 판단 기준으로 사용합니다.
  • 무시 목록(ignore list)
    검사에서 제외할 폴더/파일 목록.
    보통 venv, .venv, __pycache__ 같은 폴더가 여기에 들어갑니다.

类似文章