Ticket #10981: 10981-string_model_names_notes.2.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 django.db import models
+    from production.models import Manufacturer
+
+    class Vehicle(models.Model):
+        manufacturer = models.ForeignKey(Manufacturer)
+        # ...
+
+::
+
+    # production/models.py
+    from django.db import models
+    from goods.models import Vehicle # This would introduce circular imports
+
+    class Manufacturer(models.Model):
+        main_product = models.ForeignKey(Vehicle, related_name='lead_manufacturers')
+
+Using Python imports in this case would introduce circular imports between the
+models files of both applications and this would keep them from working. That's
+the reason why, in this particular case, you can use the name of a model in
+string form to break the import loop::
+
+    # goods/models.py
+    from django.db import models
+    from production.models import Manufacturer
+
+    class Vehicle(models.Model):
+        manufacturer = models.ForeignKey(Manufacturer)
+        # ...
+
+::
+
+    # production/models.py
+    from django.db import models
+
+    class Manufacturer(models.Model):
+        main_product = models.ForeignKey('goods.Vehicle', related_name='lead_manufacturers')
 
 .. 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')