Type hint custom Django model manager - correct way?

[dfillingham]

Hi,

What is the correct way to type hint a custom django model manager so that Intellisense will work when interacting with the manager via .objects and also when returning model instances from the built-in django queryset APIs?

Python version - 3.10.12
Django version - 5.0
Pylance version - v2024.6.1

A simple model & manager to demonstrate the issue I'm facing:

from __future__ import annotations

import typing
from django.db import models
from django.db.models import Manager

if typing.TYPE_CHECKING:
    from typing_extensions import Self

class SalesOrderManager(models.Manager):
    
    def create_sales_order(self, order_number: str):
        self.create(order_number=order_number, status="initial-entry")


class SalesOrder(models.Model):
    order_number = models.CharField()
    status = models.CharField()

    objects = SalesOrderManager()

    def is_order_open(self) -> bool:
        open_statuses = ["initial-entry", "awaiting-payment", "awaiting-delivery"]

        return self.status in open_statuses


def some_func():
    SalesOrder.objects.create_sales_order(order_number="123")

    order = SalesOrder.objects.first()

    is_open = order.is_order_open()

If I annotate objects like so: objects: SalesOrderManager = SalesOrderManager() then Intellisense works to find the custom function create_sales_order on the manager, however built-in Django APIs such as get, first etc are not typed as SalesOrder so the is_order_open function isn't found, nor are the model's fields.

This also occurs if I annotate as objects: SalesOrderManager[Self] = SalesOrderManager()

If I try to annotate objects like so: objects: SalesOrderManager[SalesOrder] = SalesOrderManager() then I get an error that SalesOrder is not yet defined

If I try to annotate objects like so: objects: Manager[SalesOrder] = SalesOrderManager() then I get the inverse, built-in APIs returning model instances are typed correctly however the custom manager function is not found:

[rchiodo]

I'll try to answer some of your questions.

For the objects annotation, you can do this:

objects: SalesOrderManager["SalesOrder"] = SalesOrderManager()

Type annotations in a class that reference that class can put quotes around a type. It's a forward reference.

For the order object, you should be able to do this:

    order: SalesOrder = typing.cast(SalesOrder, SalesOrder.objects.first())

For the get, first, etc, those aren't yet supported. See this issue for the list of things we're thinking about adding for Django support:
#3701