> ## Content Index
> Fetch the complete content index at: https://blog.frostk.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# 같은 Python 함수를 이름만 바꿨더니 gawain의 경고가 달라졌어요
- URL: https://blog.frostk.com/gawain-annotation-policy/
- Published: 2026-11-16T01:00:00.000Z
- Updated: 2026-11-16T01:00:00.000Z
- Description: Python 변수에도 타입 표기를 요구하는 gawain을 작은 입력으로 시험했어요. 같은 함수를 가리켜도 호출 이름에 따라 기본 모드의 경고가 달랐어요. Ruff ANN과 ty를 함께 돌려, 타입이 맞는지 검사하는 일과 코드에 타입을 써 두게 하는 정책이 어디서 갈리는지 비교해요.
- Author: Cat
- Tags: IT, 개발도구, 오픈소스

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

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

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

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

```python
from typing import Callable

def MakeCount() -> int:
    return 7

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

```

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

```sh
gawain check naming.py --no-types

```

결과는 하나였어요.

```text
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`의 명시적인 표기를 요구했어요.

이 차이는 [소스의 호출 판정](https://github.com/matheuzgomes/gawain/blob/807748f8a88460440ffb69823c5c962dcf41ee5e/src/presence/obvious.rs?ref=blog.frostk.com#L151-L180)과 맞아요. 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이 있지만, [공식 설명의 대상은 함수 인자와 반환값](https://docs.astral.sh/ruff/rules/any-type/?ref=blog.frostk.com)이에요. 시험 파일의 `payload: Any = 7`은 gawain에서 GW020으로 잡혔어요.

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

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

```python
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.![](https://blog.frostk.com/content/images/icon/favicon-9321ca5e-a5db-46cb-bdfc-4eda90c89d06.png)GitHub![](https://blog.frostk.com/content/images/thumbnail/gawain-f29c6fcc-a35e-4d2f-af3d-043aab79e08c.png)](https://github.com/matheuzgomes/gawain?ref=blog.frostk.com)

[any-type (ANN401) | RuffChecks that function arguments and return values are annotated with a more![](https://blog.frostk.com/content/images/icon/favicon-32x32-07572f99-e3db-4e3d-8e29-1fb1df4ba548.png)charliermarshlogo![](https://blog.frostk.com/content/images/thumbnail/bolt-7ab4eb4d-0d54-402a-b0f0-13f4e6b220ea.png)](https://docs.astral.sh/ruff/rules/any-type/?ref=blog.frostk.com)

[기본 모드와 규칙](https://github.com/matheuzgomes/gawain/blob/807748f8a88460440ffb69823c5c962dcf41ee5e/docs/rules.md?ref=blog.frostk.com), [단계 실행 코드](https://github.com/matheuzgomes/gawain/blob/807748f8a88460440ffb69823c5c962dcf41ee5e/src/check.rs?ref=blog.frostk.com)