Example
Lazy managers
Given the following models:
| from django.db import models
class Project(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
class Task(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
project = models.ForeignKey(Project, on_delete=models.CASCADE, related_name="tasks")
|
We can delay the evaluation of a manager with the LazyModelManager descriptor:
| from typing import ClassVar, TYPE_CHECKING
from django.db import models
from lazy_managers import LazyModelManager
if TYPE_CHECKING:
from .querysets import ProjectManager, TaskManager
class Project(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
objects: ClassVar[ProjectManager[Project]] = LazyModelManager.new()
class Task(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
project = models.ForeignKey(Project, on_delete=models.CASCADE, related_name="tasks")
objects: ClassVar[TaskManager[Task]] = LazyModelManager.new()
|
With this, our manager (and queryset) classes will be lazily loaded when it is first accessed,
either from the class itself, or from a to-many relationship.
The advantage of this is that our manager (and queryset) module can freely import other modules
without causing cyclical imports.
Lazy attributes
The library also provides a way to lazily load other attributes on a model, with the
same benefits of avoiding cyclical imports.
| from typing import TYPE_CHECKING
from django.db import models
from lazy_managers import LazyModelAttribute
if TYPE_CHECKING:
from lazy_managers import LazyAttribute
from .validators import ProjectValidators, TaskValidators
class Project(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
validators: LazyAttribute[ProjectValidators] = LazyModelAttribute.new()
class Task(models.Model):
name = models.CharField(max_length=255)
description = models.TextField()
created_at = models.DateTimeField(auto_now_add=True)
project = models.ForeignKey(Project, on_delete=models.CASCADE, related_name="tasks")
validators: LazyAttribute[TaskValidators] = LazyModelAttribute.new()
|
Here the attribute should take a single argument, which is the instance of the model being accessed.
However, the attribute can be accessed on the class level, in which case the attribute class itself
will be given from the descriptor.
The LazyAttribute type hint tells type checkers about this: Project.validators is typed as
type[ProjectValidators], and project.validators is typed as ProjectValidators.
Type hints
The lazy descriptors find the class to load from the attribute's type hint, and the import
for that type hint in the same module. The type hint can be:
- a class, e.g.
ProjectManager
- a class wrapped in
ClassVar, Final or LazyAttribute, e.g. ClassVar[ProjectManager]
- a generic class, e.g.
ProjectManager[Project]
- an attribute of an imported module, e.g.
querysets.ProjectManager
The import can be relative or absolute, use an alias, or span multiple lines.
Union types like ProjectManager | None are not supported.
django-stubs
Lazy managers work with the django-stubs mypy plugin. The plugin finds the types for
the model's managers and related managers from the lazy managers' type hints,
so project.tasks.all() is typed as TaskQuerySet[Task, Task] in the example above.