Zettelkasten

pyright는 플러그인이 없어서 mypy 훅처럼 분석 도중 타입을 만들 수 없다

·수정 1회

요약

  • mypy는 검사 도중 사용자 코드(플러그인)를 호출해 타입을 계산하게 할 수 있고, pyright는 플러그인 자체를 지원하지 않는다. basedpyright는 pyright 포크라 같은 제약이다.
  • pyright에서 라이브러리 타입을 넓히는 길은 .pyi 스텁, 표준 타입 기능(dataclass_transform 등), 검사 전에 스텁을 생성하는 도구뿐이다. 모두 "미리 선언을 적어 두는" 방식이다.
  • 그래서 Django처럼 런타임에 메타클래스가 속성을 만들어 내는 부분은 pyright가 모른다. 선언된 것은 pyright도 똑같이 유추한다.

본문

문서에서 가져온 것: pyright의 입장

  • pyright 공식 문서 mypy-comparison의 Plugins 절: "Mypy supports a plug-in mechanism, whereas pyright does not."
  • 지원하지 않는 이유로 discoverability, maintainability, 플러그인 작성자의 개발 비용, 플러그인 객체 모델·API의 유지 비용, security, performance를 든다. (원문 확인 범위는 이 나열까지이고, latency·robustness 표현은 직접 확인하지 못했다.)
  • 대신 typing 커뮤니티·라이브러리 저자와 협업해 타입 시스템 자체를 넓힌다는 방침이고, 예로 PEP 681 dataclass_transform을 든다.
  • basedpyright 공식 문서(docs.basedpyright.com)에는 플러그인·Django 언급이 없다. pyright 포크이므로 같은 제약이라고 보는 것은 추론이다.

mypy 훅이 하는 일 (미검증: mypy 플러그인 API 일반 지식)

  • get_base_class_hook: 특정 베이스 클래스를 상속한 클래스 정의를 만날 때 호출된다. 클래스 안을 읽고 속성을 추가할 수 있다.
  • get_method_hook·get_function_hook: 메서드·함수 호출 결과 타입을 계산한다. 인자 이름이나 값을 보고 반환형을 바꿀 수 있다.
  • get_attribute_hook, get_type_analyze_hook, get_dynamic_class_hook, get_metaclass_hook도 있다.
  • django-stubs 플러그인은 이 훅으로 models.Model 상속 클래스에서 필드를 읽어 id, get_FOO_display(), 역참조 accessor를 타입 정보에 추가한다. filter(**kwargs) 인자 이름을 모델 필드와 대조하고, get_user_model() 반환형을 settings.AUTH_USER_MODEL로 바꾼다. 검사 시작 때 django.setup()을 실제로 실행한다. (이 내부 동작은 일반 지식이라 소스로 확인하지 않았다.)

확장 범위 정리 (이 대화에서 도출한 결론)

하고 싶은 일 mypy pyright
분석 도중 외부 함수를 불러 타입 계산 훅으로 가능 불가
외부 상태(settings.py) 읽기 플러그인이 django.setup() 실행 불가
라이브러리별 특수 규칙 플러그인에 코드로 작성 불가
.pyi 스텁으로 선언 덮어쓰기 가능 가능(stubPath)
제네릭, dataclass_transform, TypedDict, Protocol, 오버로드 가능 가능
메타클래스 __getattr__ + Literal 가능 가능
검사 전에 스텁 생성 가능 가능(django-autotyping)

한 줄로 줄이면, 실행 중에 똑똑해지는 길은 막혀 있고 미리 선언을 충분히 적어 두는 길로만 확장된다. "pyright는 Django를 단편적으로밖에 유추 못 한다"는 과장이다. 선언된 것은 전부 유추하고, 모르는 것은 런타임에 메타클래스가 만들어 내는 속성이다. 대표 사례는 Django 역참조 속성은 타입 검사기가 선언만 봐서는 알 수 없다에 정리했다.

django-stubs README가 보는 지원 수준

  • mypy: "full and complete support with multiple advanced features with our custom mypy plugin"
  • pyright, pyrefly, ty: "basic support, checked in CI"
  • 플러그인 몫으로 적힌 기능: 역참조 accessor 자동 선언, QuerySet.annotate로 붙은 이름 추적(WithAnnotations), Manager.from_queryset 타입, Model Meta 검사, 플러그인 설정 django_settings_module·strict_settings.
  • 플러그인 없는 검사기에서는 역참조를 RelatedManager·ManyRelatedManager로, annotate 결과를 WithAnnotations로 직접 선언하고, Meta는 TypedModelMeta를 상속한다. Manager.from_queryset(...)로 만든 매니저는 Product.objects가 파라미터 없는 Manager로 보인다.

직접 읽고 확인한 것: 기본 objects는 pyright도 안다

  • django-stubs db/models/base.pyi에서 class Model에는 objects 선언이 없고, 메타클래스 ModelBase에 def __getattr__(cls: type[_Self], name: Literal["objects"]) -> Manager[_Self]: ...가 있다. 주석은 "Class level only access for the objects manager when it's not defined explicitly."이다. Model에는 pk: Any, _meta: ClassVar[Options[Self]]가 있다.
  • 따라서 기본 User.objects는 플러그인 없이도 Manager[User]로 잡히고, 이 부분은 표준 기능(메타클래스 __getattr__ + Literal)으로 해결한 사례다. 플러그인이 필요한 쪽은 커스텀 매니저(objects = UserManager.from_queryset(UserQuerySet)())다.

connectingServer에서 직접 관찰한 것 (2026-11-04 mypy 기준선 작업)

  • 플러그인 없이 mypy 오류가 4,386개, 플러그인을 켜자 2,544개였다. 약 1,800개가 줄었고, 이 차이가 pyright가 플러그인 없이 채우지 못하는 타입 정보의 크기를 가늠하는 단서다. (pyright로 같은 코드를 돌려 센 값은 아니다.)
  • 플러그인 크래시가 한 번 났다. services/account/models/user_models.py:58의 if TYPE_CHECKING: 안에서 자기 모듈을 import하는 줄(2023-02-17 커밋)이 있을 때 플러그인의 transformers.auth.get_user_model에서 크래시했고, 그 줄을 지우면 정상이었다. 검사기 안에서 외부 코드가 도는 구조의 비용이며, pyright가 플러그인을 거부한 이유 중 robustness와 닿아 보인다. 크래시 원인이 그 줄 하나라는 것은 지웠을 때 정상이라는 관찰에 근거하고, 플러그인 내부 코드까지 따라가 확인하지는 않았다.

대안 패키지

  • django-types(sbdchd): django-stubs를 포크해 mypy 플러그인 의존을 뗀 스텁 패키지다. README에 "non-mypy type checkers like pyright will work better with Django"가 목적으로 적혀 있다. 이번에 README 원문을 직접 열지는 않았다.
  • django-autotyping: 프로젝트 모델을 읽어 프로젝트별 스텁을 생성하는, 검사기와 무관한 도구다.

관련 노트

참고