Fixed #25966 -- Made get_user_model() work at import time.

This makes it equivalent to: `from django.contrib.auth.models import User`.

Thanks Aymeric Augustin for the initial patch and Tim Graham for the
review.

3 files changed, 30 insertions, 7 deletions

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 149312aafd..c3a06ab855 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -473,10 +473,6 @@ Here are some common problems that you may encounter during initialization:
   will also trigger this exception. The ORM cannot function properly until all
   models are available.
 
-  Another common culprit is :func:`django.contrib.auth.get_user_model()`. Use
-  the :setting:`AUTH_USER_MODEL` setting to reference the User model at import
-  time.
-
   This exception also happens if you forget to call :func:`django.setup()` in
   a standalone Python script.
 
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 53265272ca..c8c64ab9c9 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -125,6 +125,9 @@ Minor features
   Set :attr:`CustomUser.EMAIL_FIELD
   <django.contrib.auth.models.CustomUser.EMAIL_FIELD>` to the name of the field.
 
+* :func:`~django.contrib.auth.get_user_model` can now be called at import time,
+  even in modules that define models.
+
 :mod:`django.contrib.contenttypes`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/docs/topics/auth/customizing.txt b/docs/topics/auth/customizing.txt
index 1b9dc6539e..79ffa0a88b 100644
--- a/docs/topics/auth/customizing.txt
+++ b/docs/topics/auth/customizing.txt
@@ -487,9 +487,33 @@ different user model.
 
         post_save.connect(post_save_receiver, sender=settings.AUTH_USER_MODEL)
 
-    Generally speaking, you should reference the user model with the
-    :setting:`AUTH_USER_MODEL` setting in code that is executed at import
-    time. ``get_user_model()`` only works once Django has imported all models.
+    Generally speaking, it's easiest to refer to the user model with the
+    :setting:`AUTH_USER_MODEL` setting in code that's executed at import time,
+    however, it's also possible to call ``get_user_model()`` while Django
+    is importing models, so you could use
+    ``models.ForeignKey(get_user_model(), ...)``.
+
+    If your app is tested with multiple user models, using
+    ``@override_settings(AUTH_USER_MODEL=...)`` for example, and you cache the
+    result of ``get_user_model()`` in a module-level variable, you may need to
+    listen to the  :data:`~django.test.signals.setting_changed` signal to clear
+    the cache. For example::
+
+        from django.apps import apps
+        from django.contrib.auth import get_user_model
+        from django.core.signals import setting_changed
+        from django.dispatch import receiver
+
+        @receiver(setting_changed)
+        def user_model_swapped(**kwargs):
+            if kwargs['setting'] == 'AUTH_USER_MODEL':
+                apps.clear_cache()
+                from myapp import some_module
+                some_module.UserModel = get_user_model()
+
+    .. versionchanged:: 1.11
+
+        The ability to call ``get_user_model()`` at import time was added.
 
 .. _specifying-custom-user-model: