요약
- 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 theobjectsmanager 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: 프로젝트 모델을 읽어 프로젝트별 스텁을 생성하는, 검사기와 무관한 도구다.
관련 노트
참고
- https://github.com/microsoft/pyright/blob/main/docs/mypy-comparison.md
- https://docs.basedpyright.com/latest/
- https://github.com/typeddjango/django-stubs
- https://github.com/typeddjango/django-stubs/blob/master/django-stubs/db/models/base.pyi
- https://pypi.org/project/django-types
- https://viicos.github.io/posts/an-alternative-to-the-django-mypy-plugin