1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495969798991001011021031041051061071081091101111121131141151161171181191201211221231241251261271281291301311321331341351361371381391401411421431441451461471481491501511521531541551561571581591601611621631641651661671681691701711721731741751761771781791801811821831841851861871881891901911921931941951961971981992002012022032042052062072082092102112122132142152162172182192202212222232242252262272282292302312322332342352362372382392402412422432442452462472482492502512522532542552562572582592602612622632642652662672682692702712722732742752762772782792802812822832842852862872882892902912922932942952962972982993003013023033043053063073083093103113123133143153163173183193203213223233243253263273283293303313323333343353363373383393403413423433443453463473483493503513523533543553563573583593603613623633643653663673683693703713723733743753763773783793803813823833843853863873883893903913923933943953963973983994004014024034044054064074084094104114124134144154164174184194204214224234244254264274284294304314324334344354364374384394404414424434444454464474484494504514524534544554564574584594604614624634644654664674684694704714724734744754764774784794804814824834844854864874884894904914924934944954964974984995005015025035045055065075085095105115125135145155165175185195205215225235245255265275285295305315325335345355365375385395405415425435445455465475485495505515525535545555565575585595605615625635645655665675685695705715725735745755765775785795805815825835845855865875885895905915925935945955965975985996006016026036046056066076086096106116126136146156166176186196206216226236246256266276286296306316326336346356366376386396406416426436446456466476486496506516526536546556566576586596606616626636646656666676686696706716726736746756766776786796806816826836846856866876886896906916926936946956966976986997007017027037047057067077087097107117127137147157167177187197207217227237247257267277287297307317327337347357367377387397407417427437447457467477487497507517527537547557567577587597607617627637647657667677687697707717727737747757767777787797807817827837847857867877887897907917927937947957967977987998008018028038048058068078088098108118128138148158168178188198208218228238248258268278288298308318328338348358368378388398408418428438448458468478488498508518528538548558568578588598608618628638648658668678688698708718728738748758768778788798808818828838848858868878888898908918928938948958968978988999009019029039049059069079089099109119129139149159169179189199209219229239249259269279289299309319329339349359369379389399409419429439449459469479489499509519529539549559569579589599609619629639649659669679689699709719729739749759769779789799809819829839849859869879889899909919929939949959969979989991000100110021003100410051006100710081009101010111012101310141015101610171018101910201021102210231024102510261027102810291030103110321033103410351036103710381039104010411042104310441045104610471048104910501051105210531054105510561057105810591060106110621063106410651066106710681069107010711072107310741075107610771078107910801081108210831084108510861087108810891090109110921093109410951096109710981099110011011102110311041105110611071108110911101111111211131114111511161117111811191120112111221123112411251126112711281129113011311132113311341135113611371138113911401141114211431144 |
- """
- Accessors for related objects.
-
- When a field defines a relation between two models, each model class provides
- an attribute to access related instances of the other model class (unless the
- reverse accessor has been disabled with related_name='+').
-
- Accessors are implemented as descriptors in order to customize access and
- assignment. This module defines the descriptor classes.
-
- Forward accessors follow foreign keys. Reverse accessors trace them back. For
- example, with the following models::
-
- class Parent(Model):
- pass
-
- class Child(Model):
- parent = ForeignKey(Parent, related_name='children')
-
- ``child.parent`` is a forward many-to-one relation. ``parent.children`` is a
- reverse many-to-one relation.
-
- There are three types of relations (many-to-one, one-to-one, and many-to-many)
- and two directions (forward and reverse) for a total of six combinations.
-
- 1. Related instance on the forward side of a many-to-one relation:
- ``ForwardManyToOneDescriptor``.
-
- Uniqueness of foreign key values is irrelevant to accessing the related
- instance, making the many-to-one and one-to-one cases identical as far as
- the descriptor is concerned. The constraint is checked upstream (unicity
- validation in forms) or downstream (unique indexes in the database).
-
- 2. Related instance on the forward side of a one-to-one
- relation: ``ForwardOneToOneDescriptor``.
-
- It avoids querying the database when accessing the parent link field in
- a multi-table inheritance scenario.
-
- 3. Related instance on the reverse side of a one-to-one relation:
- ``ReverseOneToOneDescriptor``.
-
- One-to-one relations are asymmetrical, despite the apparent symmetry of the
- name, because they're implemented in the database with a foreign key from
- one table to another. As a consequence ``ReverseOneToOneDescriptor`` is
- slightly different from ``ForwardManyToOneDescriptor``.
-
- 4. Related objects manager for related instances on the reverse side of a
- many-to-one relation: ``ReverseManyToOneDescriptor``.
-
- Unlike the previous two classes, this one provides access to a collection
- of objects. It returns a manager rather than an instance.
-
- 5. Related objects manager for related instances on the forward or reverse
- sides of a many-to-many relation: ``ManyToManyDescriptor``.
-
- Many-to-many relations are symmetrical. The syntax of Django models
- requires declaring them on one side but that's an implementation detail.
- They could be declared on the other side without any change in behavior.
- Therefore the forward and reverse descriptors can be the same.
-
- If you're looking for ``ForwardManyToManyDescriptor`` or
- ``ReverseManyToManyDescriptor``, use ``ManyToManyDescriptor`` instead.
- """
-
- from django.db import connections, router, transaction
- from django.db.models import Q, signals
- from django.db.models.query import QuerySet
- from django.utils.functional import cached_property
-
-
- class ForwardManyToOneDescriptor:
- """
- Accessor to the related object on the forward side of a many-to-one or
- one-to-one (via ForwardOneToOneDescriptor subclass) relation.
-
- In the example::
-
- class Child(Model):
- parent = ForeignKey(Parent, related_name='children')
-
- ``Child.parent`` is a ``ForwardManyToOneDescriptor`` instance.
- """
-
- def __init__(self, field_with_rel):
- self.field = field_with_rel
-
- @cached_property
- def RelatedObjectDoesNotExist(self):
- # The exception can't be created at initialization time since the
- # related model might not be resolved yet; `self.field.model` might
- # still be a string model reference.
- return type(
- 'RelatedObjectDoesNotExist',
- (self.field.remote_field.model.DoesNotExist, AttributeError), {
- '__module__': self.field.model.__module__,
- '__qualname__': '%s.%s.RelatedObjectDoesNotExist' % (
- self.field.model.__qualname__,
- self.field.name,
- ),
- }
- )
-
- def is_cached(self, instance):
- return self.field.is_cached(instance)
-
- def get_queryset(self, **hints):
- return self.field.remote_field.model._base_manager.db_manager(hints=hints).all()
-
- def get_prefetch_queryset(self, instances, queryset=None):
- if queryset is None:
- queryset = self.get_queryset()
- queryset._add_hints(instance=instances[0])
-
- rel_obj_attr = self.field.get_foreign_related_value
- instance_attr = self.field.get_local_related_value
- instances_dict = {instance_attr(inst): inst for inst in instances}
- related_field = self.field.foreign_related_fields[0]
- remote_field = self.field.remote_field
-
- # FIXME: This will need to be revisited when we introduce support for
- # composite fields. In the meantime we take this practical approach to
- # solve a regression on 1.6 when the reverse manager in hidden
- # (related_name ends with a '+'). Refs #21410.
- # The check for len(...) == 1 is a special case that allows the query
- # to be join-less and smaller. Refs #21760.
- if remote_field.is_hidden() or len(self.field.foreign_related_fields) == 1:
- query = {'%s__in' % related_field.name: {instance_attr(inst)[0] for inst in instances}}
- else:
- query = {'%s__in' % self.field.related_query_name(): instances}
- queryset = queryset.filter(**query)
-
- # Since we're going to assign directly in the cache,
- # we must manage the reverse relation cache manually.
- if not remote_field.multiple:
- for rel_obj in queryset:
- instance = instances_dict[rel_obj_attr(rel_obj)]
- remote_field.set_cached_value(rel_obj, instance)
- return queryset, rel_obj_attr, instance_attr, True, self.field.get_cache_name(), False
-
- def get_object(self, instance):
- qs = self.get_queryset(instance=instance)
- # Assuming the database enforces foreign keys, this won't fail.
- return qs.get(self.field.get_reverse_related_filter(instance))
-
- def __get__(self, instance, cls=None):
- """
- Get the related instance through the forward relation.
-
- With the example above, when getting ``child.parent``:
-
- - ``self`` is the descriptor managing the ``parent`` attribute
- - ``instance`` is the ``child`` instance
- - ``cls`` is the ``Child`` class (we don't need it)
- """
- if instance is None:
- return self
-
- # The related instance is loaded from the database and then cached
- # by the field on the model instance state. It can also be pre-cached
- # by the reverse accessor (ReverseOneToOneDescriptor).
- try:
- rel_obj = self.field.get_cached_value(instance)
- except KeyError:
- has_value = None not in self.field.get_local_related_value(instance)
- ancestor_link = instance._meta.get_ancestor_link(self.field.model) if has_value else None
- if ancestor_link and ancestor_link.is_cached(instance):
- # An ancestor link will exist if this field is defined on a
- # multi-table inheritance parent of the instance's class.
- ancestor = ancestor_link.get_cached_value(instance)
- # The value might be cached on an ancestor if the instance
- # originated from walking down the inheritance chain.
- rel_obj = self.field.get_cached_value(ancestor, default=None)
- else:
- rel_obj = None
- if rel_obj is None and has_value:
- rel_obj = self.get_object(instance)
- remote_field = self.field.remote_field
- # If this is a one-to-one relation, set the reverse accessor
- # cache on the related object to the current instance to avoid
- # an extra SQL query if it's accessed later on.
- if not remote_field.multiple:
- remote_field.set_cached_value(rel_obj, instance)
- self.field.set_cached_value(instance, rel_obj)
-
- if rel_obj is None and not self.field.null:
- raise self.RelatedObjectDoesNotExist(
- "%s has no %s." % (self.field.model.__name__, self.field.name)
- )
- else:
- return rel_obj
-
- def __set__(self, instance, value):
- """
- Set the related instance through the forward relation.
-
- With the example above, when setting ``child.parent = parent``:
-
- - ``self`` is the descriptor managing the ``parent`` attribute
- - ``instance`` is the ``child`` instance
- - ``value`` is the ``parent`` instance on the right of the equal sign
- """
- # An object must be an instance of the related class.
- if value is not None and not isinstance(value, self.field.remote_field.model._meta.concrete_model):
- raise ValueError(
- 'Cannot assign "%r": "%s.%s" must be a "%s" instance.' % (
- value,
- instance._meta.object_name,
- self.field.name,
- self.field.remote_field.model._meta.object_name,
- )
- )
- elif value is not None:
- if instance._state.db is None:
- instance._state.db = router.db_for_write(instance.__class__, instance=value)
- if value._state.db is None:
- value._state.db = router.db_for_write(value.__class__, instance=instance)
- if not router.allow_relation(value, instance):
- raise ValueError('Cannot assign "%r": the current database router prevents this relation.' % value)
-
- remote_field = self.field.remote_field
- # If we're setting the value of a OneToOneField to None, we need to clear
- # out the cache on any old related object. Otherwise, deleting the
- # previously-related object will also cause this object to be deleted,
- # which is wrong.
- if value is None:
- # Look up the previously-related object, which may still be available
- # since we've not yet cleared out the related field.
- # Use the cache directly, instead of the accessor; if we haven't
- # populated the cache, then we don't care - we're only accessing
- # the object to invalidate the accessor cache, so there's no
- # need to populate the cache just to expire it again.
- related = self.field.get_cached_value(instance, default=None)
-
- # If we've got an old related object, we need to clear out its
- # cache. This cache also might not exist if the related object
- # hasn't been accessed yet.
- if related is not None:
- remote_field.set_cached_value(related, None)
-
- for lh_field, rh_field in self.field.related_fields:
- setattr(instance, lh_field.attname, None)
-
- # Set the values of the related field.
- else:
- for lh_field, rh_field in self.field.related_fields:
- setattr(instance, lh_field.attname, getattr(value, rh_field.attname))
-
- # Set the related instance cache used by __get__ to avoid an SQL query
- # when accessing the attribute we just set.
- self.field.set_cached_value(instance, value)
-
- # If this is a one-to-one relation, set the reverse accessor cache on
- # the related object to the current instance to avoid an extra SQL
- # query if it's accessed later on.
- if value is not None and not remote_field.multiple:
- remote_field.set_cached_value(value, instance)
-
- def __reduce__(self):
- """
- Pickling should return the instance attached by self.field on the
- model, not a new copy of that descriptor. Use getattr() to retrieve
- the instance directly from the model.
- """
- return getattr, (self.field.model, self.field.name)
-
-
- class ForwardOneToOneDescriptor(ForwardManyToOneDescriptor):
- """
- Accessor to the related object on the forward side of a one-to-one relation.
-
- In the example::
-
- class Restaurant(Model):
- place = OneToOneField(Place, related_name='restaurant')
-
- ``Restaurant.place`` is a ``ForwardOneToOneDescriptor`` instance.
- """
-
- def get_object(self, instance):
- if self.field.remote_field.parent_link:
- deferred = instance.get_deferred_fields()
- # Because it's a parent link, all the data is available in the
- # instance, so populate the parent model with this data.
- rel_model = self.field.remote_field.model
- fields = [field.attname for field in rel_model._meta.concrete_fields]
-
- # If any of the related model's fields are deferred, fallback to
- # fetching all fields from the related model. This avoids a query
- # on the related model for every deferred field.
- if not any(field in fields for field in deferred):
- kwargs = {field: getattr(instance, field) for field in fields}
- obj = rel_model(**kwargs)
- obj._state.adding = instance._state.adding
- obj._state.db = instance._state.db
- return obj
- return super().get_object(instance)
-
- def __set__(self, instance, value):
- super().__set__(instance, value)
- # If the primary key is a link to a parent model and a parent instance
- # is being set, update the value of the inherited pk(s).
- if self.field.primary_key and self.field.remote_field.parent_link:
- opts = instance._meta
- # Inherited primary key fields from this object's base classes.
- inherited_pk_fields = [
- field for field in opts.concrete_fields
- if field.primary_key and field.remote_field
- ]
- for field in inherited_pk_fields:
- rel_model_pk_name = field.remote_field.model._meta.pk.attname
- raw_value = getattr(value, rel_model_pk_name) if value is not None else None
- setattr(instance, rel_model_pk_name, raw_value)
-
-
- class ReverseOneToOneDescriptor:
- """
- Accessor to the related object on the reverse side of a one-to-one
- relation.
-
- In the example::
-
- class Restaurant(Model):
- place = OneToOneField(Place, related_name='restaurant')
-
- ``Place.restaurant`` is a ``ReverseOneToOneDescriptor`` instance.
- """
-
- def __init__(self, related):
- # Following the example above, `related` is an instance of OneToOneRel
- # which represents the reverse restaurant field (place.restaurant).
- self.related = related
-
- @cached_property
- def RelatedObjectDoesNotExist(self):
- # The exception isn't created at initialization time for the sake of
- # consistency with `ForwardManyToOneDescriptor`.
- return type(
- 'RelatedObjectDoesNotExist',
- (self.related.related_model.DoesNotExist, AttributeError), {
- '__module__': self.related.model.__module__,
- '__qualname__': '%s.%s.RelatedObjectDoesNotExist' % (
- self.related.model.__qualname__,
- self.related.name,
- )
- },
- )
-
- def is_cached(self, instance):
- return self.related.is_cached(instance)
-
- def get_queryset(self, **hints):
- return self.related.related_model._base_manager.db_manager(hints=hints).all()
-
- def get_prefetch_queryset(self, instances, queryset=None):
- if queryset is None:
- queryset = self.get_queryset()
- queryset._add_hints(instance=instances[0])
-
- rel_obj_attr = self.related.field.get_local_related_value
- instance_attr = self.related.field.get_foreign_related_value
- instances_dict = {instance_attr(inst): inst for inst in instances}
- query = {'%s__in' % self.related.field.name: instances}
- queryset = queryset.filter(**query)
-
- # Since we're going to assign directly in the cache,
- # we must manage the reverse relation cache manually.
- for rel_obj in queryset:
- instance = instances_dict[rel_obj_attr(rel_obj)]
- self.related.field.set_cached_value(rel_obj, instance)
- return queryset, rel_obj_attr, instance_attr, True, self.related.get_cache_name(), False
-
- def __get__(self, instance, cls=None):
- """
- Get the related instance through the reverse relation.
-
- With the example above, when getting ``place.restaurant``:
-
- - ``self`` is the descriptor managing the ``restaurant`` attribute
- - ``instance`` is the ``place`` instance
- - ``cls`` is the ``Place`` class (unused)
-
- Keep in mind that ``Restaurant`` holds the foreign key to ``Place``.
- """
- if instance is None:
- return self
-
- # The related instance is loaded from the database and then cached
- # by the field on the model instance state. It can also be pre-cached
- # by the forward accessor (ForwardManyToOneDescriptor).
- try:
- rel_obj = self.related.get_cached_value(instance)
- except KeyError:
- related_pk = instance.pk
- if related_pk is None:
- rel_obj = None
- else:
- filter_args = self.related.field.get_forward_related_filter(instance)
- try:
- rel_obj = self.get_queryset(instance=instance).get(**filter_args)
- except self.related.related_model.DoesNotExist:
- rel_obj = None
- else:
- # Set the forward accessor cache on the related object to
- # the current instance to avoid an extra SQL query if it's
- # accessed later on.
- self.related.field.set_cached_value(rel_obj, instance)
- self.related.set_cached_value(instance, rel_obj)
-
- if rel_obj is None:
- raise self.RelatedObjectDoesNotExist(
- "%s has no %s." % (
- instance.__class__.__name__,
- self.related.get_accessor_name()
- )
- )
- else:
- return rel_obj
-
- def __set__(self, instance, value):
- """
- Set the related instance through the reverse relation.
-
- With the example above, when setting ``place.restaurant = restaurant``:
-
- - ``self`` is the descriptor managing the ``restaurant`` attribute
- - ``instance`` is the ``place`` instance
- - ``value`` is the ``restaurant`` instance on the right of the equal sign
-
- Keep in mind that ``Restaurant`` holds the foreign key to ``Place``.
- """
- # The similarity of the code below to the code in
- # ForwardManyToOneDescriptor is annoying, but there's a bunch
- # of small differences that would make a common base class convoluted.
-
- if value is None:
- # Update the cached related instance (if any) & clear the cache.
- # Following the example above, this would be the cached
- # ``restaurant`` instance (if any).
- rel_obj = self.related.get_cached_value(instance, default=None)
- if rel_obj is not None:
- # Remove the ``restaurant`` instance from the ``place``
- # instance cache.
- self.related.delete_cached_value(instance)
- # Set the ``place`` field on the ``restaurant``
- # instance to None.
- setattr(rel_obj, self.related.field.name, None)
- elif not isinstance(value, self.related.related_model):
- # An object must be an instance of the related class.
- raise ValueError(
- 'Cannot assign "%r": "%s.%s" must be a "%s" instance.' % (
- value,
- instance._meta.object_name,
- self.related.get_accessor_name(),
- self.related.related_model._meta.object_name,
- )
- )
- else:
- if instance._state.db is None:
- instance._state.db = router.db_for_write(instance.__class__, instance=value)
- if value._state.db is None:
- value._state.db = router.db_for_write(value.__class__, instance=instance)
- if not router.allow_relation(value, instance):
- raise ValueError('Cannot assign "%r": the current database router prevents this relation.' % value)
-
- related_pk = tuple(getattr(instance, field.attname) for field in self.related.field.foreign_related_fields)
- # Set the value of the related field to the value of the related object's related field
- for index, field in enumerate(self.related.field.local_related_fields):
- setattr(value, field.attname, related_pk[index])
-
- # Set the related instance cache used by __get__ to avoid an SQL query
- # when accessing the attribute we just set.
- self.related.set_cached_value(instance, value)
-
- # Set the forward accessor cache on the related object to the current
- # instance to avoid an extra SQL query if it's accessed later on.
- self.related.field.set_cached_value(value, instance)
-
- def __reduce__(self):
- # Same purpose as ForwardManyToOneDescriptor.__reduce__().
- return getattr, (self.related.model, self.related.name)
-
-
- class ReverseManyToOneDescriptor:
- """
- Accessor to the related objects manager on the reverse side of a
- many-to-one relation.
-
- In the example::
-
- class Child(Model):
- parent = ForeignKey(Parent, related_name='children')
-
- ``Parent.children`` is a ``ReverseManyToOneDescriptor`` instance.
-
- Most of the implementation is delegated to a dynamically defined manager
- class built by ``create_forward_many_to_many_manager()`` defined below.
- """
-
- def __init__(self, rel):
- self.rel = rel
- self.field = rel.field
-
- @cached_property
- def related_manager_cls(self):
- related_model = self.rel.related_model
-
- return create_reverse_many_to_one_manager(
- related_model._default_manager.__class__,
- self.rel,
- )
-
- def __get__(self, instance, cls=None):
- """
- Get the related objects through the reverse relation.
-
- With the example above, when getting ``parent.children``:
-
- - ``self`` is the descriptor managing the ``children`` attribute
- - ``instance`` is the ``parent`` instance
- - ``cls`` is the ``Parent`` class (unused)
- """
- if instance is None:
- return self
-
- return self.related_manager_cls(instance)
-
- def _get_set_deprecation_msg_params(self):
- return (
- 'reverse side of a related set',
- self.rel.get_accessor_name(),
- )
-
- def __set__(self, instance, value):
- raise TypeError(
- 'Direct assignment to the %s is prohibited. Use %s.set() instead.'
- % self._get_set_deprecation_msg_params(),
- )
-
-
- def create_reverse_many_to_one_manager(superclass, rel):
- """
- Create a manager for the reverse side of a many-to-one relation.
-
- This manager subclasses another manager, generally the default manager of
- the related model, and adds behaviors specific to many-to-one relations.
- """
-
- class RelatedManager(superclass):
- def __init__(self, instance):
- super().__init__()
-
- self.instance = instance
- self.model = rel.related_model
- self.field = rel.field
-
- self.core_filters = {self.field.name: instance}
-
- def __call__(self, *, manager):
- manager = getattr(self.model, manager)
- manager_class = create_reverse_many_to_one_manager(manager.__class__, rel)
- return manager_class(self.instance)
- do_not_call_in_templates = True
-
- def _apply_rel_filters(self, queryset):
- """
- Filter the queryset for the instance this manager is bound to.
- """
- db = self._db or router.db_for_read(self.model, instance=self.instance)
- empty_strings_as_null = connections[db].features.interprets_empty_strings_as_nulls
- queryset._add_hints(instance=self.instance)
- if self._db:
- queryset = queryset.using(self._db)
- queryset = queryset.filter(**self.core_filters)
- for field in self.field.foreign_related_fields:
- val = getattr(self.instance, field.attname)
- if val is None or (val == '' and empty_strings_as_null):
- return queryset.none()
- queryset._known_related_objects = {self.field: {self.instance.pk: self.instance}}
- return queryset
-
- def _remove_prefetched_objects(self):
- try:
- self.instance._prefetched_objects_cache.pop(self.field.remote_field.get_cache_name())
- except (AttributeError, KeyError):
- pass # nothing to clear from cache
-
- def get_queryset(self):
- try:
- return self.instance._prefetched_objects_cache[self.field.remote_field.get_cache_name()]
- except (AttributeError, KeyError):
- queryset = super().get_queryset()
- return self._apply_rel_filters(queryset)
-
- def get_prefetch_queryset(self, instances, queryset=None):
- if queryset is None:
- queryset = super().get_queryset()
-
- queryset._add_hints(instance=instances[0])
- queryset = queryset.using(queryset._db or self._db)
-
- rel_obj_attr = self.field.get_local_related_value
- instance_attr = self.field.get_foreign_related_value
- instances_dict = {instance_attr(inst): inst for inst in instances}
- query = {'%s__in' % self.field.name: instances}
- queryset = queryset.filter(**query)
-
- # Since we just bypassed this class' get_queryset(), we must manage
- # the reverse relation manually.
- for rel_obj in queryset:
- instance = instances_dict[rel_obj_attr(rel_obj)]
- setattr(rel_obj, self.field.name, instance)
- cache_name = self.field.remote_field.get_cache_name()
- return queryset, rel_obj_attr, instance_attr, False, cache_name, False
-
- def add(self, *objs, bulk=True):
- self._remove_prefetched_objects()
- objs = list(objs)
- db = router.db_for_write(self.model, instance=self.instance)
-
- def check_and_update_obj(obj):
- if not isinstance(obj, self.model):
- raise TypeError("'%s' instance expected, got %r" % (
- self.model._meta.object_name, obj,
- ))
- setattr(obj, self.field.name, self.instance)
-
- if bulk:
- pks = []
- for obj in objs:
- check_and_update_obj(obj)
- if obj._state.adding or obj._state.db != db:
- raise ValueError(
- "%r instance isn't saved. Use bulk=False or save "
- "the object first." % obj
- )
- pks.append(obj.pk)
- self.model._base_manager.using(db).filter(pk__in=pks).update(**{
- self.field.name: self.instance,
- })
- else:
- with transaction.atomic(using=db, savepoint=False):
- for obj in objs:
- check_and_update_obj(obj)
- obj.save()
- add.alters_data = True
-
- def create(self, **kwargs):
- kwargs[self.field.name] = self.instance
- db = router.db_for_write(self.model, instance=self.instance)
- return super(RelatedManager, self.db_manager(db)).create(**kwargs)
- create.alters_data = True
-
- def get_or_create(self, **kwargs):
- kwargs[self.field.name] = self.instance
- db = router.db_for_write(self.model, instance=self.instance)
- return super(RelatedManager, self.db_manager(db)).get_or_create(**kwargs)
- get_or_create.alters_data = True
-
- def update_or_create(self, **kwargs):
- kwargs[self.field.name] = self.instance
- db = router.db_for_write(self.model, instance=self.instance)
- return super(RelatedManager, self.db_manager(db)).update_or_create(**kwargs)
- update_or_create.alters_data = True
-
- # remove() and clear() are only provided if the ForeignKey can have a value of null.
- if rel.field.null:
- def remove(self, *objs, bulk=True):
- if not objs:
- return
- val = self.field.get_foreign_related_value(self.instance)
- old_ids = set()
- for obj in objs:
- # Is obj actually part of this descriptor set?
- if self.field.get_local_related_value(obj) == val:
- old_ids.add(obj.pk)
- else:
- raise self.field.remote_field.model.DoesNotExist(
- "%r is not related to %r." % (obj, self.instance)
- )
- self._clear(self.filter(pk__in=old_ids), bulk)
- remove.alters_data = True
-
- def clear(self, *, bulk=True):
- self._clear(self, bulk)
- clear.alters_data = True
-
- def _clear(self, queryset, bulk):
- self._remove_prefetched_objects()
- db = router.db_for_write(self.model, instance=self.instance)
- queryset = queryset.using(db)
- if bulk:
- # `QuerySet.update()` is intrinsically atomic.
- queryset.update(**{self.field.name: None})
- else:
- with transaction.atomic(using=db, savepoint=False):
- for obj in queryset:
- setattr(obj, self.field.name, None)
- obj.save(update_fields=[self.field.name])
- _clear.alters_data = True
-
- def set(self, objs, *, bulk=True, clear=False):
- # Force evaluation of `objs` in case it's a queryset whose value
- # could be affected by `manager.clear()`. Refs #19816.
- objs = tuple(objs)
-
- if self.field.null:
- db = router.db_for_write(self.model, instance=self.instance)
- with transaction.atomic(using=db, savepoint=False):
- if clear:
- self.clear()
- self.add(*objs, bulk=bulk)
- else:
- old_objs = set(self.using(db).all())
- new_objs = []
- for obj in objs:
- if obj in old_objs:
- old_objs.remove(obj)
- else:
- new_objs.append(obj)
-
- self.remove(*old_objs, bulk=bulk)
- self.add(*new_objs, bulk=bulk)
- else:
- self.add(*objs, bulk=bulk)
- set.alters_data = True
-
- return RelatedManager
-
-
- class ManyToManyDescriptor(ReverseManyToOneDescriptor):
- """
- Accessor to the related objects manager on the forward and reverse sides of
- a many-to-many relation.
-
- In the example::
-
- class Pizza(Model):
- toppings = ManyToManyField(Topping, related_name='pizzas')
-
- ``Pizza.toppings`` and ``Topping.pizzas`` are ``ManyToManyDescriptor``
- instances.
-
- Most of the implementation is delegated to a dynamically defined manager
- class built by ``create_forward_many_to_many_manager()`` defined below.
- """
-
- def __init__(self, rel, reverse=False):
- super().__init__(rel)
-
- self.reverse = reverse
-
- @property
- def through(self):
- # through is provided so that you have easy access to the through
- # model (Book.authors.through) for inlines, etc. This is done as
- # a property to ensure that the fully resolved value is returned.
- return self.rel.through
-
- @cached_property
- def related_manager_cls(self):
- related_model = self.rel.related_model if self.reverse else self.rel.model
-
- return create_forward_many_to_many_manager(
- related_model._default_manager.__class__,
- self.rel,
- reverse=self.reverse,
- )
-
- def _get_set_deprecation_msg_params(self):
- return (
- '%s side of a many-to-many set' % ('reverse' if self.reverse else 'forward'),
- self.rel.get_accessor_name() if self.reverse else self.field.name,
- )
-
-
- def create_forward_many_to_many_manager(superclass, rel, reverse):
- """
- Create a manager for the either side of a many-to-many relation.
-
- This manager subclasses another manager, generally the default manager of
- the related model, and adds behaviors specific to many-to-many relations.
- """
-
- class ManyRelatedManager(superclass):
- def __init__(self, instance=None):
- super().__init__()
-
- self.instance = instance
-
- if not reverse:
- self.model = rel.model
- self.query_field_name = rel.field.related_query_name()
- self.prefetch_cache_name = rel.field.name
- self.source_field_name = rel.field.m2m_field_name()
- self.target_field_name = rel.field.m2m_reverse_field_name()
- self.symmetrical = rel.symmetrical
- else:
- self.model = rel.related_model
- self.query_field_name = rel.field.name
- self.prefetch_cache_name = rel.field.related_query_name()
- self.source_field_name = rel.field.m2m_reverse_field_name()
- self.target_field_name = rel.field.m2m_field_name()
- self.symmetrical = False
-
- self.through = rel.through
- self.reverse = reverse
-
- self.source_field = self.through._meta.get_field(self.source_field_name)
- self.target_field = self.through._meta.get_field(self.target_field_name)
-
- self.core_filters = {}
- self.pk_field_names = {}
- for lh_field, rh_field in self.source_field.related_fields:
- core_filter_key = '%s__%s' % (self.query_field_name, rh_field.name)
- self.core_filters[core_filter_key] = getattr(instance, rh_field.attname)
- self.pk_field_names[lh_field.name] = rh_field.name
-
- self.related_val = self.source_field.get_foreign_related_value(instance)
- if None in self.related_val:
- raise ValueError('"%r" needs to have a value for field "%s" before '
- 'this many-to-many relationship can be used.' %
- (instance, self.pk_field_names[self.source_field_name]))
- # Even if this relation is not to pk, we require still pk value.
- # The wish is that the instance has been already saved to DB,
- # although having a pk value isn't a guarantee of that.
- if instance.pk is None:
- raise ValueError("%r instance needs to have a primary key value before "
- "a many-to-many relationship can be used." %
- instance.__class__.__name__)
-
- def __call__(self, *, manager):
- manager = getattr(self.model, manager)
- manager_class = create_forward_many_to_many_manager(manager.__class__, rel, reverse)
- return manager_class(instance=self.instance)
- do_not_call_in_templates = True
-
- def _build_remove_filters(self, removed_vals):
- filters = Q(**{self.source_field_name: self.related_val})
- # No need to add a subquery condition if removed_vals is a QuerySet without
- # filters.
- removed_vals_filters = (not isinstance(removed_vals, QuerySet) or
- removed_vals._has_filters())
- if removed_vals_filters:
- filters &= Q(**{'%s__in' % self.target_field_name: removed_vals})
- if self.symmetrical:
- symmetrical_filters = Q(**{self.target_field_name: self.related_val})
- if removed_vals_filters:
- symmetrical_filters &= Q(
- **{'%s__in' % self.source_field_name: removed_vals})
- filters |= symmetrical_filters
- return filters
-
- def _apply_rel_filters(self, queryset):
- """
- Filter the queryset for the instance this manager is bound to.
- """
- queryset._add_hints(instance=self.instance)
- if self._db:
- queryset = queryset.using(self._db)
- return queryset._next_is_sticky().filter(**self.core_filters)
-
- def _remove_prefetched_objects(self):
- try:
- self.instance._prefetched_objects_cache.pop(self.prefetch_cache_name)
- except (AttributeError, KeyError):
- pass # nothing to clear from cache
-
- def get_queryset(self):
- try:
- return self.instance._prefetched_objects_cache[self.prefetch_cache_name]
- except (AttributeError, KeyError):
- queryset = super().get_queryset()
- return self._apply_rel_filters(queryset)
-
- def get_prefetch_queryset(self, instances, queryset=None):
- if queryset is None:
- queryset = super().get_queryset()
-
- queryset._add_hints(instance=instances[0])
- queryset = queryset.using(queryset._db or self._db)
-
- query = {'%s__in' % self.query_field_name: instances}
- queryset = queryset._next_is_sticky().filter(**query)
-
- # M2M: need to annotate the query in order to get the primary model
- # that the secondary model was actually related to. We know that
- # there will already be a join on the join table, so we can just add
- # the select.
-
- # For non-autocreated 'through' models, can't assume we are
- # dealing with PK values.
- fk = self.through._meta.get_field(self.source_field_name)
- join_table = fk.model._meta.db_table
- connection = connections[queryset.db]
- qn = connection.ops.quote_name
- queryset = queryset.extra(select={
- '_prefetch_related_val_%s' % f.attname:
- '%s.%s' % (qn(join_table), qn(f.column)) for f in fk.local_related_fields})
- return (
- queryset,
- lambda result: tuple(
- getattr(result, '_prefetch_related_val_%s' % f.attname)
- for f in fk.local_related_fields
- ),
- lambda inst: tuple(
- f.get_db_prep_value(getattr(inst, f.attname), connection)
- for f in fk.foreign_related_fields
- ),
- False,
- self.prefetch_cache_name,
- False,
- )
-
- def add(self, *objs):
- if not rel.through._meta.auto_created:
- opts = self.through._meta
- raise AttributeError(
- "Cannot use add() on a ManyToManyField which specifies an "
- "intermediary model. Use %s.%s's Manager instead." %
- (opts.app_label, opts.object_name)
- )
- self._remove_prefetched_objects()
- db = router.db_for_write(self.through, instance=self.instance)
- with transaction.atomic(using=db, savepoint=False):
- self._add_items(self.source_field_name, self.target_field_name, *objs)
-
- # If this is a symmetrical m2m relation to self, add the mirror entry in the m2m table
- if self.symmetrical:
- self._add_items(self.target_field_name, self.source_field_name, *objs)
- add.alters_data = True
-
- def remove(self, *objs):
- if not rel.through._meta.auto_created:
- opts = self.through._meta
- raise AttributeError(
- "Cannot use remove() on a ManyToManyField which specifies "
- "an intermediary model. Use %s.%s's Manager instead." %
- (opts.app_label, opts.object_name)
- )
- self._remove_prefetched_objects()
- self._remove_items(self.source_field_name, self.target_field_name, *objs)
- remove.alters_data = True
-
- def clear(self):
- db = router.db_for_write(self.through, instance=self.instance)
- with transaction.atomic(using=db, savepoint=False):
- signals.m2m_changed.send(
- sender=self.through, action="pre_clear",
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=None, using=db,
- )
- self._remove_prefetched_objects()
- filters = self._build_remove_filters(super().get_queryset().using(db))
- self.through._default_manager.using(db).filter(filters).delete()
-
- signals.m2m_changed.send(
- sender=self.through, action="post_clear",
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=None, using=db,
- )
- clear.alters_data = True
-
- def set(self, objs, *, clear=False):
- if not rel.through._meta.auto_created:
- opts = self.through._meta
- raise AttributeError(
- "Cannot set values on a ManyToManyField which specifies an "
- "intermediary model. Use %s.%s's Manager instead." %
- (opts.app_label, opts.object_name)
- )
-
- # Force evaluation of `objs` in case it's a queryset whose value
- # could be affected by `manager.clear()`. Refs #19816.
- objs = tuple(objs)
-
- db = router.db_for_write(self.through, instance=self.instance)
- with transaction.atomic(using=db, savepoint=False):
- if clear:
- self.clear()
- self.add(*objs)
- else:
- old_ids = set(self.using(db).values_list(self.target_field.target_field.attname, flat=True))
-
- new_objs = []
- for obj in objs:
- fk_val = (
- self.target_field.get_foreign_related_value(obj)[0]
- if isinstance(obj, self.model) else obj
- )
- if fk_val in old_ids:
- old_ids.remove(fk_val)
- else:
- new_objs.append(obj)
-
- self.remove(*old_ids)
- self.add(*new_objs)
- set.alters_data = True
-
- def create(self, **kwargs):
- # This check needs to be done here, since we can't later remove this
- # from the method lookup table, as we do with add and remove.
- if not self.through._meta.auto_created:
- opts = self.through._meta
- raise AttributeError(
- "Cannot use create() on a ManyToManyField which specifies "
- "an intermediary model. Use %s.%s's Manager instead." %
- (opts.app_label, opts.object_name)
- )
- db = router.db_for_write(self.instance.__class__, instance=self.instance)
- new_obj = super(ManyRelatedManager, self.db_manager(db)).create(**kwargs)
- self.add(new_obj)
- return new_obj
- create.alters_data = True
-
- def get_or_create(self, **kwargs):
- db = router.db_for_write(self.instance.__class__, instance=self.instance)
- obj, created = super(ManyRelatedManager, self.db_manager(db)).get_or_create(**kwargs)
- # We only need to add() if created because if we got an object back
- # from get() then the relationship already exists.
- if created:
- self.add(obj)
- return obj, created
- get_or_create.alters_data = True
-
- def update_or_create(self, **kwargs):
- db = router.db_for_write(self.instance.__class__, instance=self.instance)
- obj, created = super(ManyRelatedManager, self.db_manager(db)).update_or_create(**kwargs)
- # We only need to add() if created because if we got an object back
- # from get() then the relationship already exists.
- if created:
- self.add(obj)
- return obj, created
- update_or_create.alters_data = True
-
- def _add_items(self, source_field_name, target_field_name, *objs):
- # source_field_name: the PK fieldname in join table for the source object
- # target_field_name: the PK fieldname in join table for the target object
- # *objs - objects to add. Either object instances, or primary keys of object instances.
-
- # If there aren't any objects, there is nothing to do.
- from django.db.models import Model
- if objs:
- new_ids = set()
- for obj in objs:
- if isinstance(obj, self.model):
- if not router.allow_relation(obj, self.instance):
- raise ValueError(
- 'Cannot add "%r": instance is on database "%s", value is on database "%s"' %
- (obj, self.instance._state.db, obj._state.db)
- )
- fk_val = self.through._meta.get_field(
- target_field_name).get_foreign_related_value(obj)[0]
- if fk_val is None:
- raise ValueError(
- 'Cannot add "%r": the value for field "%s" is None' %
- (obj, target_field_name)
- )
- new_ids.add(fk_val)
- elif isinstance(obj, Model):
- raise TypeError(
- "'%s' instance expected, got %r" %
- (self.model._meta.object_name, obj)
- )
- else:
- new_ids.add(obj)
-
- db = router.db_for_write(self.through, instance=self.instance)
- vals = (self.through._default_manager.using(db)
- .values_list(target_field_name, flat=True)
- .filter(**{
- source_field_name: self.related_val[0],
- '%s__in' % target_field_name: new_ids,
- }))
- new_ids.difference_update(vals)
-
- with transaction.atomic(using=db, savepoint=False):
- if self.reverse or source_field_name == self.source_field_name:
- # Don't send the signal when we are inserting the
- # duplicate data row for symmetrical reverse entries.
- signals.m2m_changed.send(
- sender=self.through, action='pre_add',
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=new_ids, using=db,
- )
-
- # Add the ones that aren't there already
- self.through._default_manager.using(db).bulk_create([
- self.through(**{
- '%s_id' % source_field_name: self.related_val[0],
- '%s_id' % target_field_name: obj_id,
- })
- for obj_id in new_ids
- ])
-
- if self.reverse or source_field_name == self.source_field_name:
- # Don't send the signal when we are inserting the
- # duplicate data row for symmetrical reverse entries.
- signals.m2m_changed.send(
- sender=self.through, action='post_add',
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=new_ids, using=db,
- )
-
- def _remove_items(self, source_field_name, target_field_name, *objs):
- # source_field_name: the PK colname in join table for the source object
- # target_field_name: the PK colname in join table for the target object
- # *objs - objects to remove
- if not objs:
- return
-
- # Check that all the objects are of the right type
- old_ids = set()
- for obj in objs:
- if isinstance(obj, self.model):
- fk_val = self.target_field.get_foreign_related_value(obj)[0]
- old_ids.add(fk_val)
- else:
- old_ids.add(obj)
-
- db = router.db_for_write(self.through, instance=self.instance)
- with transaction.atomic(using=db, savepoint=False):
- # Send a signal to the other end if need be.
- signals.m2m_changed.send(
- sender=self.through, action="pre_remove",
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=old_ids, using=db,
- )
- target_model_qs = super().get_queryset()
- if target_model_qs._has_filters():
- old_vals = target_model_qs.using(db).filter(**{
- '%s__in' % self.target_field.target_field.attname: old_ids})
- else:
- old_vals = old_ids
- filters = self._build_remove_filters(old_vals)
- self.through._default_manager.using(db).filter(filters).delete()
-
- signals.m2m_changed.send(
- sender=self.through, action="post_remove",
- instance=self.instance, reverse=self.reverse,
- model=self.model, pk_set=old_ids, using=db,
- )
-
- return ManyRelatedManager
|