TECH 으로 돌아가기
TECH HACKER NEWS 7분 읽기 56 READS

파이썬 모든 변수에 타입 힌트를 강제하는 도구 'Gawain'

파이썬 모든 변수에 타입 힌트를 강제하는 도구 'Gawain'
SOURCE IMAGE · HACKER NEWS

파이썬의 타입 힌트는 선택 사항이다. mypy, Pyright, 그리고 비교적 최근에 등장한 ty와 pyrefly 같은 타입 체커는 모두 애너테이션이 없는 변수의 타입을 스스로 추론한다. 덕분에 개발자는 명시적으로 타입을 적지 않아도 어느 정도의 정적 검사 혜택을 누릴 수 있다. ruff의 ANN 규칙이나 flake8-annotations 같은 린터 역시 애너테이션을 요구하긴 하지만, 그 대상은 함수의 매개변수와 반환값에 한정된다. 함수 시그니처 바깥, 즉 지역 변수나 클래스 속성은 여전히 비어 있는 채로 남는 경우가 많다. 새로 공개된 오픈소스 도구 Gawain은 바로 이 공백을 겨냥한다.

무엇을 검사하는가

Gawain은 변수, 매개변수, 반환값, 클래스 속성 네 가지 모두에 타입 애너테이션을 요구한다. 애너테이션이 빠진 곳을 찾아낸 뒤, 선택된 타입 체커(ty 또는 pyrefly)를 같은 파일에 실행해 실제로 타입이 올바른지까지 확인하는 2단계 구조다. 개발자가 밝힌 제작 동기는 솔직하다. dict[str, Any] 같은 느슨한 타입을 싫어했고, 그것을 강제로 줄이고 싶었다는 것이다. 그는 '어차피 파이썬이 추론해 주지 않느냐', 'IDE가 알려주지 않느냐'고 반문하는 사람이라면 이 도구를 쓸 필요가 없다고 분명히 선을 긋는다. 즉 Gawain은 추론으로 충분하다는 입장과는 반대편에 서서, 코드에 타입을 눈으로 보이게 명시하는 것 자체에 가치를 두는 도구다.

다만 모든 할당에 애너테이션을 강요하지는 않는다. 기본 모드는 '명백한(obvious)' 타입을 예외로 둔다. count = 0처럼 리터럴을 대입하거나, ids = [1, 2, 3]처럼 리터럴만 담은 컨테이너, user = User("ada")처럼 생성자 호출로 값이 분명하고, 그 이름에 다시 값을 할당하지 않는 경우에는 애너테이션 없이 넘어갈 수 있다. 반대로 retries = 3은 세 번 재할당되는 변수라 명시가 필요하고, PORT 같은 상수는 Final[int]로 적어야 한다는 식이다. 더 엄격하게 쓰고 싶다면 strict 모드가 모든 할당에 애너테이션을 요구한다. 규칙과 면제 조건, 억제 문법은 저장소의 docs/rules.md에 정리돼 있다.

설치와 동작 방식

설치는 쓰려는 타입 체커를 extra로 지정하는 방식이다. 기본값인 ty는 extra로 설치하면 0.0.100 버전에 고정되고, pyrefly extra를 쓰면 pyrefly 1.4.1이 설치되며 ty는 함께 깔리지 않는다. 체커 선택은 pyproject.toml의 [tool.gawain] 섹션에 checker = "pyrefly"를 넣거나 --checker pyrefly 옵션으로 전환한다. extra 없이 pip install gawain만 하면 명령어만 설치되므로, PATH에 체커가 있어야 하거나 --no-types로 애너테이션 검사만 돌려야 한다. 종료 코드는 CI에 붙이기 쉽게 설계돼 있다. 아무것도 보고하지 않으면 0, 오류를 보고하면 1, 사용법 오류나 타입 체커 실행 실패 시 2를 반환한다. 타입 체커의 경고는 출력되지만 검사를 실패로 만들지는 않는다. 또 GW000은 읽을 수 없는 파일, GW900·GW901은 깨지거나 쓰이지 않는 억제 지시를 표시하며, 특정 라인을 무시하려면 해당 코드를 직접 지정해야 한다.

성능 면에서는 밀리초 단위를 내세운다. CPython 3.14 표준 라이브러리(1,847개 파일, 974,586줄)를 대상으로 30회 실행 중앙값(flake8-annotations는 5회)을 측정했고, 이때 Gawain은 --no-types로 돌렸다. 다만 제작자 스스로 이것이 AMD 라이젠 7 3700X·WSL2라는 한 대의 기계에서 얻은 하나의 벤치마크임을 명시하고 있어, 수치를 절대적인 보증으로 받아들이기는 어렵다. 재현에 필요한 버전과 명령은 docs/benchmarks.md에 담겨 있다. 내부적으로 Gawain은 Astral의 ruff_python_parser로 파이썬 코드를 읽고, 같은 Astral의 ty 또는 Meta의 pyrefly로 타입을 검사한다. pre-commit 훅은 저장소 소스에서 빌드하므로 Rust 1.97 이상이 필요하다.

실무에서 고려할 점

실무 도입을 저울질한다면 안정성 경고를 먼저 읽어야 한다. 기본 체커인 ty는 아직 베타 단계이고, 버전 사이에 진단 결과가 바뀔 수 있다. 제작자는 이 변동이 프로젝트에 부담이 된다면 pyrefly를 쓰거나 --no-types로 애너테이션 검사만 돌리라고 권한다. 바꿔 말해 Gawain의 강점인 '타입 검증까지 연계'하는 2단계 기능은 아직 움직이는 기반 위에 서 있는 셈이고, 보수적인 팀이라면 당분간 애너테이션 강제 용도로만 쓰는 선택지가 현실적이다.

결국 이 도구가 어울리는 자리는 분명하다. 코드베이스 전반에서 타입을 추론에 맡기지 않고 명시적으로 드러내는 것을 팀 규율로 삼고 싶은 경우, 특히 함수 시그니처를 넘어 지역 변수와 클래스 속성까지 애너테이션을 요구하고 싶을 때 기존 린터의 빈틈을 메워준다. 반대로 IDE와 체커의 추론으로 충분하다고 보는 팀에게는 과한 마찰일 수 있고, 제작자도 그 점을 숨기지 않는다. 참고로 이름 Gawain은 원탁의 기사에서 따왔으며, 마스코트는 '가웨인 경과 녹색 기사'에 등장하는 녹색 기사의 도끼와 녹색 허리띠에서 가져왔다. 기능적 의미는 없지만, 타입을 깐깐하게 베어내는 도구의 성격과 묘하게 어울리는 작명이다.

SOURCE · HACKER NEWS
원문 전체 보기 → https://github.com/matheuzgomes/gawain
SHARE
NEXT · CHOOSE

변화를 읽었다면,
내가 만들 수익 구조를 고릅니다.

정보를 더 모으는 데서 멈추지 않고, 광고·외주·판매·중개·구독 중 내 상황에 맞는 출발점을 정해보세요.

21가지 수익 구조 살펴보기 →
처리 중...