Added require_ready argument to get_model methods.

This allows bringing back the behavior of Django < 1.7.

Also fixed the check for the app registry being ready in
AppConfig.get_model(s), which was inconsistent with the equivalent check in
Apps.get_model(s). That part is a backwards-incompatible change.

2 files changed, 31 insertions, 4 deletions

diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index 110e5e867d..149312aafd 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -229,14 +229,20 @@ Methods
 
     Requires the app registry to be fully populated.
 
-.. method:: AppConfig.get_model(model_name)
+.. method:: AppConfig.get_model(model_name, require_ready=True)
 
     Returns the :class:`~django.db.models.Model` with the given
     ``model_name``. ``model_name`` is case-insensitive.
 
     Raises :exc:`LookupError` if no such model exists in this application.
 
-    Requires the app registry to be fully populated.
+    Requires the app registry to be fully populated unless the
+    ``require_ready`` argument is set to ``False``. ``require_ready`` behaves
+    exactly as in :meth:`apps.get_model()`.
+
+    .. versionadded:: 1.11
+
+        The ``require_ready`` keyword argument was added.
 
 .. method:: AppConfig.ready()
 
@@ -341,7 +347,7 @@ Application registry
     Checks whether an application with the given name exists in the registry.
     ``app_name`` is the full name of the app, e.g. ``'django.contrib.admin'``.
 
-.. method:: apps.get_model(app_label, model_name)
+.. method:: apps.get_model(app_label, model_name, require_ready=True)
 
     Returns the :class:`~django.db.models.Model` with the given ``app_label``
     and ``model_name``. As a shortcut, this method also accepts a single
@@ -352,6 +358,26 @@ Application registry
     :exc:`ValueError` when called with a single argument that doesn't contain
     exactly one dot.
 
+    Requires the app registry to be fully populated unless the
+    ``require_ready`` argument is set to ``False``.
+
+    Setting ``require_ready`` to ``False`` allows looking up models
+    :ref:`while the app registry is being populated <app-loading-process>`,
+    specifically during the second phase where it imports models. Then
+    ``get_model()`` has the same effect as importing the model. The main use
+    case is to configure model classes with settings, such as
+    :setting:`AUTH_USER_MODEL`.
+
+    When ``require_ready`` is ``False``, ``get_model()`` returns a model class
+    that may not be fully functional (reverse accessors may be missing, for
+    example) until the app registry is fully populated. For this reason, it's
+    best to leave ``require_ready`` to the default value of ``True`` whenever
+    possible.
+
+    .. versionadded:: 1.11
+
+        The ``require_ready`` keyword argument was added.
+
 .. _app-loading-process:
 
 Initialization process
diff --git a/docs/releases/1.11.txt b/docs/releases/1.11.txt
index 8fd0795d67..7886d84a3b 100644
--- a/docs/releases/1.11.txt
+++ b/docs/releases/1.11.txt
@@ -584,7 +584,8 @@ Miscellaneous
   :exc:`~django.core.exceptions.AppRegistryNotReady` if they're called before
   models of all applications have been loaded. Previously they only required
   the target application's models to be loaded and thus could return models
-  without all their relations set up.
+  without all their relations set up. If you need the old behavior of
+  ``get_model()``, set the ``require_ready`` argument to ``False``.
 
 .. _deprecated-features-1.11: