related.py 75 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995
  1. import functools
  2. import inspect
  3. import warnings
  4. from functools import partial
  5. from django import forms
  6. from django.apps import apps
  7. from django.conf import SettingsReference, settings
  8. from django.core import checks, exceptions
  9. from django.db import connection, router
  10. from django.db.backends import utils
  11. from django.db.models import Q
  12. from django.db.models.constants import LOOKUP_SEP
  13. from django.db.models.deletion import CASCADE, SET_DEFAULT, SET_NULL
  14. from django.db.models.query_utils import PathInfo
  15. from django.db.models.utils import make_model_tuple
  16. from django.utils.deprecation import RemovedInDjango60Warning
  17. from django.utils.functional import cached_property
  18. from django.utils.translation import gettext_lazy as _
  19. from . import Field
  20. from .mixins import FieldCacheMixin
  21. from .related_descriptors import (
  22. ForeignKeyDeferredAttribute,
  23. ForwardManyToOneDescriptor,
  24. ForwardOneToOneDescriptor,
  25. ManyToManyDescriptor,
  26. ReverseManyToOneDescriptor,
  27. ReverseOneToOneDescriptor,
  28. )
  29. from .related_lookups import (
  30. RelatedExact,
  31. RelatedGreaterThan,
  32. RelatedGreaterThanOrEqual,
  33. RelatedIn,
  34. RelatedIsNull,
  35. RelatedLessThan,
  36. RelatedLessThanOrEqual,
  37. )
  38. from .reverse_related import ForeignObjectRel, ManyToManyRel, ManyToOneRel, OneToOneRel
  39. RECURSIVE_RELATIONSHIP_CONSTANT = "self"
  40. def resolve_relation(scope_model, relation):
  41. """
  42. Transform relation into a model or fully-qualified model string of the form
  43. "app_label.ModelName", relative to scope_model.
  44. The relation argument can be:
  45. * RECURSIVE_RELATIONSHIP_CONSTANT, i.e. the string "self", in which case
  46. the model argument will be returned.
  47. * A bare model name without an app_label, in which case scope_model's
  48. app_label will be prepended.
  49. * An "app_label.ModelName" string.
  50. * A model class, which will be returned unchanged.
  51. """
  52. # Check for recursive relations
  53. if relation == RECURSIVE_RELATIONSHIP_CONSTANT:
  54. relation = scope_model
  55. # Look for an "app.Model" relation
  56. if isinstance(relation, str):
  57. if "." not in relation:
  58. relation = "%s.%s" % (scope_model._meta.app_label, relation)
  59. return relation
  60. def lazy_related_operation(function, model, *related_models, **kwargs):
  61. """
  62. Schedule `function` to be called once `model` and all `related_models`
  63. have been imported and registered with the app registry. `function` will
  64. be called with the newly-loaded model classes as its positional arguments,
  65. plus any optional keyword arguments.
  66. The `model` argument must be a model class. Each subsequent positional
  67. argument is another model, or a reference to another model - see
  68. `resolve_relation()` for the various forms these may take. Any relative
  69. references will be resolved relative to `model`.
  70. This is a convenience wrapper for `Apps.lazy_model_operation` - the app
  71. registry model used is the one found in `model._meta.apps`.
  72. """
  73. models = [model] + [resolve_relation(model, rel) for rel in related_models]
  74. model_keys = (make_model_tuple(m) for m in models)
  75. apps = model._meta.apps
  76. return apps.lazy_model_operation(partial(function, **kwargs), *model_keys)
  77. class RelatedField(FieldCacheMixin, Field):
  78. """Base class that all relational fields inherit from."""
  79. # Field flags
  80. one_to_many = False
  81. one_to_one = False
  82. many_to_many = False
  83. many_to_one = False
  84. def __init__(
  85. self,
  86. related_name=None,
  87. related_query_name=None,
  88. limit_choices_to=None,
  89. **kwargs,
  90. ):
  91. self._related_name = related_name
  92. self._related_query_name = related_query_name
  93. self._limit_choices_to = limit_choices_to
  94. super().__init__(**kwargs)
  95. @cached_property
  96. def related_model(self):
  97. # Can't cache this property until all the models are loaded.
  98. apps.check_models_ready()
  99. return self.remote_field.model
  100. def check(self, **kwargs):
  101. return [
  102. *super().check(**kwargs),
  103. *self._check_related_name_is_valid(),
  104. *self._check_related_query_name_is_valid(),
  105. *self._check_relation_model_exists(),
  106. *self._check_referencing_to_swapped_model(),
  107. *self._check_clashes(),
  108. ]
  109. def _check_related_name_is_valid(self):
  110. import keyword
  111. related_name = self.remote_field.related_name
  112. if related_name is None:
  113. return []
  114. is_valid_id = (
  115. not keyword.iskeyword(related_name) and related_name.isidentifier()
  116. )
  117. if not (is_valid_id or related_name.endswith("+")):
  118. return [
  119. checks.Error(
  120. "The name '%s' is invalid related_name for field %s.%s"
  121. % (
  122. self.remote_field.related_name,
  123. self.model._meta.object_name,
  124. self.name,
  125. ),
  126. hint=(
  127. "Related name must be a valid Python identifier or end with a "
  128. "'+'"
  129. ),
  130. obj=self,
  131. id="fields.E306",
  132. )
  133. ]
  134. return []
  135. def _check_related_query_name_is_valid(self):
  136. if self.remote_field.hidden:
  137. return []
  138. rel_query_name = self.related_query_name()
  139. errors = []
  140. if rel_query_name.endswith("_"):
  141. errors.append(
  142. checks.Error(
  143. "Reverse query name '%s' must not end with an underscore."
  144. % rel_query_name,
  145. hint=(
  146. "Add or change a related_name or related_query_name "
  147. "argument for this field."
  148. ),
  149. obj=self,
  150. id="fields.E308",
  151. )
  152. )
  153. if LOOKUP_SEP in rel_query_name:
  154. errors.append(
  155. checks.Error(
  156. "Reverse query name '%s' must not contain '%s'."
  157. % (rel_query_name, LOOKUP_SEP),
  158. hint=(
  159. "Add or change a related_name or related_query_name "
  160. "argument for this field."
  161. ),
  162. obj=self,
  163. id="fields.E309",
  164. )
  165. )
  166. return errors
  167. def _check_relation_model_exists(self):
  168. rel_is_missing = self.remote_field.model not in self.opts.apps.get_models()
  169. rel_is_string = isinstance(self.remote_field.model, str)
  170. model_name = (
  171. self.remote_field.model
  172. if rel_is_string
  173. else self.remote_field.model._meta.object_name
  174. )
  175. if rel_is_missing and (
  176. rel_is_string or not self.remote_field.model._meta.swapped
  177. ):
  178. return [
  179. checks.Error(
  180. "Field defines a relation with model '%s', which is either "
  181. "not installed, or is abstract." % model_name,
  182. obj=self,
  183. id="fields.E300",
  184. )
  185. ]
  186. return []
  187. def _check_referencing_to_swapped_model(self):
  188. if (
  189. self.remote_field.model not in self.opts.apps.get_models()
  190. and not isinstance(self.remote_field.model, str)
  191. and self.remote_field.model._meta.swapped
  192. ):
  193. return [
  194. checks.Error(
  195. "Field defines a relation with the model '%s', which has "
  196. "been swapped out." % self.remote_field.model._meta.label,
  197. hint="Update the relation to point at 'settings.%s'."
  198. % self.remote_field.model._meta.swappable,
  199. obj=self,
  200. id="fields.E301",
  201. )
  202. ]
  203. return []
  204. def _check_clashes(self):
  205. """Check accessor and reverse query name clashes."""
  206. from django.db.models.base import ModelBase
  207. errors = []
  208. opts = self.model._meta
  209. # f.remote_field.model may be a string instead of a model. Skip if
  210. # model name is not resolved.
  211. if not isinstance(self.remote_field.model, ModelBase):
  212. return []
  213. # Consider that we are checking field `Model.foreign` and the models
  214. # are:
  215. #
  216. # class Target(models.Model):
  217. # model = models.IntegerField()
  218. # model_set = models.IntegerField()
  219. #
  220. # class Model(models.Model):
  221. # foreign = models.ForeignKey(Target)
  222. # m2m = models.ManyToManyField(Target)
  223. # rel_opts.object_name == "Target"
  224. rel_opts = self.remote_field.model._meta
  225. # If the field doesn't install a backward relation on the target model
  226. # (so `is_hidden` returns True), then there are no clashes to check
  227. # and we can skip these fields.
  228. rel_is_hidden = self.remote_field.hidden
  229. rel_name = self.remote_field.accessor_name # i. e. "model_set"
  230. rel_query_name = self.related_query_name() # i. e. "model"
  231. # i.e. "app_label.Model.field".
  232. field_name = "%s.%s" % (opts.label, self.name)
  233. # Check clashes between accessor or reverse query name of `field`
  234. # and any other field name -- i.e. accessor for Model.foreign is
  235. # model_set and it clashes with Target.model_set.
  236. potential_clashes = rel_opts.fields + rel_opts.many_to_many
  237. for clash_field in potential_clashes:
  238. if not rel_is_hidden and clash_field.name == rel_name:
  239. clash_name = f"{rel_opts.label}.{clash_field.name}"
  240. errors.append(
  241. checks.Error(
  242. f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
  243. f"for '{field_name}' clashes with field name "
  244. f"'{clash_name}'.",
  245. hint=(
  246. "Rename field '%s', or add/change a related_name "
  247. "argument to the definition for field '%s'."
  248. )
  249. % (clash_name, field_name),
  250. obj=self,
  251. id="fields.E302",
  252. )
  253. )
  254. if clash_field.name == rel_query_name:
  255. clash_name = f"{rel_opts.label}.{clash_field.name}"
  256. errors.append(
  257. checks.Error(
  258. "Reverse query name for '%s' clashes with field name '%s'."
  259. % (field_name, clash_name),
  260. hint=(
  261. "Rename field '%s', or add/change a related_name "
  262. "argument to the definition for field '%s'."
  263. )
  264. % (clash_name, field_name),
  265. obj=self,
  266. id="fields.E303",
  267. )
  268. )
  269. # Check clashes between accessors/reverse query names of `field` and
  270. # any other field accessor -- i. e. Model.foreign accessor clashes with
  271. # Model.m2m accessor.
  272. potential_clashes = (r for r in rel_opts.related_objects if r.field is not self)
  273. for clash_field in potential_clashes:
  274. if not rel_is_hidden and clash_field.accessor_name == rel_name:
  275. clash_name = (
  276. f"{clash_field.related_model._meta.label}.{clash_field.field.name}"
  277. )
  278. errors.append(
  279. checks.Error(
  280. f"Reverse accessor '{rel_opts.object_name}.{rel_name}' "
  281. f"for '{field_name}' clashes with reverse accessor for "
  282. f"'{clash_name}'.",
  283. hint=(
  284. "Add or change a related_name argument "
  285. "to the definition for '%s' or '%s'."
  286. )
  287. % (field_name, clash_name),
  288. obj=self,
  289. id="fields.E304",
  290. )
  291. )
  292. if clash_field.accessor_name == rel_query_name:
  293. clash_name = (
  294. f"{clash_field.related_model._meta.label}.{clash_field.field.name}"
  295. )
  296. errors.append(
  297. checks.Error(
  298. "Reverse query name for '%s' clashes with reverse query name "
  299. "for '%s'." % (field_name, clash_name),
  300. hint=(
  301. "Add or change a related_name argument "
  302. "to the definition for '%s' or '%s'."
  303. )
  304. % (field_name, clash_name),
  305. obj=self,
  306. id="fields.E305",
  307. )
  308. )
  309. return errors
  310. def db_type(self, connection):
  311. # By default related field will not have a column as it relates to
  312. # columns from another table.
  313. return None
  314. def contribute_to_class(self, cls, name, private_only=False, **kwargs):
  315. super().contribute_to_class(cls, name, private_only=private_only, **kwargs)
  316. self.opts = cls._meta
  317. if not cls._meta.abstract:
  318. if self.remote_field.related_name:
  319. related_name = self.remote_field.related_name
  320. else:
  321. related_name = self.opts.default_related_name
  322. if related_name:
  323. related_name %= {
  324. "class": cls.__name__.lower(),
  325. "model_name": cls._meta.model_name.lower(),
  326. "app_label": cls._meta.app_label.lower(),
  327. }
  328. self.remote_field.related_name = related_name
  329. if self.remote_field.related_query_name:
  330. related_query_name = self.remote_field.related_query_name % {
  331. "class": cls.__name__.lower(),
  332. "app_label": cls._meta.app_label.lower(),
  333. }
  334. self.remote_field.related_query_name = related_query_name
  335. def resolve_related_class(model, related, field):
  336. field.remote_field.model = related
  337. field.do_related_class(related, model)
  338. lazy_related_operation(
  339. resolve_related_class, cls, self.remote_field.model, field=self
  340. )
  341. def deconstruct(self):
  342. name, path, args, kwargs = super().deconstruct()
  343. if self._limit_choices_to:
  344. kwargs["limit_choices_to"] = self._limit_choices_to
  345. if self._related_name is not None:
  346. kwargs["related_name"] = self._related_name
  347. if self._related_query_name is not None:
  348. kwargs["related_query_name"] = self._related_query_name
  349. return name, path, args, kwargs
  350. def get_forward_related_filter(self, obj):
  351. """
  352. Return the keyword arguments that when supplied to
  353. self.model.object.filter(), would select all instances related through
  354. this field to the remote obj. This is used to build the querysets
  355. returned by related descriptors. obj is an instance of
  356. self.related_field.model.
  357. """
  358. return {
  359. "%s__%s" % (self.name, rh_field.name): getattr(obj, rh_field.attname)
  360. for _, rh_field in self.related_fields
  361. }
  362. def get_reverse_related_filter(self, obj):
  363. """
  364. Complement to get_forward_related_filter(). Return the keyword
  365. arguments that when passed to self.related_field.model.object.filter()
  366. select all instances of self.related_field.model related through
  367. this field to obj. obj is an instance of self.model.
  368. """
  369. base_q = Q.create(
  370. [
  371. (rh_field.attname, getattr(obj, lh_field.attname))
  372. for lh_field, rh_field in self.related_fields
  373. ]
  374. )
  375. descriptor_filter = self.get_extra_descriptor_filter(obj)
  376. if isinstance(descriptor_filter, dict):
  377. return base_q & Q(**descriptor_filter)
  378. elif descriptor_filter:
  379. return base_q & descriptor_filter
  380. return base_q
  381. @property
  382. def swappable_setting(self):
  383. """
  384. Get the setting that this is powered from for swapping, or None
  385. if it's not swapped in / marked with swappable=False.
  386. """
  387. if self.swappable:
  388. # Work out string form of "to"
  389. if isinstance(self.remote_field.model, str):
  390. to_string = self.remote_field.model
  391. else:
  392. to_string = self.remote_field.model._meta.label
  393. return apps.get_swappable_settings_name(to_string)
  394. return None
  395. def set_attributes_from_rel(self):
  396. self.name = self.name or (
  397. self.remote_field.model._meta.model_name
  398. + "_"
  399. + self.remote_field.model._meta.pk.name
  400. )
  401. if self.verbose_name is None:
  402. self.verbose_name = self.remote_field.model._meta.verbose_name
  403. self.remote_field.set_field_name()
  404. def do_related_class(self, other, cls):
  405. self.set_attributes_from_rel()
  406. self.contribute_to_related_class(other, self.remote_field)
  407. def get_limit_choices_to(self):
  408. """
  409. Return ``limit_choices_to`` for this model field.
  410. If it is a callable, it will be invoked and the result will be
  411. returned.
  412. """
  413. if callable(self.remote_field.limit_choices_to):
  414. return self.remote_field.limit_choices_to()
  415. return self.remote_field.limit_choices_to
  416. def formfield(self, **kwargs):
  417. """
  418. Pass ``limit_choices_to`` to the field being constructed.
  419. Only passes it if there is a type that supports related fields.
  420. This is a similar strategy used to pass the ``queryset`` to the field
  421. being constructed.
  422. """
  423. defaults = {}
  424. if hasattr(self.remote_field, "get_related_field"):
  425. # If this is a callable, do not invoke it here. Just pass
  426. # it in the defaults for when the form class will later be
  427. # instantiated.
  428. limit_choices_to = self.remote_field.limit_choices_to
  429. defaults.update(
  430. {
  431. "limit_choices_to": limit_choices_to,
  432. }
  433. )
  434. defaults.update(kwargs)
  435. return super().formfield(**defaults)
  436. def related_query_name(self):
  437. """
  438. Define the name that can be used to identify this related object in a
  439. table-spanning query.
  440. """
  441. return (
  442. self.remote_field.related_query_name
  443. or self.remote_field.related_name
  444. or self.opts.model_name
  445. )
  446. @property
  447. def target_field(self):
  448. """
  449. When filtering against this relation, return the field on the remote
  450. model against which the filtering should happen.
  451. """
  452. target_fields = self.path_infos[-1].target_fields
  453. if len(target_fields) > 1:
  454. raise exceptions.FieldError(
  455. "The relation has multiple target fields, but only single target field "
  456. "was asked for"
  457. )
  458. return target_fields[0]
  459. @cached_property
  460. def cache_name(self):
  461. return self.name
  462. class ForeignObject(RelatedField):
  463. """
  464. Abstraction of the ForeignKey relation to support multi-column relations.
  465. """
  466. # Field flags
  467. many_to_many = False
  468. many_to_one = True
  469. one_to_many = False
  470. one_to_one = False
  471. requires_unique_target = True
  472. related_accessor_class = ReverseManyToOneDescriptor
  473. forward_related_accessor_class = ForwardManyToOneDescriptor
  474. rel_class = ForeignObjectRel
  475. def __init__(
  476. self,
  477. to,
  478. on_delete,
  479. from_fields,
  480. to_fields,
  481. rel=None,
  482. related_name=None,
  483. related_query_name=None,
  484. limit_choices_to=None,
  485. parent_link=False,
  486. swappable=True,
  487. **kwargs,
  488. ):
  489. if rel is None:
  490. rel = self.rel_class(
  491. self,
  492. to,
  493. related_name=related_name,
  494. related_query_name=related_query_name,
  495. limit_choices_to=limit_choices_to,
  496. parent_link=parent_link,
  497. on_delete=on_delete,
  498. )
  499. super().__init__(
  500. rel=rel,
  501. related_name=related_name,
  502. related_query_name=related_query_name,
  503. limit_choices_to=limit_choices_to,
  504. **kwargs,
  505. )
  506. self.from_fields = from_fields
  507. self.to_fields = to_fields
  508. self.swappable = swappable
  509. def __copy__(self):
  510. obj = super().__copy__()
  511. # Remove any cached PathInfo values.
  512. obj.__dict__.pop("path_infos", None)
  513. obj.__dict__.pop("reverse_path_infos", None)
  514. return obj
  515. def check(self, **kwargs):
  516. return [
  517. *super().check(**kwargs),
  518. *self._check_to_fields_exist(),
  519. *self._check_unique_target(),
  520. ]
  521. def _check_to_fields_exist(self):
  522. # Skip nonexistent models.
  523. if isinstance(self.remote_field.model, str):
  524. return []
  525. errors = []
  526. for to_field in self.to_fields:
  527. if to_field:
  528. try:
  529. self.remote_field.model._meta.get_field(to_field)
  530. except exceptions.FieldDoesNotExist:
  531. errors.append(
  532. checks.Error(
  533. "The to_field '%s' doesn't exist on the related "
  534. "model '%s'."
  535. % (to_field, self.remote_field.model._meta.label),
  536. obj=self,
  537. id="fields.E312",
  538. )
  539. )
  540. return errors
  541. def _check_unique_target(self):
  542. rel_is_string = isinstance(self.remote_field.model, str)
  543. if rel_is_string or not self.requires_unique_target:
  544. return []
  545. try:
  546. self.foreign_related_fields
  547. except exceptions.FieldDoesNotExist:
  548. return []
  549. if not self.foreign_related_fields:
  550. return []
  551. has_unique_constraint = any(
  552. rel_field.unique for rel_field in self.foreign_related_fields
  553. )
  554. if not has_unique_constraint:
  555. foreign_fields = {f.name for f in self.foreign_related_fields}
  556. remote_opts = self.remote_field.model._meta
  557. has_unique_constraint = any(
  558. frozenset(ut) <= foreign_fields for ut in remote_opts.unique_together
  559. ) or any(
  560. frozenset(uc.fields) <= foreign_fields
  561. for uc in remote_opts.total_unique_constraints
  562. )
  563. if not has_unique_constraint:
  564. if len(self.foreign_related_fields) > 1:
  565. field_combination = ", ".join(
  566. f"'{rel_field.name}'" for rel_field in self.foreign_related_fields
  567. )
  568. model_name = self.remote_field.model.__name__
  569. return [
  570. checks.Error(
  571. f"No subset of the fields {field_combination} on model "
  572. f"'{model_name}' is unique.",
  573. hint=(
  574. "Mark a single field as unique=True or add a set of "
  575. "fields to a unique constraint (via unique_together "
  576. "or a UniqueConstraint (without condition) in the "
  577. "model Meta.constraints)."
  578. ),
  579. obj=self,
  580. id="fields.E310",
  581. )
  582. ]
  583. else:
  584. field_name = self.foreign_related_fields[0].name
  585. model_name = self.remote_field.model.__name__
  586. return [
  587. checks.Error(
  588. f"'{model_name}.{field_name}' must be unique because it is "
  589. "referenced by a foreign key.",
  590. hint=(
  591. "Add unique=True to this field or add a "
  592. "UniqueConstraint (without condition) in the model "
  593. "Meta.constraints."
  594. ),
  595. obj=self,
  596. id="fields.E311",
  597. )
  598. ]
  599. return []
  600. def deconstruct(self):
  601. name, path, args, kwargs = super().deconstruct()
  602. kwargs["on_delete"] = self.remote_field.on_delete
  603. kwargs["from_fields"] = self.from_fields
  604. kwargs["to_fields"] = self.to_fields
  605. if self.remote_field.parent_link:
  606. kwargs["parent_link"] = self.remote_field.parent_link
  607. if isinstance(self.remote_field.model, str):
  608. if "." in self.remote_field.model:
  609. app_label, model_name = self.remote_field.model.split(".")
  610. kwargs["to"] = "%s.%s" % (app_label, model_name.lower())
  611. else:
  612. kwargs["to"] = self.remote_field.model.lower()
  613. else:
  614. kwargs["to"] = self.remote_field.model._meta.label_lower
  615. # If swappable is True, then see if we're actually pointing to the target
  616. # of a swap.
  617. swappable_setting = self.swappable_setting
  618. if swappable_setting is not None:
  619. # If it's already a settings reference, error
  620. if hasattr(kwargs["to"], "setting_name"):
  621. if kwargs["to"].setting_name != swappable_setting:
  622. raise ValueError(
  623. "Cannot deconstruct a ForeignKey pointing to a model "
  624. "that is swapped in place of more than one model (%s and %s)"
  625. % (kwargs["to"].setting_name, swappable_setting)
  626. )
  627. # Set it
  628. kwargs["to"] = SettingsReference(
  629. kwargs["to"],
  630. swappable_setting,
  631. )
  632. return name, path, args, kwargs
  633. def resolve_related_fields(self):
  634. if not self.from_fields or len(self.from_fields) != len(self.to_fields):
  635. raise ValueError(
  636. "Foreign Object from and to fields must be the same non-zero length"
  637. )
  638. if isinstance(self.remote_field.model, str):
  639. raise ValueError(
  640. "Related model %r cannot be resolved" % self.remote_field.model
  641. )
  642. related_fields = []
  643. for from_field_name, to_field_name in zip(self.from_fields, self.to_fields):
  644. from_field = (
  645. self
  646. if from_field_name == RECURSIVE_RELATIONSHIP_CONSTANT
  647. else self.opts.get_field(from_field_name)
  648. )
  649. to_field = (
  650. self.remote_field.model._meta.pk
  651. if to_field_name is None
  652. else self.remote_field.model._meta.get_field(to_field_name)
  653. )
  654. related_fields.append((from_field, to_field))
  655. return related_fields
  656. @cached_property
  657. def related_fields(self):
  658. return self.resolve_related_fields()
  659. @cached_property
  660. def reverse_related_fields(self):
  661. return [(rhs_field, lhs_field) for lhs_field, rhs_field in self.related_fields]
  662. @cached_property
  663. def local_related_fields(self):
  664. return tuple(lhs_field for lhs_field, rhs_field in self.related_fields)
  665. @cached_property
  666. def foreign_related_fields(self):
  667. return tuple(
  668. rhs_field for lhs_field, rhs_field in self.related_fields if rhs_field
  669. )
  670. def get_local_related_value(self, instance):
  671. return self.get_instance_value_for_fields(instance, self.local_related_fields)
  672. def get_foreign_related_value(self, instance):
  673. return self.get_instance_value_for_fields(instance, self.foreign_related_fields)
  674. @staticmethod
  675. def get_instance_value_for_fields(instance, fields):
  676. ret = []
  677. opts = instance._meta
  678. for field in fields:
  679. # Gotcha: in some cases (like fixture loading) a model can have
  680. # different values in parent_ptr_id and parent's id. So, use
  681. # instance.pk (that is, parent_ptr_id) when asked for instance.id.
  682. if field.primary_key:
  683. possible_parent_link = opts.get_ancestor_link(field.model)
  684. if (
  685. not possible_parent_link
  686. or possible_parent_link.primary_key
  687. or possible_parent_link.model._meta.abstract
  688. ):
  689. ret.append(instance.pk)
  690. continue
  691. ret.append(getattr(instance, field.attname))
  692. return tuple(ret)
  693. def get_attname_column(self):
  694. attname, column = super().get_attname_column()
  695. return attname, None
  696. def get_joining_columns(self, reverse_join=False):
  697. warnings.warn(
  698. "ForeignObject.get_joining_columns() is deprecated. Use "
  699. "get_joining_fields() instead.",
  700. RemovedInDjango60Warning,
  701. )
  702. source = self.reverse_related_fields if reverse_join else self.related_fields
  703. return tuple(
  704. (lhs_field.column, rhs_field.column) for lhs_field, rhs_field in source
  705. )
  706. def get_reverse_joining_columns(self):
  707. warnings.warn(
  708. "ForeignObject.get_reverse_joining_columns() is deprecated. Use "
  709. "get_reverse_joining_fields() instead.",
  710. RemovedInDjango60Warning,
  711. )
  712. return self.get_joining_columns(reverse_join=True)
  713. def get_joining_fields(self, reverse_join=False):
  714. return tuple(
  715. self.reverse_related_fields if reverse_join else self.related_fields
  716. )
  717. def get_reverse_joining_fields(self):
  718. return self.get_joining_fields(reverse_join=True)
  719. def get_extra_descriptor_filter(self, instance):
  720. """
  721. Return an extra filter condition for related object fetching when
  722. user does 'instance.fieldname', that is the extra filter is used in
  723. the descriptor of the field.
  724. The filter should be either a dict usable in .filter(**kwargs) call or
  725. a Q-object. The condition will be ANDed together with the relation's
  726. joining columns.
  727. A parallel method is get_extra_restriction() which is used in
  728. JOIN and subquery conditions.
  729. """
  730. return {}
  731. def get_extra_restriction(self, alias, related_alias):
  732. """
  733. Return a pair condition used for joining and subquery pushdown. The
  734. condition is something that responds to as_sql(compiler, connection)
  735. method.
  736. Note that currently referring both the 'alias' and 'related_alias'
  737. will not work in some conditions, like subquery pushdown.
  738. A parallel method is get_extra_descriptor_filter() which is used in
  739. instance.fieldname related object fetching.
  740. """
  741. return None
  742. def get_path_info(self, filtered_relation=None):
  743. """Get path from this field to the related model."""
  744. opts = self.remote_field.model._meta
  745. from_opts = self.model._meta
  746. return [
  747. PathInfo(
  748. from_opts=from_opts,
  749. to_opts=opts,
  750. target_fields=self.foreign_related_fields,
  751. join_field=self,
  752. m2m=False,
  753. direct=True,
  754. filtered_relation=filtered_relation,
  755. )
  756. ]
  757. @cached_property
  758. def path_infos(self):
  759. return self.get_path_info()
  760. def get_reverse_path_info(self, filtered_relation=None):
  761. """Get path from the related model to this field's model."""
  762. opts = self.model._meta
  763. from_opts = self.remote_field.model._meta
  764. return [
  765. PathInfo(
  766. from_opts=from_opts,
  767. to_opts=opts,
  768. target_fields=(opts.pk,),
  769. join_field=self.remote_field,
  770. m2m=not self.unique,
  771. direct=False,
  772. filtered_relation=filtered_relation,
  773. )
  774. ]
  775. @cached_property
  776. def reverse_path_infos(self):
  777. return self.get_reverse_path_info()
  778. @classmethod
  779. @functools.cache
  780. def get_class_lookups(cls):
  781. bases = inspect.getmro(cls)
  782. bases = bases[: bases.index(ForeignObject) + 1]
  783. class_lookups = [parent.__dict__.get("class_lookups", {}) for parent in bases]
  784. return cls.merge_dicts(class_lookups)
  785. def contribute_to_class(self, cls, name, private_only=False, **kwargs):
  786. super().contribute_to_class(cls, name, private_only=private_only, **kwargs)
  787. setattr(cls, self.name, self.forward_related_accessor_class(self))
  788. def contribute_to_related_class(self, cls, related):
  789. # Internal FK's - i.e., those with a related name ending with '+' -
  790. # and swapped models don't get a related descriptor.
  791. if not self.remote_field.hidden and not related.related_model._meta.swapped:
  792. setattr(
  793. cls._meta.concrete_model,
  794. related.accessor_name,
  795. self.related_accessor_class(related),
  796. )
  797. # While 'limit_choices_to' might be a callable, simply pass
  798. # it along for later - this is too early because it's still
  799. # model load time.
  800. if self.remote_field.limit_choices_to:
  801. cls._meta.related_fkey_lookups.append(
  802. self.remote_field.limit_choices_to
  803. )
  804. ForeignObject.register_lookup(RelatedIn)
  805. ForeignObject.register_lookup(RelatedExact)
  806. ForeignObject.register_lookup(RelatedLessThan)
  807. ForeignObject.register_lookup(RelatedGreaterThan)
  808. ForeignObject.register_lookup(RelatedGreaterThanOrEqual)
  809. ForeignObject.register_lookup(RelatedLessThanOrEqual)
  810. ForeignObject.register_lookup(RelatedIsNull)
  811. class ForeignKey(ForeignObject):
  812. """
  813. Provide a many-to-one relation by adding a column to the local model
  814. to hold the remote value.
  815. By default ForeignKey will target the pk of the remote model but this
  816. behavior can be changed by using the ``to_field`` argument.
  817. """
  818. descriptor_class = ForeignKeyDeferredAttribute
  819. # Field flags
  820. many_to_many = False
  821. many_to_one = True
  822. one_to_many = False
  823. one_to_one = False
  824. rel_class = ManyToOneRel
  825. empty_strings_allowed = False
  826. default_error_messages = {
  827. "invalid": _("%(model)s instance with %(field)s %(value)r does not exist.")
  828. }
  829. description = _("Foreign Key (type determined by related field)")
  830. def __init__(
  831. self,
  832. to,
  833. on_delete,
  834. related_name=None,
  835. related_query_name=None,
  836. limit_choices_to=None,
  837. parent_link=False,
  838. to_field=None,
  839. db_constraint=True,
  840. **kwargs,
  841. ):
  842. try:
  843. to._meta.model_name
  844. except AttributeError:
  845. if not isinstance(to, str):
  846. raise TypeError(
  847. "%s(%r) is invalid. First parameter to ForeignKey must be "
  848. "either a model, a model name, or the string %r"
  849. % (
  850. self.__class__.__name__,
  851. to,
  852. RECURSIVE_RELATIONSHIP_CONSTANT,
  853. )
  854. )
  855. else:
  856. # For backwards compatibility purposes, we need to *try* and set
  857. # the to_field during FK construction. It won't be guaranteed to
  858. # be correct until contribute_to_class is called. Refs #12190.
  859. to_field = to_field or (to._meta.pk and to._meta.pk.name)
  860. if not callable(on_delete):
  861. raise TypeError("on_delete must be callable.")
  862. kwargs["rel"] = self.rel_class(
  863. self,
  864. to,
  865. to_field,
  866. related_name=related_name,
  867. related_query_name=related_query_name,
  868. limit_choices_to=limit_choices_to,
  869. parent_link=parent_link,
  870. on_delete=on_delete,
  871. )
  872. kwargs.setdefault("db_index", True)
  873. super().__init__(
  874. to,
  875. on_delete,
  876. related_name=related_name,
  877. related_query_name=related_query_name,
  878. limit_choices_to=limit_choices_to,
  879. from_fields=[RECURSIVE_RELATIONSHIP_CONSTANT],
  880. to_fields=[to_field],
  881. **kwargs,
  882. )
  883. self.db_constraint = db_constraint
  884. def __class_getitem__(cls, *args, **kwargs):
  885. return cls
  886. def check(self, **kwargs):
  887. return [
  888. *super().check(**kwargs),
  889. *self._check_on_delete(),
  890. *self._check_unique(),
  891. ]
  892. def _check_on_delete(self):
  893. on_delete = getattr(self.remote_field, "on_delete", None)
  894. if on_delete == SET_NULL and not self.null:
  895. return [
  896. checks.Error(
  897. "Field specifies on_delete=SET_NULL, but cannot be null.",
  898. hint=(
  899. "Set null=True argument on the field, or change the on_delete "
  900. "rule."
  901. ),
  902. obj=self,
  903. id="fields.E320",
  904. )
  905. ]
  906. elif on_delete == SET_DEFAULT and not self.has_default():
  907. return [
  908. checks.Error(
  909. "Field specifies on_delete=SET_DEFAULT, but has no default value.",
  910. hint="Set a default value, or change the on_delete rule.",
  911. obj=self,
  912. id="fields.E321",
  913. )
  914. ]
  915. else:
  916. return []
  917. def _check_unique(self, **kwargs):
  918. return (
  919. [
  920. checks.Warning(
  921. "Setting unique=True on a ForeignKey has the same effect as using "
  922. "a OneToOneField.",
  923. hint=(
  924. "ForeignKey(unique=True) is usually better served by a "
  925. "OneToOneField."
  926. ),
  927. obj=self,
  928. id="fields.W342",
  929. )
  930. ]
  931. if self.unique
  932. else []
  933. )
  934. def deconstruct(self):
  935. name, path, args, kwargs = super().deconstruct()
  936. del kwargs["to_fields"]
  937. del kwargs["from_fields"]
  938. # Handle the simpler arguments
  939. if self.db_index:
  940. del kwargs["db_index"]
  941. else:
  942. kwargs["db_index"] = False
  943. if self.db_constraint is not True:
  944. kwargs["db_constraint"] = self.db_constraint
  945. # Rel needs more work.
  946. to_meta = getattr(self.remote_field.model, "_meta", None)
  947. if self.remote_field.field_name and (
  948. not to_meta
  949. or (to_meta.pk and self.remote_field.field_name != to_meta.pk.name)
  950. ):
  951. kwargs["to_field"] = self.remote_field.field_name
  952. return name, path, args, kwargs
  953. def to_python(self, value):
  954. return self.target_field.to_python(value)
  955. @property
  956. def target_field(self):
  957. return self.foreign_related_fields[0]
  958. def validate(self, value, model_instance):
  959. if self.remote_field.parent_link:
  960. return
  961. super().validate(value, model_instance)
  962. if value is None:
  963. return
  964. using = router.db_for_read(self.remote_field.model, instance=model_instance)
  965. qs = self.remote_field.model._base_manager.using(using).filter(
  966. **{self.remote_field.field_name: value}
  967. )
  968. qs = qs.complex_filter(self.get_limit_choices_to())
  969. if not qs.exists():
  970. raise exceptions.ValidationError(
  971. self.error_messages["invalid"],
  972. code="invalid",
  973. params={
  974. "model": self.remote_field.model._meta.verbose_name,
  975. "pk": value,
  976. "field": self.remote_field.field_name,
  977. "value": value,
  978. }, # 'pk' is included for backwards compatibility
  979. )
  980. def resolve_related_fields(self):
  981. related_fields = super().resolve_related_fields()
  982. for from_field, to_field in related_fields:
  983. if (
  984. to_field
  985. and to_field.model != self.remote_field.model._meta.concrete_model
  986. ):
  987. raise exceptions.FieldError(
  988. "'%s.%s' refers to field '%s' which is not local to model "
  989. "'%s'."
  990. % (
  991. self.model._meta.label,
  992. self.name,
  993. to_field.name,
  994. self.remote_field.model._meta.concrete_model._meta.label,
  995. )
  996. )
  997. return related_fields
  998. def get_attname(self):
  999. return "%s_id" % self.name
  1000. def get_attname_column(self):
  1001. attname = self.get_attname()
  1002. column = self.db_column or attname
  1003. return attname, column
  1004. def get_default(self):
  1005. """Return the to_field if the default value is an object."""
  1006. field_default = super().get_default()
  1007. if isinstance(field_default, self.remote_field.model):
  1008. return getattr(field_default, self.target_field.attname)
  1009. return field_default
  1010. def get_db_prep_save(self, value, connection):
  1011. if value is None or (
  1012. value == ""
  1013. and (
  1014. not self.target_field.empty_strings_allowed
  1015. or connection.features.interprets_empty_strings_as_nulls
  1016. )
  1017. ):
  1018. return None
  1019. else:
  1020. return self.target_field.get_db_prep_save(value, connection=connection)
  1021. def get_db_prep_value(self, value, connection, prepared=False):
  1022. return self.target_field.get_db_prep_value(value, connection, prepared)
  1023. def get_prep_value(self, value):
  1024. return self.target_field.get_prep_value(value)
  1025. def contribute_to_related_class(self, cls, related):
  1026. super().contribute_to_related_class(cls, related)
  1027. if self.remote_field.field_name is None:
  1028. self.remote_field.field_name = cls._meta.pk.name
  1029. def formfield(self, *, using=None, **kwargs):
  1030. if isinstance(self.remote_field.model, str):
  1031. raise ValueError(
  1032. "Cannot create form field for %r yet, because "
  1033. "its related model %r has not been loaded yet"
  1034. % (self.name, self.remote_field.model)
  1035. )
  1036. return super().formfield(
  1037. **{
  1038. "form_class": forms.ModelChoiceField,
  1039. "queryset": self.remote_field.model._default_manager.using(using),
  1040. "to_field_name": self.remote_field.field_name,
  1041. **kwargs,
  1042. "blank": self.blank,
  1043. }
  1044. )
  1045. def db_check(self, connection):
  1046. return None
  1047. def db_type(self, connection):
  1048. return self.target_field.rel_db_type(connection=connection)
  1049. def cast_db_type(self, connection):
  1050. return self.target_field.cast_db_type(connection=connection)
  1051. def db_parameters(self, connection):
  1052. target_db_parameters = self.target_field.db_parameters(connection)
  1053. return {
  1054. "type": self.db_type(connection),
  1055. "check": self.db_check(connection),
  1056. "collation": target_db_parameters.get("collation"),
  1057. }
  1058. def convert_empty_strings(self, value, expression, connection):
  1059. if (not value) and isinstance(value, str):
  1060. return None
  1061. return value
  1062. def get_db_converters(self, connection):
  1063. converters = super().get_db_converters(connection)
  1064. if connection.features.interprets_empty_strings_as_nulls:
  1065. converters += [self.convert_empty_strings]
  1066. return converters
  1067. def get_col(self, alias, output_field=None):
  1068. if output_field is None:
  1069. output_field = self.target_field
  1070. while isinstance(output_field, ForeignKey):
  1071. output_field = output_field.target_field
  1072. if output_field is self:
  1073. raise ValueError("Cannot resolve output_field.")
  1074. return super().get_col(alias, output_field)
  1075. class OneToOneField(ForeignKey):
  1076. """
  1077. A OneToOneField is essentially the same as a ForeignKey, with the exception
  1078. that it always carries a "unique" constraint with it and the reverse
  1079. relation always returns the object pointed to (since there will only ever
  1080. be one), rather than returning a list.
  1081. """
  1082. # Field flags
  1083. many_to_many = False
  1084. many_to_one = False
  1085. one_to_many = False
  1086. one_to_one = True
  1087. related_accessor_class = ReverseOneToOneDescriptor
  1088. forward_related_accessor_class = ForwardOneToOneDescriptor
  1089. rel_class = OneToOneRel
  1090. description = _("One-to-one relationship")
  1091. def __init__(self, to, on_delete, to_field=None, **kwargs):
  1092. kwargs["unique"] = True
  1093. super().__init__(to, on_delete, to_field=to_field, **kwargs)
  1094. def deconstruct(self):
  1095. name, path, args, kwargs = super().deconstruct()
  1096. if "unique" in kwargs:
  1097. del kwargs["unique"]
  1098. return name, path, args, kwargs
  1099. def formfield(self, **kwargs):
  1100. if self.remote_field.parent_link:
  1101. return None
  1102. return super().formfield(**kwargs)
  1103. def save_form_data(self, instance, data):
  1104. if isinstance(data, self.remote_field.model):
  1105. setattr(instance, self.name, data)
  1106. else:
  1107. setattr(instance, self.attname, data)
  1108. # Remote field object must be cleared otherwise Model.save()
  1109. # will reassign attname using the related object pk.
  1110. if data is None:
  1111. setattr(instance, self.name, data)
  1112. def _check_unique(self, **kwargs):
  1113. # Override ForeignKey since check isn't applicable here.
  1114. return []
  1115. def create_many_to_many_intermediary_model(field, klass):
  1116. from django.db import models
  1117. def set_managed(model, related, through):
  1118. through._meta.managed = model._meta.managed or related._meta.managed
  1119. to_model = resolve_relation(klass, field.remote_field.model)
  1120. name = "%s_%s" % (klass._meta.object_name, field.name)
  1121. lazy_related_operation(set_managed, klass, to_model, name)
  1122. to = make_model_tuple(to_model)[1]
  1123. from_ = klass._meta.model_name
  1124. if to == from_:
  1125. to = "to_%s" % to
  1126. from_ = "from_%s" % from_
  1127. meta = type(
  1128. "Meta",
  1129. (),
  1130. {
  1131. "db_table": field._get_m2m_db_table(klass._meta),
  1132. "auto_created": klass,
  1133. "app_label": klass._meta.app_label,
  1134. "db_tablespace": klass._meta.db_tablespace,
  1135. "unique_together": (from_, to),
  1136. "verbose_name": _("%(from)s-%(to)s relationship")
  1137. % {"from": from_, "to": to},
  1138. "verbose_name_plural": _("%(from)s-%(to)s relationships")
  1139. % {"from": from_, "to": to},
  1140. "apps": field.model._meta.apps,
  1141. },
  1142. )
  1143. # Construct and return the new class.
  1144. return type(
  1145. name,
  1146. (models.Model,),
  1147. {
  1148. "Meta": meta,
  1149. "__module__": klass.__module__,
  1150. from_: models.ForeignKey(
  1151. klass,
  1152. related_name="%s+" % name,
  1153. db_tablespace=field.db_tablespace,
  1154. db_constraint=field.remote_field.db_constraint,
  1155. on_delete=CASCADE,
  1156. ),
  1157. to: models.ForeignKey(
  1158. to_model,
  1159. related_name="%s+" % name,
  1160. db_tablespace=field.db_tablespace,
  1161. db_constraint=field.remote_field.db_constraint,
  1162. on_delete=CASCADE,
  1163. ),
  1164. },
  1165. )
  1166. class ManyToManyField(RelatedField):
  1167. """
  1168. Provide a many-to-many relation by using an intermediary model that
  1169. holds two ForeignKey fields pointed at the two sides of the relation.
  1170. Unless a ``through`` model was provided, ManyToManyField will use the
  1171. create_many_to_many_intermediary_model factory to automatically generate
  1172. the intermediary model.
  1173. """
  1174. # Field flags
  1175. many_to_many = True
  1176. many_to_one = False
  1177. one_to_many = False
  1178. one_to_one = False
  1179. rel_class = ManyToManyRel
  1180. description = _("Many-to-many relationship")
  1181. def __init__(
  1182. self,
  1183. to,
  1184. related_name=None,
  1185. related_query_name=None,
  1186. limit_choices_to=None,
  1187. symmetrical=None,
  1188. through=None,
  1189. through_fields=None,
  1190. db_constraint=True,
  1191. db_table=None,
  1192. swappable=True,
  1193. **kwargs,
  1194. ):
  1195. try:
  1196. to._meta
  1197. except AttributeError:
  1198. if not isinstance(to, str):
  1199. raise TypeError(
  1200. "%s(%r) is invalid. First parameter to ManyToManyField "
  1201. "must be either a model, a model name, or the string %r"
  1202. % (
  1203. self.__class__.__name__,
  1204. to,
  1205. RECURSIVE_RELATIONSHIP_CONSTANT,
  1206. )
  1207. )
  1208. if symmetrical is None:
  1209. symmetrical = to == RECURSIVE_RELATIONSHIP_CONSTANT
  1210. if through is not None and db_table is not None:
  1211. raise ValueError(
  1212. "Cannot specify a db_table if an intermediary model is used."
  1213. )
  1214. kwargs["rel"] = self.rel_class(
  1215. self,
  1216. to,
  1217. related_name=related_name,
  1218. related_query_name=related_query_name,
  1219. limit_choices_to=limit_choices_to,
  1220. symmetrical=symmetrical,
  1221. through=through,
  1222. through_fields=through_fields,
  1223. db_constraint=db_constraint,
  1224. )
  1225. self.has_null_arg = "null" in kwargs
  1226. super().__init__(
  1227. related_name=related_name,
  1228. related_query_name=related_query_name,
  1229. limit_choices_to=limit_choices_to,
  1230. **kwargs,
  1231. )
  1232. self.db_table = db_table
  1233. self.swappable = swappable
  1234. def check(self, **kwargs):
  1235. return [
  1236. *super().check(**kwargs),
  1237. *self._check_unique(**kwargs),
  1238. *self._check_relationship_model(**kwargs),
  1239. *self._check_ignored_options(**kwargs),
  1240. *self._check_table_uniqueness(**kwargs),
  1241. ]
  1242. def _check_unique(self, **kwargs):
  1243. if self.unique:
  1244. return [
  1245. checks.Error(
  1246. "ManyToManyFields cannot be unique.",
  1247. obj=self,
  1248. id="fields.E330",
  1249. )
  1250. ]
  1251. return []
  1252. def _check_ignored_options(self, **kwargs):
  1253. warnings = []
  1254. if self.has_null_arg:
  1255. warnings.append(
  1256. checks.Warning(
  1257. "null has no effect on ManyToManyField.",
  1258. obj=self,
  1259. id="fields.W340",
  1260. )
  1261. )
  1262. if self._validators:
  1263. warnings.append(
  1264. checks.Warning(
  1265. "ManyToManyField does not support validators.",
  1266. obj=self,
  1267. id="fields.W341",
  1268. )
  1269. )
  1270. if self.remote_field.symmetrical and self._related_name:
  1271. warnings.append(
  1272. checks.Warning(
  1273. "related_name has no effect on ManyToManyField "
  1274. 'with a symmetrical relationship, e.g. to "self".',
  1275. obj=self,
  1276. id="fields.W345",
  1277. )
  1278. )
  1279. if self.db_comment:
  1280. warnings.append(
  1281. checks.Warning(
  1282. "db_comment has no effect on ManyToManyField.",
  1283. obj=self,
  1284. id="fields.W346",
  1285. )
  1286. )
  1287. return warnings
  1288. def _check_relationship_model(self, from_model=None, **kwargs):
  1289. if hasattr(self.remote_field.through, "_meta"):
  1290. qualified_model_name = "%s.%s" % (
  1291. self.remote_field.through._meta.app_label,
  1292. self.remote_field.through.__name__,
  1293. )
  1294. else:
  1295. qualified_model_name = self.remote_field.through
  1296. errors = []
  1297. if self.remote_field.through not in self.opts.apps.get_models(
  1298. include_auto_created=True
  1299. ):
  1300. # The relationship model is not installed.
  1301. errors.append(
  1302. checks.Error(
  1303. "Field specifies a many-to-many relation through model "
  1304. "'%s', which has not been installed." % qualified_model_name,
  1305. obj=self,
  1306. id="fields.E331",
  1307. )
  1308. )
  1309. else:
  1310. assert from_model is not None, (
  1311. "ManyToManyField with intermediate "
  1312. "tables cannot be checked if you don't pass the model "
  1313. "where the field is attached to."
  1314. )
  1315. # Set some useful local variables
  1316. to_model = resolve_relation(from_model, self.remote_field.model)
  1317. from_model_name = from_model._meta.object_name
  1318. if isinstance(to_model, str):
  1319. to_model_name = to_model
  1320. else:
  1321. to_model_name = to_model._meta.object_name
  1322. relationship_model_name = self.remote_field.through._meta.object_name
  1323. self_referential = from_model == to_model
  1324. # Count foreign keys in intermediate model
  1325. if self_referential:
  1326. seen_self = sum(
  1327. from_model == getattr(field.remote_field, "model", None)
  1328. for field in self.remote_field.through._meta.fields
  1329. )
  1330. if seen_self > 2 and not self.remote_field.through_fields:
  1331. errors.append(
  1332. checks.Error(
  1333. "The model is used as an intermediate model by "
  1334. "'%s', but it has more than two foreign keys "
  1335. "to '%s', which is ambiguous. You must specify "
  1336. "which two foreign keys Django should use via the "
  1337. "through_fields keyword argument."
  1338. % (self, from_model_name),
  1339. hint=(
  1340. "Use through_fields to specify which two foreign keys "
  1341. "Django should use."
  1342. ),
  1343. obj=self.remote_field.through,
  1344. id="fields.E333",
  1345. )
  1346. )
  1347. else:
  1348. # Count foreign keys in relationship model
  1349. seen_from = sum(
  1350. from_model == getattr(field.remote_field, "model", None)
  1351. for field in self.remote_field.through._meta.fields
  1352. )
  1353. seen_to = sum(
  1354. to_model == getattr(field.remote_field, "model", None)
  1355. for field in self.remote_field.through._meta.fields
  1356. )
  1357. if seen_from > 1 and not self.remote_field.through_fields:
  1358. errors.append(
  1359. checks.Error(
  1360. (
  1361. "The model is used as an intermediate model by "
  1362. "'%s', but it has more than one foreign key "
  1363. "from '%s', which is ambiguous. You must specify "
  1364. "which foreign key Django should use via the "
  1365. "through_fields keyword argument."
  1366. )
  1367. % (self, from_model_name),
  1368. hint=(
  1369. "If you want to create a recursive relationship, "
  1370. 'use ManyToManyField("%s", through="%s").'
  1371. )
  1372. % (
  1373. RECURSIVE_RELATIONSHIP_CONSTANT,
  1374. relationship_model_name,
  1375. ),
  1376. obj=self,
  1377. id="fields.E334",
  1378. )
  1379. )
  1380. if seen_to > 1 and not self.remote_field.through_fields:
  1381. errors.append(
  1382. checks.Error(
  1383. "The model is used as an intermediate model by "
  1384. "'%s', but it has more than one foreign key "
  1385. "to '%s', which is ambiguous. You must specify "
  1386. "which foreign key Django should use via the "
  1387. "through_fields keyword argument." % (self, to_model_name),
  1388. hint=(
  1389. "If you want to create a recursive relationship, "
  1390. 'use ManyToManyField("%s", through="%s").'
  1391. )
  1392. % (
  1393. RECURSIVE_RELATIONSHIP_CONSTANT,
  1394. relationship_model_name,
  1395. ),
  1396. obj=self,
  1397. id="fields.E335",
  1398. )
  1399. )
  1400. if seen_from == 0 or seen_to == 0:
  1401. errors.append(
  1402. checks.Error(
  1403. "The model is used as an intermediate model by "
  1404. "'%s', but it does not have a foreign key to '%s' or '%s'."
  1405. % (self, from_model_name, to_model_name),
  1406. obj=self.remote_field.through,
  1407. id="fields.E336",
  1408. )
  1409. )
  1410. # Validate `through_fields`.
  1411. if self.remote_field.through_fields is not None:
  1412. # Validate that we're given an iterable of at least two items
  1413. # and that none of them is "falsy".
  1414. if not (
  1415. len(self.remote_field.through_fields) >= 2
  1416. and self.remote_field.through_fields[0]
  1417. and self.remote_field.through_fields[1]
  1418. ):
  1419. errors.append(
  1420. checks.Error(
  1421. "Field specifies 'through_fields' but does not provide "
  1422. "the names of the two link fields that should be used "
  1423. "for the relation through model '%s'." % qualified_model_name,
  1424. hint=(
  1425. "Make sure you specify 'through_fields' as "
  1426. "through_fields=('field1', 'field2')"
  1427. ),
  1428. obj=self,
  1429. id="fields.E337",
  1430. )
  1431. )
  1432. # Validate the given through fields -- they should be actual
  1433. # fields on the through model, and also be foreign keys to the
  1434. # expected models.
  1435. else:
  1436. assert from_model is not None, (
  1437. "ManyToManyField with intermediate "
  1438. "tables cannot be checked if you don't pass the model "
  1439. "where the field is attached to."
  1440. )
  1441. source, through, target = (
  1442. from_model,
  1443. self.remote_field.through,
  1444. self.remote_field.model,
  1445. )
  1446. source_field_name, target_field_name = self.remote_field.through_fields[
  1447. :2
  1448. ]
  1449. for field_name, related_model in (
  1450. (source_field_name, source),
  1451. (target_field_name, target),
  1452. ):
  1453. possible_field_names = []
  1454. for f in through._meta.fields:
  1455. if (
  1456. hasattr(f, "remote_field")
  1457. and getattr(f.remote_field, "model", None) == related_model
  1458. ):
  1459. possible_field_names.append(f.name)
  1460. if possible_field_names:
  1461. hint = (
  1462. "Did you mean one of the following foreign keys to '%s': "
  1463. "%s?"
  1464. % (
  1465. related_model._meta.object_name,
  1466. ", ".join(possible_field_names),
  1467. )
  1468. )
  1469. else:
  1470. hint = None
  1471. try:
  1472. field = through._meta.get_field(field_name)
  1473. except exceptions.FieldDoesNotExist:
  1474. errors.append(
  1475. checks.Error(
  1476. "The intermediary model '%s' has no field '%s'."
  1477. % (qualified_model_name, field_name),
  1478. hint=hint,
  1479. obj=self,
  1480. id="fields.E338",
  1481. )
  1482. )
  1483. else:
  1484. if not (
  1485. hasattr(field, "remote_field")
  1486. and getattr(field.remote_field, "model", None)
  1487. == related_model
  1488. ):
  1489. errors.append(
  1490. checks.Error(
  1491. "'%s.%s' is not a foreign key to '%s'."
  1492. % (
  1493. through._meta.object_name,
  1494. field_name,
  1495. related_model._meta.object_name,
  1496. ),
  1497. hint=hint,
  1498. obj=self,
  1499. id="fields.E339",
  1500. )
  1501. )
  1502. return errors
  1503. def _check_table_uniqueness(self, **kwargs):
  1504. if (
  1505. isinstance(self.remote_field.through, str)
  1506. or not self.remote_field.through._meta.managed
  1507. ):
  1508. return []
  1509. registered_tables = {
  1510. model._meta.db_table: model
  1511. for model in self.opts.apps.get_models(include_auto_created=True)
  1512. if model != self.remote_field.through and model._meta.managed
  1513. }
  1514. m2m_db_table = self.m2m_db_table()
  1515. model = registered_tables.get(m2m_db_table)
  1516. # The second condition allows multiple m2m relations on a model if
  1517. # some point to a through model that proxies another through model.
  1518. if (
  1519. model
  1520. and model._meta.concrete_model
  1521. != self.remote_field.through._meta.concrete_model
  1522. ):
  1523. if model._meta.auto_created:
  1524. def _get_field_name(model):
  1525. for field in model._meta.auto_created._meta.many_to_many:
  1526. if field.remote_field.through is model:
  1527. return field.name
  1528. opts = model._meta.auto_created._meta
  1529. clashing_obj = "%s.%s" % (opts.label, _get_field_name(model))
  1530. else:
  1531. clashing_obj = model._meta.label
  1532. if settings.DATABASE_ROUTERS:
  1533. error_class, error_id = checks.Warning, "fields.W344"
  1534. error_hint = (
  1535. "You have configured settings.DATABASE_ROUTERS. Verify "
  1536. "that the table of %r is correctly routed to a separate "
  1537. "database." % clashing_obj
  1538. )
  1539. else:
  1540. error_class, error_id = checks.Error, "fields.E340"
  1541. error_hint = None
  1542. return [
  1543. error_class(
  1544. "The field's intermediary table '%s' clashes with the "
  1545. "table name of '%s'." % (m2m_db_table, clashing_obj),
  1546. obj=self,
  1547. hint=error_hint,
  1548. id=error_id,
  1549. )
  1550. ]
  1551. return []
  1552. def deconstruct(self):
  1553. name, path, args, kwargs = super().deconstruct()
  1554. # Handle the simpler arguments.
  1555. if self.db_table is not None:
  1556. kwargs["db_table"] = self.db_table
  1557. if self.remote_field.db_constraint is not True:
  1558. kwargs["db_constraint"] = self.remote_field.db_constraint
  1559. # Lowercase model names as they should be treated as case-insensitive.
  1560. if isinstance(self.remote_field.model, str):
  1561. if "." in self.remote_field.model:
  1562. app_label, model_name = self.remote_field.model.split(".")
  1563. kwargs["to"] = "%s.%s" % (app_label, model_name.lower())
  1564. else:
  1565. kwargs["to"] = self.remote_field.model.lower()
  1566. else:
  1567. kwargs["to"] = self.remote_field.model._meta.label_lower
  1568. if getattr(self.remote_field, "through", None) is not None:
  1569. if isinstance(self.remote_field.through, str):
  1570. kwargs["through"] = self.remote_field.through
  1571. elif not self.remote_field.through._meta.auto_created:
  1572. kwargs["through"] = self.remote_field.through._meta.label
  1573. # If swappable is True, then see if we're actually pointing to the target
  1574. # of a swap.
  1575. swappable_setting = self.swappable_setting
  1576. if swappable_setting is not None:
  1577. # If it's already a settings reference, error.
  1578. if hasattr(kwargs["to"], "setting_name"):
  1579. if kwargs["to"].setting_name != swappable_setting:
  1580. raise ValueError(
  1581. "Cannot deconstruct a ManyToManyField pointing to a "
  1582. "model that is swapped in place of more than one model "
  1583. "(%s and %s)" % (kwargs["to"].setting_name, swappable_setting)
  1584. )
  1585. kwargs["to"] = SettingsReference(
  1586. kwargs["to"],
  1587. swappable_setting,
  1588. )
  1589. return name, path, args, kwargs
  1590. def _get_path_info(self, direct=False, filtered_relation=None):
  1591. """Called by both direct and indirect m2m traversal."""
  1592. int_model = self.remote_field.through
  1593. linkfield1 = int_model._meta.get_field(self.m2m_field_name())
  1594. linkfield2 = int_model._meta.get_field(self.m2m_reverse_field_name())
  1595. if direct:
  1596. join1infos = linkfield1.reverse_path_infos
  1597. if filtered_relation:
  1598. join2infos = linkfield2.get_path_info(filtered_relation)
  1599. else:
  1600. join2infos = linkfield2.path_infos
  1601. else:
  1602. join1infos = linkfield2.reverse_path_infos
  1603. if filtered_relation:
  1604. join2infos = linkfield1.get_path_info(filtered_relation)
  1605. else:
  1606. join2infos = linkfield1.path_infos
  1607. # Get join infos between the last model of join 1 and the first model
  1608. # of join 2. Assume the only reason these may differ is due to model
  1609. # inheritance.
  1610. join1_final = join1infos[-1].to_opts
  1611. join2_initial = join2infos[0].from_opts
  1612. if join1_final is join2_initial:
  1613. intermediate_infos = []
  1614. elif issubclass(join1_final.model, join2_initial.model):
  1615. intermediate_infos = join1_final.get_path_to_parent(join2_initial.model)
  1616. else:
  1617. intermediate_infos = join2_initial.get_path_from_parent(join1_final.model)
  1618. return [*join1infos, *intermediate_infos, *join2infos]
  1619. def get_path_info(self, filtered_relation=None):
  1620. return self._get_path_info(direct=True, filtered_relation=filtered_relation)
  1621. @cached_property
  1622. def path_infos(self):
  1623. return self.get_path_info()
  1624. def get_reverse_path_info(self, filtered_relation=None):
  1625. return self._get_path_info(direct=False, filtered_relation=filtered_relation)
  1626. @cached_property
  1627. def reverse_path_infos(self):
  1628. return self.get_reverse_path_info()
  1629. def _get_m2m_db_table(self, opts):
  1630. """
  1631. Function that can be curried to provide the m2m table name for this
  1632. relation.
  1633. """
  1634. if self.remote_field.through is not None:
  1635. return self.remote_field.through._meta.db_table
  1636. elif self.db_table:
  1637. return self.db_table
  1638. else:
  1639. m2m_table_name = "%s_%s" % (utils.strip_quotes(opts.db_table), self.name)
  1640. return utils.truncate_name(m2m_table_name, connection.ops.max_name_length())
  1641. def _get_m2m_attr(self, related, attr):
  1642. """
  1643. Function that can be curried to provide the source accessor or DB
  1644. column name for the m2m table.
  1645. """
  1646. cache_attr = "_m2m_%s_cache" % attr
  1647. if hasattr(self, cache_attr):
  1648. return getattr(self, cache_attr)
  1649. if self.remote_field.through_fields is not None:
  1650. link_field_name = self.remote_field.through_fields[0]
  1651. else:
  1652. link_field_name = None
  1653. for f in self.remote_field.through._meta.fields:
  1654. if (
  1655. f.is_relation
  1656. and f.remote_field.model == related.related_model
  1657. and (link_field_name is None or link_field_name == f.name)
  1658. ):
  1659. setattr(self, cache_attr, getattr(f, attr))
  1660. return getattr(self, cache_attr)
  1661. def _get_m2m_reverse_attr(self, related, attr):
  1662. """
  1663. Function that can be curried to provide the related accessor or DB
  1664. column name for the m2m table.
  1665. """
  1666. cache_attr = "_m2m_reverse_%s_cache" % attr
  1667. if hasattr(self, cache_attr):
  1668. return getattr(self, cache_attr)
  1669. found = False
  1670. if self.remote_field.through_fields is not None:
  1671. link_field_name = self.remote_field.through_fields[1]
  1672. else:
  1673. link_field_name = None
  1674. for f in self.remote_field.through._meta.fields:
  1675. if f.is_relation and f.remote_field.model == related.model:
  1676. if link_field_name is None and related.related_model == related.model:
  1677. # If this is an m2m-intermediate to self,
  1678. # the first foreign key you find will be
  1679. # the source column. Keep searching for
  1680. # the second foreign key.
  1681. if found:
  1682. setattr(self, cache_attr, getattr(f, attr))
  1683. break
  1684. else:
  1685. found = True
  1686. elif link_field_name is None or link_field_name == f.name:
  1687. setattr(self, cache_attr, getattr(f, attr))
  1688. break
  1689. return getattr(self, cache_attr)
  1690. def contribute_to_class(self, cls, name, **kwargs):
  1691. # To support multiple relations to self, it's useful to have a non-None
  1692. # related name on symmetrical relations for internal reasons. The
  1693. # concept doesn't make a lot of sense externally ("you want me to
  1694. # specify *what* on my non-reversible relation?!"), so we set it up
  1695. # automatically. The funky name reduces the chance of an accidental
  1696. # clash.
  1697. if self.remote_field.symmetrical and (
  1698. self.remote_field.model == RECURSIVE_RELATIONSHIP_CONSTANT
  1699. or self.remote_field.model == cls._meta.object_name
  1700. ):
  1701. self.remote_field.related_name = "%s_rel_+" % name
  1702. elif self.remote_field.hidden:
  1703. # If the backwards relation is disabled, replace the original
  1704. # related_name with one generated from the m2m field name. Django
  1705. # still uses backwards relations internally and we need to avoid
  1706. # clashes between multiple m2m fields with related_name == '+'.
  1707. self.remote_field.related_name = "_%s_%s_%s_+" % (
  1708. cls._meta.app_label,
  1709. cls.__name__.lower(),
  1710. name,
  1711. )
  1712. super().contribute_to_class(cls, name, **kwargs)
  1713. # The intermediate m2m model is not auto created if:
  1714. # 1) There is a manually specified intermediate, or
  1715. # 2) The class owning the m2m field is abstract.
  1716. # 3) The class owning the m2m field has been swapped out.
  1717. if not cls._meta.abstract:
  1718. if self.remote_field.through:
  1719. def resolve_through_model(_, model, field):
  1720. field.remote_field.through = model
  1721. lazy_related_operation(
  1722. resolve_through_model, cls, self.remote_field.through, field=self
  1723. )
  1724. elif not cls._meta.swapped:
  1725. self.remote_field.through = create_many_to_many_intermediary_model(
  1726. self, cls
  1727. )
  1728. # Add the descriptor for the m2m relation.
  1729. setattr(cls, self.name, ManyToManyDescriptor(self.remote_field, reverse=False))
  1730. # Set up the accessor for the m2m table name for the relation.
  1731. self.m2m_db_table = partial(self._get_m2m_db_table, cls._meta)
  1732. def contribute_to_related_class(self, cls, related):
  1733. # Internal M2Ms (i.e., those with a related name ending with '+')
  1734. # and swapped models don't get a related descriptor.
  1735. if not self.remote_field.hidden and not related.related_model._meta.swapped:
  1736. setattr(
  1737. cls,
  1738. related.accessor_name,
  1739. ManyToManyDescriptor(self.remote_field, reverse=True),
  1740. )
  1741. # Set up the accessors for the column names on the m2m table.
  1742. self.m2m_column_name = partial(self._get_m2m_attr, related, "column")
  1743. self.m2m_reverse_name = partial(self._get_m2m_reverse_attr, related, "column")
  1744. self.m2m_field_name = partial(self._get_m2m_attr, related, "name")
  1745. self.m2m_reverse_field_name = partial(
  1746. self._get_m2m_reverse_attr, related, "name"
  1747. )
  1748. get_m2m_rel = partial(self._get_m2m_attr, related, "remote_field")
  1749. self.m2m_target_field_name = lambda: get_m2m_rel().field_name
  1750. get_m2m_reverse_rel = partial(
  1751. self._get_m2m_reverse_attr, related, "remote_field"
  1752. )
  1753. self.m2m_reverse_target_field_name = lambda: get_m2m_reverse_rel().field_name
  1754. def set_attributes_from_rel(self):
  1755. pass
  1756. def value_from_object(self, obj):
  1757. return [] if obj.pk is None else list(getattr(obj, self.attname).all())
  1758. def save_form_data(self, instance, data):
  1759. getattr(instance, self.attname).set(data)
  1760. def formfield(self, *, using=None, **kwargs):
  1761. defaults = {
  1762. "form_class": forms.ModelMultipleChoiceField,
  1763. "queryset": self.remote_field.model._default_manager.using(using),
  1764. **kwargs,
  1765. }
  1766. # If initial is passed in, it's a list of related objects, but the
  1767. # MultipleChoiceField takes a list of IDs.
  1768. if defaults.get("initial") is not None:
  1769. initial = defaults["initial"]
  1770. if callable(initial):
  1771. initial = initial()
  1772. defaults["initial"] = [i.pk for i in initial]
  1773. return super().formfield(**defaults)
  1774. def db_check(self, connection):
  1775. return None
  1776. def db_type(self, connection):
  1777. # A ManyToManyField is not represented by a single column,
  1778. # so return None.
  1779. return None
  1780. def db_parameters(self, connection):
  1781. return {"type": None, "check": None}