Zettelkasten

Django 역참조 속성은 타입 검사기가 선언만 봐서는 알 수 없다

·수정 1회

요약

  • author.book_set은 Author 본문에 한 줄도 없고, 모델 클래스가 만들어질 때 메타클래스가 Book.author FK를 보고 Author에 심는다. 선언만 읽는 검사기는 이 속성을 모른다.
  • mypy는 django-stubs 플러그인이 모든 모델을 훑어 Author의 타입 정보에 끼워 넣는다. pyright는 플러그인이 없어서 RelatedManager["Book"]을 Author에 직접 선언해야 한다.
  • 라이브러리 스텁에 미리 적어 둘 수도 없다. 스텁은 사용자 프로젝트에 Author가 있는지 모른다.

본문

역참조 속성은 어디서 생기나

class Author(models.Model):
    name = models.CharField(max_length=100)

class Book(models.Model):
    author = models.ForeignKey(Author, on_delete=models.CASCADE)

author.book_set.all()  # Author 본문에 book_set은 한 줄도 없음
  • 이름은 FK를 가진 모델 이름 소문자 + _set이고, FK가 가리키는 모델 쪽에 붙는다. related_name="books"면 author.books다.
  • 방향을 헷갈리기 쉽다. User.team = ForeignKey(Team)이면 Team.user_set이지 User.user_set이 아니다.
  • 모델 클래스가 생성될 때 메타클래스가 FK를 보고 반대편 클래스에 descriptor를 심는다(일반 지식, 소스로 확인하지 않음).

왜 선언만 읽는 방식으로는 안 되나

  • Author의 타입을 알려면 프로젝트 모델 전부를 뒤져 "어떤 FK가 Author를 가리키나"를 찾아야 한다. 한 클래스를 분석하다 다른 클래스의 타입을 고치는 일이라, 클래스 본문의 선언을 읽는 방식으로는 나오지 않는다.
  • 라이브러리 스텁(.pyi)에 적는 방법도 막혀 있다. django-stubs는 사용자의 Author·Book을 모른다.
  • mypy는 플러그인이 이 일을 한다. django-stubs README는 "역참조 accessor 자동 선언"을 플러그인 몫으로 적는다.
  • pyright 계열은 플러그인이 없으므로 README 말대로 pyright·pyrefly·ty에서는 직접 선언한다. 배경은 pyright는 플러그인이 없어서 mypy 훅처럼 분석 도중 타입을 만들 수 없다에 있다.

pyright에서 메우는 법: 손으로 선언

from typing import TYPE_CHECKING
from django_stubs_ext.db.models.manager import RelatedManager

class Author(models.Model):
    name = models.CharField(max_length=100)
    if TYPE_CHECKING:
        book_set: RelatedManager["Book"]
  • README에 따르면 역참조 accessor에는 Manager가 아니라 RelatedManager를 쓴다. M2M 쪽은 ManyRelatedManager이고, 이 타입은 queryset 인자를 받지 않는다.
  • if TYPE_CHECKING:로 감싼 이유는 런타임에 같은 이름의 속성을 덮어쓰지 않으려는 것이다(이 코드 예는 직접 실행해 보지 않았다).
  • 모델마다 손으로 적어야 하고 FK가 바뀌면 같이 고쳐야 한다. 이 부담을 없애려면 프로젝트 모델을 읽어 스텁을 생성하는 django-autotyping 같은 도구를 쓴다(README 확인 범위 밖, 도구 소개글 기준).

함께 알아 둘 것

  • 기본 User.objects는 플러그인 없이 pyright도 Manager[User]로 잡는다. django-stubs base.pyi의 메타클래스 ModelBase.__getattr__(cls, name: Literal["objects"]) -> Manager[_Self]가 처리한다(직접 읽고 확인). 플러그인이 필요한 쪽은 from_queryset으로 만든 커스텀 매니저다.
  • 역참조는 "선언된 것을 유추하는" 문제가 아니라 "선언되지 않은 것을 만들어 내는" 문제라서 대표 사례가 된다. pyright가 Django를 단편적으로만 이해한다는 뜻은 아니다.

관련 노트

참고