Declare manager class attributes on models as ClassVars

Inclusions:

- Adjustments for the plugin to make generated managers `ClassVar`s
- Changes the default 'objects' to 'ClassVar' and controls it via the
  plugin
- Plugin ensures to only add the 'objects' manager to models it exists
  on during runtime

Author: flaeppe

django-stubs/contrib/admin/models.pyi

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, ClassVar
 from uuid import UUID
 
 from django.db import models
@@ -28,7 +28,7 @@ class LogEntry(models.Model):
     object_repr: models.CharField
     action_flag: models.PositiveSmallIntegerField
     change_message: models.TextField
-    objects: LogEntryManager
+    objects: ClassVar[LogEntryManager]
     def is_addition(self) -> bool: ...
     def is_change(self) -> bool: ...
     def is_deletion(self) -> bool: ...

django-stubs/contrib/auth/models.pyi

@@ -1,5 +1,5 @@
 from collections.abc import Iterable
-from typing import Any, Literal, TypeVar
+from typing import Any, ClassVar, Literal, TypeVar
 
 from django.contrib.auth.base_user import AbstractBaseUser as AbstractBaseUser
 from django.contrib.auth.base_user import BaseUserManager as BaseUserManager
@@ -10,7 +10,7 @@ from django.db.models import QuerySet
 from django.db.models.base import Model
 from django.db.models.manager import EmptyManager
 from django.utils.functional import _StrOrPromise
-from typing_extensions import TypeAlias
+from typing_extensions import Self, TypeAlias
 
 _AnyUser: TypeAlias = Model | AnonymousUser
 
@@ -21,7 +21,7 @@ class PermissionManager(models.Manager[Permission]):
 
 class Permission(models.Model):
     content_type_id: int
-    objects: PermissionManager
+    objects: ClassVar[PermissionManager]
 
     name = models.CharField(max_length=255)
     content_type = models.ForeignKey(ContentType, on_delete=models.CASCADE)
@@ -32,7 +32,7 @@ class GroupManager(models.Manager[Group]):
     def get_by_natural_key(self, name: str) -> Group: ...
 
 class Group(models.Model):
-    objects: GroupManager
+    objects: ClassVar[GroupManager]
 
     name = models.CharField(max_length=150)
     permissions = models.ManyToManyField(Permission)
@@ -81,6 +81,8 @@ class AbstractUser(AbstractBaseUser, PermissionsMixin):
     is_active = models.BooleanField()
     date_joined = models.DateTimeField()
 
+    objects: ClassVar[UserManager[Self]]
+
     EMAIL_FIELD: str
     USERNAME_FIELD: str
 

django-stubs/contrib/contenttypes/models.pyi

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, ClassVar
 
 from django.db import models
 from django.db.models.base import Model
@@ -15,7 +15,7 @@ class ContentType(models.Model):
     id: int
     app_label: models.CharField
     model: models.CharField
-    objects: ContentTypeManager
+    objects: ClassVar[ContentTypeManager]
     @property
     def name(self) -> str: ...
     def model_class(self) -> type[Model] | None: ...

django-stubs/contrib/sites/models.pyi

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, ClassVar
 
 from django.db import models
 from django.http.request import HttpRequest
@@ -11,7 +11,7 @@ class SiteManager(models.Manager[Site]):
     def get_by_natural_key(self, domain: str) -> Site: ...
 
 class Site(models.Model):
-    objects: SiteManager
+    objects: ClassVar[SiteManager]
 
     domain = models.CharField(max_length=100)
     name = models.CharField(max_length=50)

django-stubs/db/models/base.pyi

@@ -1,11 +1,11 @@
 from collections.abc import Collection, Iterable, Sequence
-from typing import Any, Final, TypeVar
+from typing import Any, ClassVar, Final, TypeVar
 
 from django.core.checks.messages import CheckMessage
 from django.core.exceptions import MultipleObjectsReturned as BaseMultipleObjectsReturned
 from django.core.exceptions import ObjectDoesNotExist, ValidationError
 from django.db.models import BaseConstraint, Field
