본문 바로가기
FrostK
테마 색상
로그인

읽는 데 7분Cat

같은 Python 함수를 이름만 바꿨더니 gawain의 경고가 달라졌어요

같은 Python 함수를 이름만 바꿨더니 gawain의 경고가 달라졌어요

같은 함수를 가리키는 이름 두 개를 만들었어요. MakeCount()의 결과를 담은 변수는 통과했는데, make_count()의 결과를 담은 변수에는 타입을 적으라는 경고가 나왔어요. Python 타입 표기를 검사하는 gawain의 기본 모드는 호출 이름의 모양도 봐요.

타입을 알아낼 수 있는 코드에 왜 타입을 더 적어야 할까요? gawain은 그걸 팀의 작성 규칙으로 정하려는 도구예요. matheuzgomes가 공개한 MIT 라이선스 프로젝트이고, 이번에는 Linux와 Python 3.12.16에서 gawain 0.3.1을 시험했어요.

같은 함수인데 한쪽만 경고했어요

아래 파일을 naming.py로 저장했어요. Callable[[], int]는 인자 없이 호출하면 정수를 돌려주는 함수라는 뜻이에요. 두 호출은 같은 함수를 가리키도록 했고, 별칭 자체에는 타입을 적어 불필요한 경고를 없앴어요.

from typing import Callable


def MakeCount() -> int:
    return 7


make_count: Callable[[], int] = MakeCount
upper_result = MakeCount()
lower_result = make_count()

타입 표기가 있는지만 보는 명령을 실행했어요.

gawain check naming.py --no-types

결과는 하나였어요.

naming.py:10:1  GW001 variable 'lower_result' has no type annotation

같은 파일에 ty check naming.py를 실행하면 All checks passed!가 나왔어요. ty 0.0.100은 이 입력에서 타입 오류를 보고하지 않았고, gawain은 lower_result의 명시적인 표기를 요구했어요.

이 차이는 소스의 호출 판정과 맞아요. gawain은 호출 이름이 대문자로 시작하고 소문자를 포함하는지 먼저 봐요. User나 MakeCount는 그 조건을 충족하지만 make_count는 아니에요. 이 검사에서 클래스 생성자와 대문자로 이름 붙인 일반 함수를 완전히 구별하는 건 아니죠.

기본 obvious 모드는 값의 타입이 코드 모양상 분명하다고 판단하고, 그 이름에 다시 대입하지 않을 때 타입 표기를 생략할 수 있게 해요. 생성자처럼 보이는 이름을 통한 예외이지, 타입 검사기가 추론할 수 있는 모든 표현식에 대한 예외는 아니에요.

Ruff와 ty 사이에 하나 더 생기는 규칙

다른 파일에는 빈 리스트, 재대입하는 정수 변수, Any로 표시한 변수, 반환 타입이 틀린 함수를 함께 넣었어요. Any는 타입 제약을 넓게 풀어 두는 표기예요. 비교에는 Ruff 0.17.5를 썼어요.

같은 시험 파일에 실행한 검사 실제 결과
ruff check cases.py --select ANN 통과
ty check cases.py 정수 반환을 선언하고 문자열을 돌려준 함수에서 오류
gawain check cases.py 타입 표기 관련 오류를 먼저 보고하고 타입 검사 단계는 건너뜀

Ruff의 ANN 규칙은 함수의 매개변수와 반환 타입 표기를 다뤄요. 이번 파일은 함수 표기를 갖췄으므로 통과했어요. Ruff에도 Any를 지적하는 ANN401이 있지만, 공식 설명의 대상은 함수 인자와 반환값이에요. 시험 파일의 payload: Any = 7은 gawain에서 GW020으로 잡혔어요.

gawain이 더 많은 변수를 검사한다고 타입 오류까지 먼저 보여 주는 건 아니에요. 이 도구는 타입 표기 검사를 통과해야 다음 타입 검사기로 넘어가요. 표기가 빠진 코드가 많은 저장소라면, 그 정비가 끝날 때까지 잘못된 반환값 같은 오류가 gawain의 결과에 함께 나오지 않을 수 있어요.

이를 분리해 확인하려고 아래 함수만 typed.py에 남겼어요.

def wrong() -> int:
    return "wrong"

이번에는 gawain check typed.py가 [types] 단계로 들어가 ty의 invalid-return-type 오류를 출력했어요. 타입 검사 기능이 없는 게 아니라, 앞 단계가 통과 조건인 셈이에요.

명시성을 어디까지 강제할까요

별도 입력에서 한 번만 대입한 literal = 7은 기본 모드에서 지적되지 않았어요. 빈 리스트 empty = []와 같은 이름에 두 번 대입한 정수 변수는 타입을 요구받았고요. --mode strict로 바꾸면 그 리터럴과 앞서 통과한 MakeCount() 결과 변수까지 타입을 요구받았어요.

이미 Ruff ANN과 타입 검사기를 쓰는 팀이라면 gawain을 더할 이유는 변수와 속성까지 작성 규칙을 넓히려는 데 있어요. 기본 모드를 고르면 ‘분명함’이 팀의 기대와 같은지 작은 파일부터 확인할 만해요. 함수 이름 하나로 예외가 달라지는 것이 싫다면 strict 모드가 더 예측하기 쉬운 선택이에요.

제 생각엔 기존 타입 검사 작업은 별도로 유지한 채, gawain을 명시성 정책 검사로 추가하는 쪽이 도입 의도를 드러내기 좋아요. 표기 정비 중에도 타입 오류를 독립적으로 볼 수 있으니까요. 설치는 공식 README의 uv tool install "gawain[ty]"로 시작할 수 있어요. 이번 버전의 ty extra는 ty 0.0.100을 고정해 설치해요.

확인한 범위

  • 기준일: 2026-11-16
  • 직접 한 것: Linux, Python 3.12.16에서 gawain 0.3.1, ty 0.0.100, Ruff 0.17.5에 같은 작은 입력을 넣었어요. 함수 별칭의 호출 이름, 변수의 Any, 리터럴과 재대입, 표기 오류가 있을 때와 없을 때의 타입 검사 진입을 비교하고 고정 커밋의 호출 판정 코드와 대조했어요.
  • 읽은 것: gawain README와 규칙 문서, 호출 판정 및 단계 실행 코드, Ruff ANN401 공식 문서.
  • 확인하지 못한 것: 큰 실제 저장소에서의 진단 품질과 정비 비용, pyrefly 조합은 시험하지 않았어요.

출처

GitHub - matheuzgomes/gawain: Every Python type declared, every covenant kept.
Every Python type declared, every covenant kept. Contribute to matheuzgomes/gawain development by creating an account on GitHub.
any-type (ANN401) | Ruff
Checks that function arguments and return values are annotated with a more

기본 모드와 규칙, 단계 실행 코드