Debian Codegraph @

django/db/models/fields/related_descriptors.py

raw
1 """
2 Accessors for related objects.
3
4 When a field defines a relation between two models, each model class provides
5 an attribute to access related instances of the other model class (unless the
6 reverse accessor has been disabled with related_name='+').
7
8 Accessors are implemented as descriptors in order to customize access and
9 assignment. This module defines the descriptor classes.
10
11 Forward accessors follow foreign keys. Reverse accessors trace them back. For
12 example, with the following models::
13
14 class Parent(Model):
15 pass
16
17 class Child(Model):
18 parent = ForeignKey(Parent, related_name='children')
19
20 ``child.parent`` is a forward many-to-one relation. ``parent.children`` is a
21 reverse many-to-one relation.
22
23 There are three types of relations (many-to-one, one-to-one, and many-to-many)
24 and two directions (forward and reverse) for a total of six combinations.
25
26 1. Related instance on the forward side of a many-to-one relation:
27 ``ForwardManyToOneDescriptor``.
28
29 Uniqueness of foreign key values is irrelevant to accessing the related
30 instance, making the many-to-one and one-to-one cases identical as far as
31 the descriptor is concerned. The constraint is checked upstream (unicity
32 validation in forms) or downstream (unique indexes in the database).
33
34 2. Related instance on the forward side of a one-to-one
35 relation: ``ForwardOneToOneDescriptor``.
36
37 It avoids querying the database when accessing the parent link field in
38 a multi-table inheritance scenario.
39
40 3. Related instance on the reverse side of a one-to-one relation:
41 ``ReverseOneToOneDescriptor``.
42
43 One-to-one relations are asymmetrical, despite the apparent symmetry of the
44 name, because they're implemented in the database with a foreign key from
45 one table to another. As a consequence ``ReverseOneToOneDescriptor`` is
46 slightly different from ``ForwardManyToOneDescriptor``.
47
48 4. Related objects manager for related instances on the reverse side of a
49 many-to-one relation: ``ReverseManyToOneDescriptor``.
50
51 Unlike the previous two classes, this one provides access to a collection
52 of objects. It returns a manager rather than an instance.
53
54 5. Related objects manager for related instances on the forward or reverse
55 sides of a many-to-many relation: ``ManyToManyDescriptor``.
56
57 Many-to-many relations are symmetrical. The syntax of Django models
58 requires declaring them on one side but that's an implementation detail.
59 They could be declared on the other side without any change in behavior.
60 Therefore the forward and reverse descriptors can be the same.
61
62 If you're looking for ``ForwardManyToManyDescriptor`` or
63 ``ReverseManyToManyDescriptor``, use ``ManyToManyDescriptor`` instead.
64 """
65
66 import warnings
67
68 from asgiref.sync import sync_to_async
69
70 from django.core.exceptions import FieldError
71 from django.db import (
72 DEFAULT_DB_ALIAS,
73 NotSupportedError,
74 connections,
75 router,
76 transaction,
77 )
78 from django.db.models import Manager, Q, Window, signals
79 from django.db.models.expressions import ColPairs
80 from django.db.models.fields.tuple_lookups import TupleIn
81 from django.db.models.functions import RowNumber
82 from django.db.models.lookups import GreaterThan, LessThanOrEqual
83 from django.db.models.query import QuerySet
84 from django.db.models.query_utils import DeferredAttribute
85 from django.db.models.utils import AltersData, resolve_callables
86 from django.utils.deprecation import RemovedInDjango60Warning
87 from django.utils.functional import cached_property
88
89
90 class ForeignKeyDeferredAttribute(DeferredAttribute):
91 def __set__(self, instance, value):
92 if instance.__dict__.get(self.field.attname) != value and self.field.is_cached(
93 instance
94 ):
95 self.field.delete_cached_value(instance)
96 instance.__dict__[self.field.attname] = value
97
98
99 def _filter_prefetch_queryset(queryset, field_name, instances):
100 predicate = Q(**{f"{field_name}__in": instances})
101 db = queryset._db or DEFAULT_DB_ALIAS
102 if queryset.query.is_sliced:
103 if not connections[db].features.supports_over_clause:
104 raise NotSupportedError(
105 "Prefetching from a limited queryset is only supported on backends "
106 "that support window functions."
107 )
108 low_mark, high_mark = queryset.query.low_mark, queryset.query.high_mark
109 order_by = [
110 expr for expr, _ in queryset.query.get_compiler(using=db).get_order_by()
111 ]
112 window = Window(RowNumber(), partition_by=field_name, order_by=order_by)
113 predicate &= GreaterThan(window, low_mark)
114 if high_mark is not None:
115 predicate &= LessThanOrEqual(window, high_mark)
116 queryset.query.clear_limits()
117 # All pre-existing JOINs must be re-used when applying the predicate to
118 # avoid unintended spanning of multi-valued relationships.
119 queryset.query.add_q(predicate, reuse_all=True)
120 return queryset
121
122
123 class ForwardManyToOneDescriptor:
124 """
125 Accessor to the related object on the forward side of a many-to-one or
126 one-to-one (via ForwardOneToOneDescriptor subclass) relation.
127
128 In the example::
129
130 class Child(Model):
131 parent = ForeignKey(Parent, related_name='children')
132
133 ``Child.parent`` is a ``ForwardManyToOneDescriptor`` instance.
134 """
135
136 def __init__(self, field_with_rel):
137 self.field = field_with_rel
138
139 @cached_property
140 def RelatedObjectDoesNotExist(self):
141 # The exception can't be created at initialization time since the
142 # related model might not be resolved yet; `self.field.model` might
143 # still be a string model reference.
144 return type(
145 "RelatedObjectDoesNotExist",
146 (self.field.remote_field.model.DoesNotExist, AttributeError),
147 {
148 "__module__": self.field.model.__module__,
149 "__qualname__": "%s.%s.RelatedObjectDoesNotExist"
150 % (
151 self.field.model.__qualname__,
152 self.field.name,
153 ),
154 },
155 )
156
157 def is_cached(self, instance):
158 return self.field.is_cached(instance)
159
160 def get_queryset(self, **hints):
161 return self.field.remote_field.model._base_manager.db_manager(hints=hints).all()
162
163 def get_prefetch_queryset(self, instances, queryset=None):
164 warnings.warn(
165 "get_prefetch_queryset() is deprecated. Use get_prefetch_querysets() "
166 "instead.",
167 RemovedInDjango60Warning,
168 stacklevel=2,
169 )
170 if queryset is None:
171 return self.get_prefetch_querysets(instances)
172 return self.get_prefetch_querysets(instances, [queryset])
173
174 def get_prefetch_querysets(self, instances, querysets=None):
175 if querysets and len(querysets) != 1:
176 raise ValueError(
177 "querysets argument of get_prefetch_querysets() should have a length "
178 "of 1."
179 )
180 queryset = querysets[0] if querysets else self.get_queryset()
181 queryset._add_hints(instance=instances[0])
182
183 rel_obj_attr = self.field.get_foreign_related_value
184 instance_attr = self.field.get_local_related_value
185 instances_dict = {instance_attr(inst): inst for inst in instances}
186 remote_field = self.field.remote_field
187 related_fields = [
188 queryset.query.resolve_ref(field.name).target
189 for field in self.field.foreign_related_fields
190 ]
191 queryset = queryset.filter(
192 TupleIn(
193 ColPairs(
194 queryset.model._meta.db_table,
195 related_fields,
196 related_fields,
197 self.field,
198 ),
199 list(instances_dict),
200 )
201 )
202 # There can be only one object prefetched for each instance so clear
203 # ordering if the query allows it without side effects.
204 queryset.query.clear_ordering()
205
206 # Since we're going to assign directly in the cache,
207 # we must manage the reverse relation cache manually.
208 if not remote_field.multiple:
209 for rel_obj in queryset:
210 instance = instances_dict[rel_obj_attr(rel_obj)]
211 remote_field.set_cached_value(rel_obj, instance)
212 return (
213 queryset,
214 rel_obj_attr,
215 instance_attr,
216 True,
217 self.field.cache_name,
218 False,
219 )
220
221 def get_object(self, instance):
222 qs = self.get_queryset(instance=instance)
223 # Assuming the database enforces foreign keys, this won't fail.
224 return qs.get(self.field.get_reverse_related_filter(instance))
225
226 def __get__(self, instance, cls=None):
227 """
228 Get the related instance through the forward relation.
229
230 With the example above, when getting ``child.parent``:
231
232 - ``self`` is the descriptor managing the ``parent`` attribute
233 - ``instance`` is the ``child`` instance
234 - ``cls`` is the ``Child`` class (we don't need it)
235 """
236 if instance is None:
237 return self
238
239 # The related instance is loaded from the database and then cached
240 # by the field on the model instance state. It can also be pre-cached
241 # by the reverse accessor (ReverseOneToOneDescriptor).
242 try:
243 rel_obj = self.field.get_cached_value(instance)
244 except KeyError:
245 has_value = None not in self.field.get_local_related_value(instance)
246 ancestor_link = (
247 instance._meta.get_ancestor_link(self.field.model)
248 if has_value
249 else None
250 )
251 if ancestor_link and ancestor_link.is_cached(instance):
252 # An ancestor link will exist if this field is defined on a
253 # multi-table inheritance parent of the instance's class.
254 ancestor = ancestor_link.get_cached_value(instance)
255 # The value might be cached on an ancestor if the instance
256 # originated from walking down the inheritance chain.
257 rel_obj = self.field.get_cached_value(ancestor, default=None)
258 else:
259 rel_obj = None
260 if rel_obj is None and has_value:
261 rel_obj = self.get_object(instance)
262 remote_field = self.field.remote_field
263 # If this is a one-to-one relation, set the reverse accessor
264 # cache on the related object to the current instance to avoid
265 # an extra SQL query if it's accessed later on.
266 if not remote_field.multiple:
267 remote_field.set_cached_value(rel_obj, instance)
268 self.field.set_cached_value(instance, rel_obj)
269
270 if rel_obj is None and not self.field.null:
271 raise self.RelatedObjectDoesNotExist(
272 "%s has no %s." % (self.field.model.__name__, self.field.name)
273 )
274 else:
275 return rel_obj
276
277 def __set__(self, instance, value):
278 """
279 Set the related instance through the forward relation.
280
281 With the example above, when setting ``child.parent = parent``:
282
283 - ``self`` is the descriptor managing the ``parent`` attribute
284 - ``instance`` is the ``child`` instance
285 - ``value`` is the ``parent`` instance on the right of the equal sign
286 """
287 # An object must be an instance of the related class.
288 if value is not None and not isinstance(
289 value, self.field.remote_field.model._meta.concrete_model
290 ):
291 raise ValueError(
292 'Cannot assign "%r": "%s.%s" must be a "%s" instance.'
293 % (
294 value,
295 instance._meta.object_name,
296 self.field.name,
297 self.field.remote_field.model._meta.object_name,
298 )
299 )
300 elif value is not None:
301 if instance._state.db is None:
302 instance._state.db = router.db_for_write(
303 instance.__class__, instance=value
304 )
305 if value._state.db is None:
306 value._state.db = router.db_for_write(
307 value.__class__, instance=instance
308 )
309 if not router.allow_relation(value, instance):
310 raise ValueError(
311 'Cannot assign "%r": the current database router prevents this '
312 "relation." % value
313 )
314
315 remote_field = self.field.remote_field
316 # If we're setting the value of a OneToOneField to None, we need to clear
317 # out the cache on any old related object. Otherwise, deleting the
318 # previously-related object will also cause this object to be deleted,
319 # which is wrong.
320 if value is None:
321 # Look up the previously-related object, which may still be available
322 # since we've not yet cleared out the related field.
323 # Use the cache directly, instead of the accessor; if we haven't
324 # populated the cache, then we don't care - we're only accessing
325 # the object to invalidate the accessor cache, so there's no
326 # need to populate the cache just to expire it again.
327 related = self.field.get_cached_value(instance, default=None)
328
329 # If we've got an old related object, we need to clear out its
330 # cache. This cache also might not exist if the related object
331 # hasn't been accessed yet.
332 if related is not None:
333 remote_field.set_cached_value(related, None)
334
335 for lh_field, rh_field in self.field.related_fields:
336 setattr(instance, lh_field.attname, None)
337
338 # Set the values of the related field.
339 else:
340 for lh_field, rh_field in self.field.related_fields:
341 setattr(instance, lh_field.attname, getattr(value, rh_field.attname))
342
343 # Set the related instance cache used by __get__ to avoid an SQL query
344 # when accessing the attribute we just set.
345 self.field.set_cached_value(instance, value)
346
347 # If this is a one-to-one relation, set the reverse accessor cache on
348 # the related object to the current instance to avoid an extra SQL
349 # query if it's accessed later on.
350 if value is not None and not remote_field.multiple:
351 remote_field.set_cached_value(value, instance)
352
353 def __reduce__(self):
354 """
355 Pickling should return the instance attached by self.field on the
356 model, not a new copy of that descriptor. Use getattr() to retrieve
357 the instance directly from the model.
358 """
359 return getattr, (self.field.model, self.field.name)
360
361
362 class ForwardOneToOneDescriptor(ForwardManyToOneDescriptor):
363 """
364 Accessor to the related object on the forward side of a one-to-one relation.
365
366 In the example::
367
368 class Restaurant(Model):
369 place = OneToOneField(Place, related_name='restaurant')
370
371 ``Restaurant.place`` is a ``ForwardOneToOneDescriptor`` instance.
372 """
373
374 def get_object(self, instance):
375 if self.field.remote_field.parent_link:
376 deferred = instance.get_deferred_fields()
377 # Because it's a parent link, all the data is available in the
378 # instance, so populate the parent model with this data.
379 rel_model = self.field.remote_field.model
380 fields = [field.attname for field in rel_model._meta.concrete_fields]
381
382 # If any of the related model's fields are deferred, fallback to
383 # fetching all fields from the related model. This avoids a query
384 # on the related model for every deferred field.
385 if not any(field in fields for field in deferred):
386 kwargs = {field: getattr(instance, field) for field in fields}
387 obj = rel_model(**kwargs)
388 obj._state.adding = instance._state.adding
389 obj._state.db = instance._state.db
390 return obj
391 return super().get_object(instance)
392
393 def __set__(self, instance, value):
394 super().__set__(instance, value)
395 # If the primary key is a link to a parent model and a parent instance
396 # is being set, update the value of the inherited pk(s).
397 if self.field.primary_key and self.field.remote_field.parent_link:
398 opts = instance._meta
399 # Inherited primary key fields from this object's base classes.
400 inherited_pk_fields = [
401 field
402 for field in opts.concrete_fields
403 if field.primary_key and field.remote_field
404 ]
405 for field in inherited_pk_fields:
406 rel_model_pk_name = field.remote_field.model._meta.pk.attname
407 raw_value = (
408 getattr(value, rel_model_pk_name) if value is not None else None
409 )
410 setattr(instance, rel_model_pk_name, raw_value)
411
412
413 class ReverseOneToOneDescriptor:
414 """
415 Accessor to the related object on the reverse side of a one-to-one
416 relation.
417
418 In the example::
419
420 class Restaurant(Model):
421 place = OneToOneField(Place, related_name='restaurant')
422
423 ``Place.restaurant`` is a ``ReverseOneToOneDescriptor`` instance.
424 """
425
426 def __init__(self, related):
427 # Following the example above, `related` is an instance of OneToOneRel
428 # which represents the reverse restaurant field (place.restaurant).
429 self.related = related
430
431 @cached_property
432 def RelatedObjectDoesNotExist(self):
433 # The exception isn't created at initialization time for the sake of
434 # consistency with `ForwardManyToOneDescriptor`.
435 return type(
436 "RelatedObjectDoesNotExist",
437 (self.related.related_model.DoesNotExist, AttributeError),
438 {
439 "__module__": self.related.model.__module__,
440 "__qualname__": "%s.%s.RelatedObjectDoesNotExist"
441 % (
442 self.related.model.__qualname__,
443 self.related.name,
444 ),
445 },
446 )
447
448 def is_cached(self, instance):
449 return self.related.is_cached(instance)
450
451 def get_queryset(self, **hints):
452 return self.related.related_model._base_manager.db_manager(hints=hints).all()
453
454 def get_prefetch_queryset(self, instances, queryset=None):
455 warnings.warn(
456 "get_prefetch_queryset() is deprecated. Use get_prefetch_querysets() "
457 "instead.",
458 RemovedInDjango60Warning,
459 stacklevel=2,
460 )
461 if queryset is None:
462 return self.get_prefetch_querysets(instances)
463 return self.get_prefetch_querysets(instances, [queryset])
464
465 def get_prefetch_querysets(self, instances, querysets=None):
466 if querysets and len(querysets) != 1:
467 raise ValueError(
468 "querysets argument of get_prefetch_querysets() should have a length "
469 "of 1."
470 )
471 queryset = querysets[0] if querysets else self.get_queryset()
472 queryset._add_hints(instance=instances[0])
473
474 rel_obj_attr = self.related.field.get_local_related_value
475 instance_attr = self.related.field.get_foreign_related_value
476 instances_dict = {instance_attr(inst): inst for inst in instances}
477 query = {"%s__in" % self.related.field.name: instances}
478 queryset = queryset.filter(**query)
479 # There can be only one object prefetched for each instance so clear
480 # ordering if the query allows it without side effects.
481 queryset.query.clear_ordering()
482
483 # Since we're going to assign directly in the cache,
484 # we must manage the reverse relation cache manually.
485 for rel_obj in queryset:
486 instance = instances_dict[rel_obj_attr(rel_obj)]
487 self.related.field.set_cached_value(rel_obj, instance)
488 return (
489 queryset,
490 rel_obj_attr,
491 instance_attr,
492 True,
493 self.related.cache_name,
494 False,
495 )
496
497 def __get__(self, instance, cls=None):
498 """
499 Get the related instance through the reverse relation.
500
501 With the example above, when getting ``place.restaurant``:
502
503 - ``self`` is the descriptor managing the ``restaurant`` attribute
504 - ``instance`` is the ``place`` instance
505 - ``cls`` is the ``Place`` class (unused)
506
507 Keep in mind that ``Restaurant`` holds the foreign key to ``Place``.
508 """
509 if instance is None:
510 return self
511
512 # The related instance is loaded from the database and then cached
513 # by the field on the model instance state. It can also be pre-cached
514 # by the forward accessor (ForwardManyToOneDescriptor).
515 try:
516 rel_obj = self.related.get_cached_value(instance)
517 except KeyError:
518 if not instance._is_pk_set():
519 rel_obj = None
520 else:
521 filter_args = self.related.field.get_forward_related_filter(instance)
522 try:
523 rel_obj = self.get_queryset(instance=instance).get(**filter_args)
524 except self.related.related_model.DoesNotExist:
525 rel_obj = None
526 else:
527 # Set the forward accessor cache on the related object to
528 # the current instance to avoid an extra SQL query if it's
529 # accessed later on.
530 self.related.field.set_cached_value(rel_obj, instance)
531 self.related.set_cached_value(instance, rel_obj)
532
533 if rel_obj is None:
534 raise self.RelatedObjectDoesNotExist(
535 "%s has no %s."
536 % (instance.__class__.__name__, self.related.accessor_name)
537 )
538 else:
539 return rel_obj
540
541 def __set__(self, instance, value):
542 """
543 Set the related instance through the reverse relation.
544
545 With the example above, when setting ``place.restaurant = restaurant``:
546
547 - ``self`` is the descriptor managing the ``restaurant`` attribute
548 - ``instance`` is the ``place`` instance
549 - ``value`` is the ``restaurant`` instance on the right of the equal sign
550
551 Keep in mind that ``Restaurant`` holds the foreign key to ``Place``.
552 """
553 # The similarity of the code below to the code in
554 # ForwardManyToOneDescriptor is annoying, but there's a bunch
555 # of small differences that would make a common base class convoluted.
556
557 if value is None:
558 # Update the cached related instance (if any) & clear the cache.
559 # Following the example above, this would be the cached
560 # ``restaurant`` instance (if any).
561 rel_obj = self.related.get_cached_value(instance, default=None)
562 if rel_obj is not None:
563 # Remove the ``restaurant`` instance from the ``place``
564 # instance cache.
565 self.related.delete_cached_value(instance)
566 # Set the ``place`` field on the ``restaurant``
567 # instance to None.
568 setattr(rel_obj, self.related.field.name, None)
569 elif not isinstance(value, self.related.related_model):
570 # An object must be an instance of the related class.
571 raise ValueError(
572 'Cannot assign "%r": "%s.%s" must be a "%s" instance.'
573 % (
574 value,
575 instance._meta.object_name,
576 self.related.accessor_name,
577 self.related.related_model._meta.object_name,
578 )
579 )
580 else:
581 if instance._state.db is None:
582 instance._state.db = router.db_for_write(
583 instance.__class__, instance=value
584 )
585 if value._state.db is None:
586 value._state.db = router.db_for_write(
587 value.__class__, instance=instance
588 )
589 if not router.allow_relation(value, instance):
590 raise ValueError(
591 'Cannot assign "%r": the current database router prevents this '
592 "relation." % value
593 )
594
595 related_pk = tuple(
596 getattr(instance, field.attname)
597 for field in self.related.field.foreign_related_fields
598 )
599 # Set the value of the related field to the value of the related
600 # object's related field.
601 for index, field in enumerate(self.related.field.local_related_fields):
602 setattr(value, field.attname, related_pk[index])
603
604 # Set the related instance cache used by __get__ to avoid an SQL query
605 # when accessing the attribute we just set.
606 self.related.set_cached_value(instance, value)
607
608 # Set the forward accessor cache on the related object to the current
609 # instance to avoid an extra SQL query if it's accessed later on.
610 self.related.field.set_cached_value(value, instance)
611
612 def __reduce__(self):
613 # Same purpose as ForwardManyToOneDescriptor.__reduce__().
614 return getattr, (self.related.model, self.related.name)
615
616
617 class ReverseManyToOneDescriptor:
618 """
619 Accessor to the related objects manager on the reverse side of a
620 many-to-one relation.
621
622 In the example::
623
624 class Child(Model):
625 parent = ForeignKey(Parent, related_name='children')
626
627 ``Parent.children`` is a ``ReverseManyToOneDescriptor`` instance.
628
629 Most of the implementation is delegated to a dynamically defined manager
630 class built by ``create_forward_many_to_many_manager()`` defined below.
631 """
632
633 def __init__(self, rel):
634 self.rel = rel
635 self.field = rel.field
636
637 @cached_property
638 def related_manager_cls(self):
639 related_model = self.rel.related_model
640
641 return create_reverse_many_to_one_manager(
642 related_model._default_manager.__class__,
643 self.rel,
644 )
645
646 def __get__(self, instance, cls=None):
647 """
648 Get the related objects through the reverse relation.
649
650 With the example above, when getting ``parent.children``:
651
652 - ``self`` is the descriptor managing the ``children`` attribute
653 - ``instance`` is the ``parent`` instance
654 - ``cls`` is the ``Parent`` class (unused)
655 """
656 if instance is None:
657 return self
658
659 return self.related_manager_cls(instance)
660
661 def _get_set_deprecation_msg_params(self):
662 return (
663 "reverse side of a related set",
664 self.rel.accessor_name,
665 )
666
667 def __set__(self, instance, value):
668 raise TypeError(
669 "Direct assignment to the %s is prohibited. Use %s.set() instead."
670 % self._get_set_deprecation_msg_params(),
671 )
672
673
674 def create_reverse_many_to_one_manager(superclass, rel):
675 """
676 Create a manager for the reverse side of a many-to-one relation.
677
678 This manager subclasses another manager, generally the default manager of
679 the related model, and adds behaviors specific to many-to-one relations.
680 """
681
682 class RelatedManager(superclass, AltersData):
683 def __init__(self, instance):
684 super().__init__()
685
686 self.instance = instance
687 self.model = rel.related_model
688 self.field = rel.field
689
690 self.core_filters = {self.field.name: instance}
691
692 def __call__(self, *, manager):
693 manager = getattr(self.model, manager)
694 manager_class = create_reverse_many_to_one_manager(manager.__class__, rel)
695 return manager_class(self.instance)
696
697 do_not_call_in_templates = True
698
699 def _check_fk_val(self):
700 for field in self.field.foreign_related_fields:
701 if getattr(self.instance, field.attname) is None:
702 raise ValueError(
703 f'"{self.instance!r}" needs to have a value for field '
704 f'"{field.attname}" before this relationship can be used.'
705 )
706
707 def _apply_rel_filters(self, queryset):
708 """
709 Filter the queryset for the instance this manager is bound to.
710 """
711 db = self._db or router.db_for_read(self.model, instance=self.instance)
712 empty_strings_as_null = connections[
713 db
714 ].features.interprets_empty_strings_as_nulls
715 queryset._add_hints(instance=self.instance)
716 if self._db:
717 queryset = queryset.using(self._db)
718 queryset._defer_next_filter = True
719 queryset = queryset.filter(**self.core_filters)
720 for field in self.field.foreign_related_fields:
721 val = getattr(self.instance, field.attname)
722 if val is None or (val == "" and empty_strings_as_null):
723 return queryset.none()
724 if self.field.many_to_one:
725 # Guard against field-like objects such as GenericRelation
726 # that abuse create_reverse_many_to_one_manager() with reverse
727 # one-to-many relationships instead and break known related
728 # objects assignment.
729 try:
730 target_field = self.field.target_field
731 except FieldError:
732 # The relationship has multiple target fields. Use a tuple
733 # for related object id.
734 rel_obj_id = tuple(
735 [
736 getattr(self.instance, target_field.attname)
737 for target_field in self.field.path_infos[-1].target_fields
738 ]
739 )
740 else:
741 rel_obj_id = getattr(self.instance, target_field.attname)
742 queryset._known_related_objects = {
743 self.field: {rel_obj_id: self.instance}
744 }
745 return queryset
746
747 def _remove_prefetched_objects(self):
748 try:
749 self.instance._prefetched_objects_cache.pop(
750 self.field.remote_field.cache_name
751 )
752 except (AttributeError, KeyError):
753 pass # nothing to clear from cache
754
755 def get_queryset(self):
756 # Even if this relation is not to pk, we require still pk value.
757 # The wish is that the instance has been already saved to DB,
758 # although having a pk value isn't a guarantee of that.
759 if not self.instance._is_pk_set():
760 raise ValueError(
761 f"{self.instance.__class__.__name__!r} instance needs to have a "
762 f"primary key value before this relationship can be used."
763 )
764 try:
765 return self.instance._prefetched_objects_cache[
766 self.field.remote_field.cache_name
767 ]
768 except (AttributeError, KeyError):
769 queryset = super().get_queryset()
770 return self._apply_rel_filters(queryset)
771
772 def get_prefetch_queryset(self, instances, queryset=None):
773 warnings.warn(
774 "get_prefetch_queryset() is deprecated. Use get_prefetch_querysets() "
775 "instead.",
776 RemovedInDjango60Warning,
777 stacklevel=2,
778 )
779 if queryset is None:
780 return self.get_prefetch_querysets(instances)
781 return self.get_prefetch_querysets(instances, [queryset])
782
783 def get_prefetch_querysets(self, instances, querysets=None):
784 if querysets and len(querysets) != 1:
785 raise ValueError(
786 "querysets argument of get_prefetch_querysets() should have a "
787 "length of 1."
788 )
789 queryset = querysets[0] if querysets else super().get_queryset()
790 queryset._add_hints(instance=instances[0])
791 queryset = queryset.using(queryset._db or self._db)
792
793 rel_obj_attr = self.field.get_local_related_value
794 instance_attr = self.field.get_foreign_related_value
795 instances_dict = {instance_attr(inst): inst for inst in instances}
796 queryset = _filter_prefetch_queryset(queryset, self.field.name, instances)
797
798 # Since we just bypassed this class' get_queryset(), we must manage
799 # the reverse relation manually.
800 for rel_obj in queryset:
801 if not self.field.is_cached(rel_obj):
802 instance = instances_dict[rel_obj_attr(rel_obj)]
803 self.field.set_cached_value(rel_obj, instance)
804 cache_name = self.field.remote_field.cache_name
805 return queryset, rel_obj_attr, instance_attr, False, cache_name, False
806
807 def add(self, *objs, bulk=True):
808 self._check_fk_val()
809 self._remove_prefetched_objects()
810 db = router.db_for_write(self.model, instance=self.instance)
811
812 def check_and_update_obj(obj):
813 if not isinstance(obj, self.model):
814 raise TypeError(
815 "'%s' instance expected, got %r"
816 % (
817 self.model._meta.object_name,
818 obj,
819 )
820 )
821 setattr(obj, self.field.name, self.instance)
822
823 if bulk:
824 pks = []
825 for obj in objs:
826 check_and_update_obj(obj)
827 if obj._state.adding or obj._state.db != db:
828 raise ValueError(
829 "%r instance isn't saved. Use bulk=False or save "
830 "the object first." % obj
831 )
832 pks.append(obj.pk)
833 self.model._base_manager.using(db).filter(pk__in=pks).update(
834 **{
835 self.field.name: self.instance,
836 }
837 )
838 else:
839 with transaction.atomic(using=db, savepoint=False):
840 for obj in objs:
841 check_and_update_obj(obj)
842 obj.save()
843
844 add.alters_data = True
845
846 async def aadd(self, *objs, bulk=True):
847 return await sync_to_async(self.add)(*objs, bulk=bulk)
848
849 aadd.alters_data = True
850
851 def create(self, **kwargs):
852 self._check_fk_val()
853 self._remove_prefetched_objects()
854 kwargs[self.field.name] = self.instance
855 db = router.db_for_write(self.model, instance=self.instance)
856 return super(RelatedManager, self.db_manager(db)).create(**kwargs)
857
858 create.alters_data = True
859
860 async def acreate(self, **kwargs):
861 return await sync_to_async(self.create)(**kwargs)
862
863 acreate.alters_data = True
864
865 def get_or_create(self, **kwargs):
866 self._check_fk_val()
867 kwargs[self.field.name] = self.instance
868 db = router.db_for_write(self.model, instance=self.instance)
869 return super(RelatedManager, self.db_manager(db)).get_or_create(**kwargs)
870
871 get_or_create.alters_data = True
872
873 async def aget_or_create(self, **kwargs):
874 return await sync_to_async(self.get_or_create)(**kwargs)
875
876 aget_or_create.alters_data = True
877
878 def update_or_create(self, **kwargs):
879 self._check_fk_val()
880 kwargs[self.field.name] = self.instance
881 db = router.db_for_write(self.model, instance=self.instance)
882 return super(RelatedManager, self.db_manager(db)).update_or_create(**kwargs)
883
884 update_or_create.alters_data = True
885
886 async def aupdate_or_create(self, **kwargs):
887 return await sync_to_async(self.update_or_create)(**kwargs)
888
889 aupdate_or_create.alters_data = True
890
891 # remove() and clear() are only provided if the ForeignKey can have a
892 # value of null.
893 if rel.field.null:
894
895 def remove(self, *objs, bulk=True):
896 if not objs:
897 return
898 self._check_fk_val()
899 val = self.field.get_foreign_related_value(self.instance)
900 old_ids = set()
901 for obj in objs:
902 if not isinstance(obj, self.model):
903 raise TypeError(
904 "'%s' instance expected, got %r"
905 % (
906 self.model._meta.object_name,
907 obj,
908 )
909 )
910 # Is obj actually part of this descriptor set?
911 if self.field.get_local_related_value(obj) == val:
912 old_ids.add(obj.pk)
913 else:
914 raise self.field.remote_field.model.DoesNotExist(
915 "%r is not related to %r." % (obj, self.instance)
916 )
917 self._clear(self.filter(pk__in=old_ids), bulk)
918
919 remove.alters_data = True
920
921 async def aremove(self, *objs, bulk=True):
922 return await sync_to_async(self.remove)(*objs, bulk=bulk)
923
924 aremove.alters_data = True
925
926 def clear(self, *, bulk=True):
927 self._check_fk_val()
928 self._clear(self, bulk)
929
930 clear.alters_data = True
931
932 async def aclear(self, *, bulk=True):
933 return await sync_to_async(self.clear)(bulk=bulk)
934
935 aclear.alters_data = True
936
937 def _clear(self, queryset, bulk):
938 self._remove_prefetched_objects()
939 db = router.db_for_write(self.model, instance=self.instance)
940 queryset = queryset.using(db)
941 if bulk:
942 # `QuerySet.update()` is intrinsically atomic.
943 queryset.update(**{self.field.name: None})
944 else:
945 with transaction.atomic(using=db, savepoint=False):
946 for obj in queryset:
947 setattr(obj, self.field.name, None)
948 obj.save(update_fields=[self.field.name])
949
950 _clear.alters_data = True
951
952 def set(self, objs, *, bulk=True, clear=False):
953 self._check_fk_val()
954 # Force evaluation of `objs` in case it's a queryset whose value
955 # could be affected by `manager.clear()`. Refs #19816.
956 objs = tuple(objs)
957
958 if self.field.null:
959 db = router.db_for_write(self.model, instance=self.instance)
960 with transaction.atomic(using=db, savepoint=False):
961 if clear:
962 self.clear(bulk=bulk)
963 self.add(*objs, bulk=bulk)
964 else:
965 old_objs = set(self.using(db).all())
966 new_objs = []
967 for obj in objs:
968 if obj in old_objs:
969 old_objs.remove(obj)
970 else:
971 new_objs.append(obj)
972
973 self.remove(*old_objs, bulk=bulk)
974 self.add(*new_objs, bulk=bulk)
975 else:
976 self.add(*objs, bulk=bulk)
977
978 set.alters_data = True
979
980 async def aset(self, objs, *, bulk=True, clear=False):
981 return await sync_to_async(self.set)(objs=objs, bulk=bulk, clear=clear)
982
983 aset.alters_data = True
984
985 return RelatedManager
986
987
988 class ManyToManyDescriptor(ReverseManyToOneDescriptor):
989 """
990 Accessor to the related objects manager on the forward and reverse sides of
991 a many-to-many relation.
992
993 In the example::
994
995 class Pizza(Model):
996 toppings = ManyToManyField(Topping, related_name='pizzas')
997
998 ``Pizza.toppings`` and ``Topping.pizzas`` are ``ManyToManyDescriptor``
999 instances.
1000
1001 Most of the implementation is delegated to a dynamically defined manager
1002 class built by ``create_forward_many_to_many_manager()`` defined below.
1003 """
1004
1005 def __init__(self, rel, reverse=False):
1006 super().__init__(rel)
1007
1008 self.reverse = reverse
1009
1010 @property
1011 def through(self):
1012 # through is provided so that you have easy access to the through
1013 # model (Book.authors.through) for inlines, etc. This is done as
1014 # a property to ensure that the fully resolved value is returned.
1015 return self.rel.through
1016
1017 @cached_property
1018 def related_manager_cls(self):
1019 related_model = self.rel.related_model if self.reverse else self.rel.model
1020
1021 return create_forward_many_to_many_manager(
1022 related_model._default_manager.__class__,
1023 self.rel,
1024 reverse=self.reverse,
1025 )
1026
1027 def _get_set_deprecation_msg_params(self):
1028 return (
1029 "%s side of a many-to-many set"
1030 % ("reverse" if self.reverse else "forward"),
1031 self.rel.accessor_name if self.reverse else self.field.name,
1032 )
1033
1034
1035 def create_forward_many_to_many_manager(superclass, rel, reverse):
1036 """
1037 Create a manager for the either side of a many-to-many relation.
1038
1039 This manager subclasses another manager, generally the default manager of
1040 the related model, and adds behaviors specific to many-to-many relations.
1041 """
1042
1043 class ManyRelatedManager(superclass, AltersData):
1044 def __init__(self, instance=None):
1045 super().__init__()
1046
1047 self.instance = instance
1048
1049 if not reverse:
1050 self.model = rel.model
1051 self.query_field_name = rel.field.related_query_name()
1052 self.prefetch_cache_name = rel.field.name
1053 self.source_field_name = rel.field.m2m_field_name()
1054 self.target_field_name = rel.field.m2m_reverse_field_name()
1055 self.symmetrical = rel.symmetrical
1056 else:
1057 self.model = rel.related_model
1058 self.query_field_name = rel.field.name
1059 self.prefetch_cache_name = rel.field.related_query_name()
1060 self.source_field_name = rel.field.m2m_reverse_field_name()
1061 self.target_field_name = rel.field.m2m_field_name()
1062 self.symmetrical = False
1063
1064 self.through = rel.through
1065 self.reverse = reverse
1066
1067 self.source_field = self.through._meta.get_field(self.source_field_name)
1068 self.target_field = self.through._meta.get_field(self.target_field_name)
1069
1070 self.core_filters = {}
1071 self.pk_field_names = {}
1072 for lh_field, rh_field in self.source_field.related_fields:
1073 core_filter_key = "%s__%s" % (self.query_field_name, rh_field.name)
1074 self.core_filters[core_filter_key] = getattr(instance, rh_field.attname)
1075 self.pk_field_names[lh_field.name] = rh_field.name
1076
1077 self.related_val = self.source_field.get_foreign_related_value(instance)
1078 if None in self.related_val:
1079 raise ValueError(
1080 '"%r" needs to have a value for field "%s" before '
1081 "this many-to-many relationship can be used."
1082 % (instance, self.pk_field_names[self.source_field_name])
1083 )
1084 # Even if this relation is not to pk, we require still pk value.
1085 # The wish is that the instance has been already saved to DB,
1086 # although having a pk value isn't a guarantee of that.
1087 if not instance._is_pk_set():
1088 raise ValueError(
1089 "%r instance needs to have a primary key value before "
1090 "a many-to-many relationship can be used."
1091 % instance.__class__.__name__
1092 )
1093
1094 def __call__(self, *, manager):
1095 manager = getattr(self.model, manager)
1096 manager_class = create_forward_many_to_many_manager(
1097 manager.__class__, rel, reverse
1098 )
1099 return manager_class(instance=self.instance)
1100
1101 do_not_call_in_templates = True
1102
1103 def _build_remove_filters(self, removed_vals):
1104 filters = Q.create([(self.source_field_name, self.related_val)])
1105 # No need to add a subquery condition if removed_vals is a QuerySet without
1106 # filters.
1107 removed_vals_filters = (
1108 not isinstance(removed_vals, QuerySet) or removed_vals._has_filters()
1109 )
1110 if removed_vals_filters:
1111 filters &= Q.create([(f"{self.target_field_name}__in", removed_vals)])
1112 if self.symmetrical:
1113 symmetrical_filters = Q.create(
1114 [(self.target_field_name, self.related_val)]
1115 )
1116 if removed_vals_filters:
1117 symmetrical_filters &= Q.create(
1118 [(f"{self.source_field_name}__in", removed_vals)]
1119 )
1120 filters |= symmetrical_filters
1121 return filters
1122
1123 def _apply_rel_filters(self, queryset):
1124 """
1125 Filter the queryset for the instance this manager is bound to.
1126 """
1127 queryset._add_hints(instance=self.instance)
1128 if self._db:
1129 queryset = queryset.using(self._db)
1130 queryset._defer_next_filter = True
1131 return queryset._next_is_sticky().filter(**self.core_filters)
1132
1133 def get_prefetch_cache(self):
1134 try:
1135 return self.instance._prefetched_objects_cache[self.prefetch_cache_name]
1136 except (AttributeError, KeyError):
1137 return None
1138
1139 def _remove_prefetched_objects(self):
1140 try:
1141 self.instance._prefetched_objects_cache.pop(self.prefetch_cache_name)
1142 except (AttributeError, KeyError):
1143 pass # nothing to clear from cache
1144
1145 def get_queryset(self):
1146 if (cache := self.get_prefetch_cache()) is not None:
1147 return cache
1148 else:
1149 queryset = super().get_queryset()
1150 return self._apply_rel_filters(queryset)
1151
1152 def get_prefetch_queryset(self, instances, queryset=None):
1153 warnings.warn(
1154 "get_prefetch_queryset() is deprecated. Use get_prefetch_querysets() "
1155 "instead.",
1156 RemovedInDjango60Warning,
1157 stacklevel=2,
1158 )
1159 if queryset is None:
1160 return self.get_prefetch_querysets(instances)
1161 return self.get_prefetch_querysets(instances, [queryset])
1162
1163 def get_prefetch_querysets(self, instances, querysets=None):
1164 if querysets and len(querysets) != 1:
1165 raise ValueError(
1166 "querysets argument of get_prefetch_querysets() should have a "
1167 "length of 1."
1168 )
1169 queryset = querysets[0] if querysets else super().get_queryset()
1170 queryset._add_hints(instance=instances[0])
1171 queryset = queryset.using(queryset._db or self._db)
1172 queryset = _filter_prefetch_queryset(
1173 queryset, self.query_field_name, instances
1174 )
1175
1176 # M2M: need to annotate the query in order to get the primary model
1177 # that the secondary model was actually related to. We know that
1178 # there will already be a join on the join table, so we can just add
1179 # the select.
1180
1181 # For non-autocreated 'through' models, can't assume we are
1182 # dealing with PK values.
1183 fk = self.through._meta.get_field(self.source_field_name)
1184 join_table = fk.model._meta.db_table
1185 connection = connections[queryset.db]
1186 qn = connection.ops.quote_name
1187 queryset = queryset.extra(
1188 select={
1189 "_prefetch_related_val_%s"
1190 % f.attname: "%s.%s"
1191 % (qn(join_table), qn(f.column))
1192 for f in fk.local_related_fields
1193 }
1194 )
1195 return (
1196 queryset,
1197 lambda result: tuple(
1198 f.get_db_prep_value(
1199 getattr(result, f"_prefetch_related_val_{f.attname}"),
1200 connection,
1201 )
1202 for f in fk.local_related_fields
1203 ),
1204 lambda inst: tuple(
1205 f.get_db_prep_value(getattr(inst, f.attname), connection)
1206 for f in fk.foreign_related_fields
1207 ),
1208 False,
1209 self.prefetch_cache_name,
1210 False,
1211 )
1212
1213 @property
1214 def constrained_target(self):
1215 # If the through relation's target field's foreign integrity is
1216 # enforced, the query can be performed solely against the through
1217 # table as the INNER JOIN'ing against target table is unnecessary.
1218 if not self.target_field.db_constraint:
1219 return None
1220 db = router.db_for_read(self.through, instance=self.instance)
1221 if not connections[db].features.supports_foreign_keys:
1222 return None
1223 hints = {"instance": self.instance}
1224 manager = self.through._base_manager.db_manager(db, hints=hints)
1225 filters = {self.source_field_name: self.related_val[0]}
1226 # Nullable target rows must be excluded as well as they would have
1227 # been filtered out from an INNER JOIN.
1228 if self.target_field.null:
1229 filters["%s__isnull" % self.target_field_name] = False
1230 return manager.filter(**filters)
1231
1232 def exists(self):
1233 if (
1234 superclass is Manager
1235 and self.get_prefetch_cache() is None
1236 and (constrained_target := self.constrained_target) is not None
1237 ):
1238 return constrained_target.exists()
1239 else:
1240 return super().exists()
1241
1242 def count(self):
1243 if (
1244 superclass is Manager
1245 and self.get_prefetch_cache() is None
1246 and (constrained_target := self.constrained_target) is not None
1247 ):
1248 return constrained_target.count()
1249 else:
1250 return super().count()
1251
1252 def add(self, *objs, through_defaults=None):
1253 self._remove_prefetched_objects()
1254 db = router.db_for_write(self.through, instance=self.instance)
1255 with transaction.atomic(using=db, savepoint=False):
1256 self._add_items(
1257 self.source_field_name,
1258 self.target_field_name,
1259 *objs,
1260 through_defaults=through_defaults,
1261 )
1262 # If this is a symmetrical m2m relation to self, add the mirror
1263 # entry in the m2m table.
1264 if self.symmetrical:
1265 self._add_items(
1266 self.target_field_name,
1267 self.source_field_name,
1268 *objs,
1269 through_defaults=through_defaults,
1270 )
1271
1272 add.alters_data = True
1273
1274 async def aadd(self, *objs, through_defaults=None):
1275 return await sync_to_async(self.add)(
1276 *objs, through_defaults=through_defaults
1277 )
1278
1279 aadd.alters_data = True
1280
1281 def remove(self, *objs):
1282 self._remove_prefetched_objects()
1283 self._remove_items(self.source_field_name, self.target_field_name, *objs)
1284
1285 remove.alters_data = True
1286
1287 async def aremove(self, *objs):
1288 return await sync_to_async(self.remove)(*objs)
1289
1290 aremove.alters_data = True
1291
1292 def clear(self):
1293 db = router.db_for_write(self.through, instance=self.instance)
1294 with transaction.atomic(using=db, savepoint=False):
1295 signals.m2m_changed.send(
1296 sender=self.through,
1297 action="pre_clear",
1298 instance=self.instance,
1299 reverse=self.reverse,
1300 model=self.model,
1301 pk_set=None,
1302 using=db,
1303 )
1304 self._remove_prefetched_objects()
1305 filters = self._build_remove_filters(super().get_queryset().using(db))
1306 self.through._default_manager.using(db).filter(filters).delete()
1307
1308 signals.m2m_changed.send(
1309 sender=self.through,
1310 action="post_clear",
1311 instance=self.instance,
1312 reverse=self.reverse,
1313 model=self.model,
1314 pk_set=None,
1315 using=db,
1316 )
1317
1318 clear.alters_data = True
1319
1320 async def aclear(self):
1321 return await sync_to_async(self.clear)()
1322
1323 aclear.alters_data = True
1324
1325 def set(self, objs, *, clear=False, through_defaults=None):
1326 # Force evaluation of `objs` in case it's a queryset whose value
1327 # could be affected by `manager.clear()`. Refs #19816.
1328 objs = tuple(objs)
1329
1330 db = router.db_for_write(self.through, instance=self.instance)
1331 with transaction.atomic(using=db, savepoint=False):
1332 if clear:
1333 self.clear()
1334 self.add(*objs, through_defaults=through_defaults)
1335 else:
1336 old_ids = set(
1337 self.using(db).values_list(
1338 self.target_field.target_field.attname, flat=True
1339 )
1340 )
1341
1342 new_objs = []
1343 for obj in objs:
1344 fk_val = (
1345 self.target_field.get_foreign_related_value(obj)[0]
1346 if isinstance(obj, self.model)
1347 else self.target_field.get_prep_value(obj)
1348 )
1349 if fk_val in old_ids:
1350 old_ids.remove(fk_val)
1351 else:
1352 new_objs.append(obj)
1353
1354 self.remove(*old_ids)
1355 self.add(*new_objs, through_defaults=through_defaults)
1356
1357 set.alters_data = True
1358
1359 async def aset(self, objs, *, clear=False, through_defaults=None):
1360 return await sync_to_async(self.set)(
1361 objs=objs, clear=clear, through_defaults=through_defaults
1362 )
1363
1364 aset.alters_data = True
1365
1366 def create(self, *, through_defaults=None, **kwargs):
1367 db = router.db_for_write(self.instance.__class__, instance=self.instance)
1368 new_obj = super(ManyRelatedManager, self.db_manager(db)).create(**kwargs)
1369 self.add(new_obj, through_defaults=through_defaults)
1370 return new_obj
1371
1372 create.alters_data = True
1373
1374 async def acreate(self, *, through_defaults=None, **kwargs):
1375 return await sync_to_async(self.create)(
1376 through_defaults=through_defaults, **kwargs
1377 )
1378
1379 acreate.alters_data = True
1380
1381 def get_or_create(self, *, through_defaults=None, **kwargs):
1382 db = router.db_for_write(self.instance.__class__, instance=self.instance)
1383 obj, created = super(ManyRelatedManager, self.db_manager(db)).get_or_create(
1384 **kwargs
1385 )
1386 # We only need to add() if created because if we got an object back
1387 # from get() then the relationship already exists.
1388 if created:
1389 self.add(obj, through_defaults=through_defaults)
1390 return obj, created
1391
1392 get_or_create.alters_data = True
1393
1394 async def aget_or_create(self, *, through_defaults=None, **kwargs):
1395 return await sync_to_async(self.get_or_create)(
1396 through_defaults=through_defaults, **kwargs
1397 )
1398
1399 aget_or_create.alters_data = True
1400
1401 def update_or_create(self, *, through_defaults=None, **kwargs):
1402 db = router.db_for_write(self.instance.__class__, instance=self.instance)
1403 obj, created = super(
1404 ManyRelatedManager, self.db_manager(db)
1405 ).update_or_create(**kwargs)
1406 # We only need to add() if created because if we got an object back
1407 # from get() then the relationship already exists.
1408 if created:
1409 self.add(obj, through_defaults=through_defaults)
1410 return obj, created
1411
1412 update_or_create.alters_data = True
1413
1414 async def aupdate_or_create(self, *, through_defaults=None, **kwargs):
1415 return await sync_to_async(self.update_or_create)(
1416 through_defaults=through_defaults, **kwargs
1417 )
1418
1419 aupdate_or_create.alters_data = True
1420
1421 def _get_target_ids(self, target_field_name, objs):
1422 """
1423 Return the set of ids of `objs` that the target field references.
1424 """
1425 from django.db.models import Model
1426
1427 target_ids = set()
1428 target_field = self.through._meta.get_field(target_field_name)
1429 for obj in objs:
1430 if isinstance(obj, self.model):
1431 if not router.allow_relation(obj, self.instance):
1432 raise ValueError(
1433 'Cannot add "%r": instance is on database "%s", '
1434 'value is on database "%s"'
1435 % (obj, self.instance._state.db, obj._state.db)
1436 )
1437 target_id = target_field.get_foreign_related_value(obj)[0]
1438 if target_id is None:
1439 raise ValueError(
1440 'Cannot add "%r": the value for field "%s" is None'
1441 % (obj, target_field_name)
1442 )
1443 target_ids.add(target_id)
1444 elif isinstance(obj, Model):
1445 raise TypeError(
1446 "'%s' instance expected, got %r"
1447 % (self.model._meta.object_name, obj)
1448 )
1449 else:
1450 target_ids.add(target_field.get_prep_value(obj))
1451 return target_ids
1452
1453 def _get_missing_target_ids(
1454 self, source_field_name, target_field_name, db, target_ids
1455 ):
1456 """
1457 Return the subset of ids of `objs` that aren't already assigned to
1458 this relationship.
1459 """
1460 vals = (
1461 self.through._default_manager.using(db)
1462 .values_list(target_field_name, flat=True)
1463 .filter(
1464 **{
1465 source_field_name: self.related_val[0],
1466 "%s__in" % target_field_name: target_ids,
1467 }
1468 )
1469 )
1470 return target_ids.difference(vals)
1471
1472 def _get_add_plan(self, db, source_field_name):
1473 """
1474 Return a boolean triple of the way the add should be performed.
1475
1476 The first element is whether or not bulk_create(ignore_conflicts)
1477 can be used, the second whether or not signals must be sent, and
1478 the third element is whether or not the immediate bulk insertion
1479 with conflicts ignored can be performed.
1480 """
1481 # Conflicts can be ignored when the intermediary model is
1482 # auto-created as the only possible collision is on the
1483 # (source_id, target_id) tuple. The same assertion doesn't hold for
1484 # user-defined intermediary models as they could have other fields
1485 # causing conflicts which must be surfaced.
1486 can_ignore_conflicts = (
1487 self.through._meta.auto_created is not False
1488 and connections[db].features.supports_ignore_conflicts
1489 )
1490 # Don't send the signal when inserting duplicate data row
1491 # for symmetrical reverse entries.
1492 must_send_signals = (
1493 self.reverse or source_field_name == self.source_field_name
1494 ) and (signals.m2m_changed.has_listeners(self.through))
1495 # Fast addition through bulk insertion can only be performed
1496 # if no m2m_changed listeners are connected for self.through
1497 # as they require the added set of ids to be provided via
1498 # pk_set.
1499 return (
1500 can_ignore_conflicts,
1501 must_send_signals,
1502 (can_ignore_conflicts and not must_send_signals),
1503 )
1504
1505 def _add_items(
1506 self, source_field_name, target_field_name, *objs, through_defaults=None
1507 ):
1508 # source_field_name: the PK fieldname in join table for the source object
1509 # target_field_name: the PK fieldname in join table for the target object
1510 # *objs - objects to add. Either object instances, or primary keys
1511 # of object instances.
1512 if not objs:
1513 return
1514
1515 through_defaults = dict(resolve_callables(through_defaults or {}))
1516 target_ids = self._get_target_ids(target_field_name, objs)
1517 db = router.db_for_write(self.through, instance=self.instance)
1518 can_ignore_conflicts, must_send_signals, can_fast_add = self._get_add_plan(
1519 db, source_field_name
1520 )
1521 if can_fast_add:
1522 self.through._default_manager.using(db).bulk_create(
1523 [
1524 self.through(
1525 **{
1526 "%s_id" % source_field_name: self.related_val[0],
1527 "%s_id" % target_field_name: target_id,
1528 }
1529 )
1530 for target_id in target_ids
1531 ],
1532 ignore_conflicts=True,
1533 )
1534 return
1535
1536 missing_target_ids = self._get_missing_target_ids(
1537 source_field_name, target_field_name, db, target_ids
1538 )
1539 with transaction.atomic(using=db, savepoint=False):
1540 if must_send_signals:
1541 signals.m2m_changed.send(
1542 sender=self.through,
1543 action="pre_add",
1544 instance=self.instance,
1545 reverse=self.reverse,
1546 model=self.model,
1547 pk_set=missing_target_ids,
1548 using=db,
1549 )
1550 # Add the ones that aren't there already.
1551 self.through._default_manager.using(db).bulk_create(
1552 [
1553 self.through(
1554 **through_defaults,
1555 **{
1556 "%s_id" % source_field_name: self.related_val[0],
1557 "%s_id" % target_field_name: target_id,
1558 },
1559 )
1560 for target_id in missing_target_ids
1561 ],
1562 ignore_conflicts=can_ignore_conflicts,
1563 )
1564
1565 if must_send_signals:
1566 signals.m2m_changed.send(
1567 sender=self.through,
1568 action="post_add",
1569 instance=self.instance,
1570 reverse=self.reverse,
1571 model=self.model,
1572 pk_set=missing_target_ids,
1573 using=db,
1574 )
1575
1576 def _remove_items(self, source_field_name, target_field_name, *objs):
1577 # source_field_name: the PK colname in join table for the source object
1578 # target_field_name: the PK colname in join table for the target object
1579 # *objs - objects to remove. Either object instances, or primary
1580 # keys of object instances.
1581 if not objs:
1582 return
1583
1584 # Check that all the objects are of the right type
1585 old_ids = set()
1586 for obj in objs:
1587 if isinstance(obj, self.model):
1588 fk_val = self.target_field.get_foreign_related_value(obj)[0]
1589 old_ids.add(fk_val)
1590 else:
1591 old_ids.add(obj)
1592
1593 db = router.db_for_write(self.through, instance=self.instance)
1594 with transaction.atomic(using=db, savepoint=False):
1595 # Send a signal to the other end if need be.
1596 signals.m2m_changed.send(
1597 sender=self.through,
1598 action="pre_remove",
1599 instance=self.instance,
1600 reverse=self.reverse,
1601 model=self.model,
1602 pk_set=old_ids,
1603 using=db,
1604 )
1605 target_model_qs = super().get_queryset()
1606 if target_model_qs._has_filters():
1607 old_vals = target_model_qs.using(db).filter(
1608 **{"%s__in" % self.target_field.target_field.attname: old_ids}
1609 )
1610 else:
1611 old_vals = old_ids
1612 filters = self._build_remove_filters(old_vals)
1613 self.through._default_manager.using(db).filter(filters).delete()
1614
1615 signals.m2m_changed.send(
1616 sender=self.through,
1617 action="post_remove",
1618 instance=self.instance,
1619 reverse=self.reverse,
1620 model=self.model,
1621 pk_set=old_ids,
1622 using=db,
1623 )
1624
1625 return ManyRelatedManager