-from django.db.models.manager import BaseManager
+from django.db.models.manager import BaseManager, Manager
 from django.db.models.options import Options
 from typing_extensions import Self
 
@@ -25,15 +25,16 @@ class ModelBase(type):
     def _base_manager(cls: type[_Self]) -> BaseManager[_Self]: ...  # type: ignore[misc]
 
 class Model(metaclass=ModelBase):
-    objects: BaseManager[Self]
-
     # Note: these two metaclass generated attributes don't really exist on the 'Model'
     # class, runtime they are only added on concrete subclasses of 'Model'. The
     # metaclass also sets up correct inheritance from concrete parent models exceptions.
     # Our mypy plugin aligns with this behaviour and will remove the 2 attributes below
     # and re-add them to correct concrete subclasses of 'Model'
     DoesNotExist: Final[type[ObjectDoesNotExist]]
     MultipleObjectsReturned: Final[type[BaseMultipleObjectsReturned]]
+    # This 'objects' attribute will be deleted, via the plugin, in favor of managing it
+    # to only exist on subclasses it exists on during runtime.
+    objects: ClassVar[Manager[Self]]
 
     class Meta: ...
     _meta: Options[Any]

mypy_django_plugin/lib/helpers.py

@@ -379,14 +379,17 @@ def check_types_compatible(
     api.check_subtype(actual_type, expected_type, ctx.context, error_message, "got", "expected")
 
 
-def add_new_sym_for_info(info: TypeInfo, *, name: str, sym_type: MypyType, no_serialize: bool = False) -> None:
+def add_new_sym_for_info(
+    info: TypeInfo, *, name: str, sym_type: MypyType, no_serialize: bool = False, is_classvar: bool = False
+) -> None:
     # type=: type of the variable itself
     var = Var(name=name, type=sym_type)
     # var.info: type of the object variable is bound to
     var.info = info
     var._fullname = info.fullname + "." + name
     var.is_initialized_in_class = True
     var.is_inferred = True
+    var.is_classvar = is_classvar
     info.names[name] = SymbolTableNode(MDEF, var, plugin_generated=True, no_serialize=no_serialize)
 
 

mypy_django_plugin/transformers/models.py

@@ -70,8 +70,13 @@ def create_new_var(self, name: str, typ: MypyType) -> Var:
         var.is_inferred = True
         return var
 
-    def add_new_node_to_model_class(self, name: str, typ: MypyType, no_serialize: bool = False) -> None:
-        helpers.add_new_sym_for_info(self.model_classdef.info, name=name, sym_type=typ, no_serialize=no_serialize)
+    def add_new_node_to_model_class(
+        self, name: str, typ: MypyType, no_serialize: bool = False, is_classvar: bool = False
+    ) -> None:
+        # TODO: Rename to signal that it is a `Var` that is added..
+        helpers.add_new_sym_for_info(
+            self.model_classdef.info, name=name, sym_type=typ, no_serialize=no_serialize, is_classvar=is_classvar
+        )
 
     def add_new_class_for_current_module(self, name: str, bases: List[Instance]) -> TypeInfo:
         current_module = self.api.modules[self.model_classdef.info.module_name]
@@ -311,7 +316,7 @@ def reparametrize_dynamically_created_manager(self, manager_name: str, manager_i
         assert manager_info is not None
         # Reparameterize dynamically created manager with model type
         manager_type = Instance(manager_info, [Instance(self.model_classdef.info, [])])
-        self.add_new_node_to_model_class(manager_name, manager_type)
+        self.add_new_node_to_model_class(manager_name, manager_type, is_classvar=True)
 
     def run_with_model_cls(self, model_cls: Type[Model]) -> None:
         manager_info: Optional[TypeInfo]
@@ -336,7 +341,7 @@ def run_with_model_cls(self, model_cls: Type[Model]) -> None:
                 continue
 
             manager_type = Instance(manager_info, [Instance(self.model_classdef.info, [])])
-            self.add_new_node_to_model_class(manager_name, manager_type)
+            self.add_new_node_to_model_class(manager_name, manager_type, is_classvar=True)
 
         if incomplete_manager_defs:
             if not self.api.final_iteration:
@@ -351,7 +356,9 @@ def run_with_model_cls(self, model_cls: Type[Model]) -> None:
                 # setting _some_ type
                 fallback_manager_info = self.get_or_create_manager_with_any_fallback()
                 self.add_new_node_to_model_class(
-                    manager_name, Instance(fallback_manager_info, [Instance(self.model_classdef.info, [])])
+                    manager_name,
+                    Instance(fallback_manager_info, [Instance(self.model_classdef.info, [])]),
+                    is_classvar=True,
                 )
 
                 # Find expression for e.g. `objects = SomeManager()`
@@ -623,6 +630,10 @@ def adjust_model_class(cls, ctx: ClassDefContext) -> None:
         ):
             del ctx.cls.info.names["MultipleObjectsReturned"]
 
+        objects = ctx.cls.info.names.get("objects")
+        if objects is not None and isinstance(objects.node, Var) and not objects.plugin_generated:
+            del ctx.cls.info.names["objects"]
+
         return
 
     def get_exception_bases(self, name: str) -> List[Instance]:

tests/typecheck/managers/test_managers.yml

@@ -194,7 +194,16 @@
 
 -   case: managers_inherited_from_abstract_classes_multiple_inheritance
     main: |
-        from myapp.models import Child
+        from myapp.models import AbstractBase1, AbstractBase2, Child
+        reveal_type(Child.manager1)
+        reveal_type(Child.restricted)
+        reveal_type(AbstractBase1.manager1)
+        reveal_type(AbstractBase2.restricted)
+    out: |
+        main:2: note: Revealed type is "myapp.models.CustomManager1[myapp.models.Child]"
+        main:3: note: Revealed type is "myapp.models.CustomManager2[myapp.models.Child]"
+        main:4: note: Revealed type is "myapp.models.CustomManager1[myapp.models.AbstractBase1]"
+        main:5: note: Revealed type is "myapp.models.CustomManager2[myapp.models.AbstractBase2]"
     installed_apps:
         - myapp
     files:
@@ -297,12 +306,13 @@
         -   path: myapp/__init__.py
         -   path: myapp/models.py
             content: |
+                from typing import ClassVar
                 from django.db import models
                 class ParentOfMyModel4(models.Model):
                     objects = models.Manager()
 
                 class MyModel4(ParentOfMyModel4):
-                    objects = models.Manager['MyModel4']()
+                    objects: ClassVar[models.Manager["MyModel4"]] = models.Manager["MyModel4"]()
 
 # TODO: make it work someday
 #-   case: inheritance_of_two_models_with_custom_objects_manager
@@ -570,7 +580,7 @@
         -   path: myapp/__init__.py
         -   path: myapp/models.py
             content: |
-                from typing import TypeVar
+                from typing import ClassVar, TypeVar
                 from django.db import models
 
                 T = TypeVar("T", bound="MyModel")
@@ -585,7 +595,7 @@
                     pass
 
                 class MySubModel(MyModel):
-                    objects = MySubManager()
+                    objects: ClassVar[MySubManager["MySubModel"]] = MySubManager()
 
 -   case: subclass_manager_without_type_parameters_disallow_any_generics
     main: |
@@ -598,14 +608,14 @@
         [mypy-myapp.models]
         disallow_any_generics = true
     out: |
-        main:2: note: Revealed type is "myapp.models.MySubManager[myapp.models.MySubModel]"
+        main:2: note: Revealed type is "myapp.models.MySubManager"
         main:3: note: Revealed type is "Any"
         myapp/models:9: error: Missing type parameters for generic type "MyManager"
     files:
         -   path: myapp/__init__.py
         -   path: myapp/models.py
             content: |
-                from typing import TypeVar
+                from typing import ClassVar, TypeVar
                 from django.db import models
 
                 T = TypeVar("T", bound="MyModel")
@@ -620,7 +630,7 @@
                     pass
 
                 class MySubModel(MyModel):
-                    objects = MySubManager()
+                    objects: ClassVar[MySubManager] = MySubManager()
 
 -   case: nested_manager_class_definition
     main: |

tests/typecheck/models/test_abstract.yml

@@ -51,8 +51,7 @@
     Recursive(parent=Recursive(parent=None))
     Concrete(parent=Concrete(parent=None))
   out: |
-    main:4: error: Access to generic instance variables via class is ambiguous
-    main:4: error: Unexpected attribute "parent" for model "Recursive"
+    main:4: error: "Type[Recursive]" has no attribute "objects"
     main:5: error: Cannot instantiate abstract class "Recursive" with abstract attributes "DoesNotExist" and "MultipleObjectsReturned"
     main:5: error: Unexpected attribute "parent" for model "Recursive"
   installed_apps:
@@ -210,4 +209,4 @@
 
             def create_animal_generic(klass: Type[T], name: str) -> T:
                 reveal_type(klass)  # N: Revealed type is "Type[T`-1]"
-                return klass.objects.create(name=name)  # E: Incompatible return value type (got "Animal", expected "T")
+                return klass._default_manager.create(name=name)

tests/typecheck/models/test_contrib_models.yml

@@ -31,9 +31,11 @@
 
 -   case: can_override_abstract_user_manager
     main: |
-        from myapp.models import User
-        reveal_type(User.objects)  # N: Revealed type is "myapp.models.UserManager[myapp.models.User]"
-        reveal_type(User.objects.all())  # N: Revealed type is "django.db.models.query._QuerySet[myapp.models.User, myapp.models.User]"
+        from myapp.models import MyBaseUser, MyUser
+        reveal_type(MyBaseUser.objects)  # N: Revealed type is "myapp.models.MyBaseUserManager[myapp.models.MyBaseUser]"
+        reveal_type(MyBaseUser.objects.all())  # N: Revealed type is "django.db.models.query._QuerySet[myapp.models.MyBaseUser, myapp.models.MyBaseUser]"
+        reveal_type(MyUser.objects)  # N: Revealed type is "myapp.models.MyUserManager"
+        reveal_type(MyUser.objects.all())  # N: Revealed type is "django.db.models.query._QuerySet[myapp.models.MyUser, myapp.models.MyUser]"
     installed_apps:
         - django.contrib.auth
         - myapp
@@ -42,8 +44,15 @@
         - path: myapp/models.py
           content: |
               from django.contrib.auth.base_user import AbstractBaseUser, BaseUserManager
-              class UserManager(BaseUserManager["User"]):
+              from django.contrib.auth.models import AbstractUser, UserManager
+              from typing import ClassVar
+              class MyBaseUserManager(BaseUserManager["MyBaseUser"]):
                   ...
 
-              class User(AbstractBaseUser):
-                  objects = UserManager()
+              class MyBaseUser(AbstractBaseUser):
+                  objects = MyBaseUserManager()
+
+              class MyUserManager(UserManager["MyUser"]):
+                  ...
+              class MyUser(AbstractUser):
+                  objects: ClassVar[MyUserManager] = MyUserManager()

tests/typecheck/models/test_meta_options.yml

@@ -77,10 +77,11 @@
         # Should not raise:
         MyModel(field=1)
         MyModel.objects.create(field=2)
+        AbstractModel._default_manager.create()
 
         # Errors:
         AbstractModel()  # E: Cannot instantiate abstract class "AbstractModel" with abstract attributes "DoesNotExist" and "MultipleObjectsReturned"
-        AbstractModel.objects.create()  # E: Access to generic instance variables via class is ambiguous
+        AbstractModel.objects.create()  # E: "Type[AbstractModel]" has no attribute "objects"
     installed_apps:
         - myapp
     files: