Ticket #10981: 10981-string_model_names_notes.diff

docs/ref/models/fields.txt

@@ -801 +801 @@
         # ...
 
 Note, however, that this only refers to models in the same ``models.py`` file --
-you cannot use a string to reference a model defined in another application or
-imported from elsewhere.
+As a general rule, you cannot use a string to reference a model defined in
+another application or imported from elsewhere.
+
+.. versionchanged:: 1.0
+
+The only exception to this rule is the following scenario: Models defined in
+different applications have mutually referencing relationships::
+
+    # goods/models.py
+    from production.models import Manufacturer
+
+    class Vehicle(models.Model):
+        manufacturer = models.ForeignKey(Manufacturer)
+        # ...
+
+::
+
+    # production/models.py
+    from goods.models import Vehicle # This would introduce circular imports
+
+    class Manufacturer(models.Model):
+        main_product = models.ForeignKey(Vehicle)
+
+Solving this by using Python imports would mean having circular imports between
+the models files of both applications. That's the reason why, in this particular
+case, you can use the name of a model in string form::
+
+    # goods/models.py
+    from production.models import Manufacturer
+
+    class Vehicle(models.Model):
+        manufacturer = models.ForeignKey(Manufacturer)
+        # ...
+
+::
+
+    # production/models.py
+
+    class Manufacturer(models.Model):
+        main_product = models.ForeignKey('goods.Vehicle')
 
 .. versionchanged:: 1.0
    Refering models in other applications must include the application label.
 
-To refer to models defined in another
-application, you must instead explicitly specify the application label. For
-example, if the ``Manufacturer`` model above is defined in another application
-called ``production``, you'd need to use::
+To refer to models defined in another application, you must instead explicitly
+specify the application label. For example, if the ``Manufacturer`` model above
+is defined in another application called ``production``, you'd need to use::
 
     class Car(models.Model):
         manufacturer = models.ForeignKey('production.Manufacturer')