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

[thomthom]

For the objects annotation, you can do this:

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

I'm getting pylance errors with that:

Expected no type arguments for class "SalesOrderManager"

VSCode: 1.96.4, Pylance VSCode extension: 2024.12.1

[thomthom]

objects: models.Manager['SalesOrder'] = SalesOrderManager()

That seemed to do the trick. Is this correct?

Edit: Doing that makes QuerySets act as expected, but the custom methods on the manager is not picked up.

Edit 2:

This seems to allow Pylance to understand that the QuerySets deal with SalesOrder and pick up the manager methods:

class SalesOrderManager(models.Manager['SalesOrder']):
  def foo():
    pass

class SalesOrder
  objects: SalesOrderManager = SalesOrderManager()

[rchiodo]

Most of Django's custom methods are dynamic and Pylance doesn't know about them. It can only statically analyze your code to see methods that are allowed. Hence why the custom methods on the QuerySet are not found.

We hope to fix this eventually, but it requires something we don't currently have - a way to run python code without possibly affecting your system.