Fixed #31180 -- Configured applications automatically.

3 files changed, 95 insertions, 39 deletions

diff --git a/docs/internals/deprecation.txt b/docs/internals/deprecation.txt
index d6becd31c1..826c2ee814 100644
--- a/docs/internals/deprecation.txt
+++ b/docs/internals/deprecation.txt
@@ -24,6 +24,8 @@ details on these changes.
 * The ``whitelist`` argument and ``domain_whitelist`` attribute of
   ``django.core.validators.EmailValidator`` will be removed.
 
+* The ``default_app_config`` module variable will be removed.
+
 .. _deprecation-removed-in-4.0:
 
 4.0
diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt
index d1a242163f..765e9e8d3c 100644
--- a/docs/ref/applications.txt
+++ b/docs/ref/applications.txt
@@ -56,25 +56,28 @@ application and have models, etc. (which would require adding it to
 Configuring applications
 ========================
 
-To configure an application, subclass :class:`~django.apps.AppConfig` and put
-the dotted path to that subclass in :setting:`INSTALLED_APPS`.
+To configure an application, create an ``apps.py`` module inside the
+application, then define a subclass of :class:`AppConfig` there.
 
 When :setting:`INSTALLED_APPS` contains the dotted path to an application
-module, Django checks for a ``default_app_config`` variable in that module.
+module, by default, if Django finds exactly one :class:`AppConfig` subclass in
+the ``apps.py`` submodule, it uses that configuration for the application. This
+behavior may be disabled by setting :attr:`AppConfig.default` to ``False``.
 
-If it's defined, it's the dotted path to the :class:`~django.apps.AppConfig`
-subclass for that application.
+If the ``apps.py`` module contains more than one :class:`AppConfig` subclass,
+Django will look for a single one where :attr:`AppConfig.default` is ``True``.
 
-If there is no ``default_app_config``, Django uses the base
-:class:`~django.apps.AppConfig` class.
+If no :class:`AppConfig` subclass is found, the base :class:`AppConfig` class
+will be used.
 
-``default_app_config`` allows applications that predate Django 1.7 such as
-``django.contrib.admin`` to opt-in to :class:`~django.apps.AppConfig` features
-without requiring users to update their :setting:`INSTALLED_APPS`.
+Alternatively, :setting:`INSTALLED_APPS` may contain the dotted path to a
+configuration class to specify it explicitly::
 
-New applications should avoid ``default_app_config``. Instead they should
-require the dotted path to the appropriate :class:`~django.apps.AppConfig`
-subclass to be configured explicitly in :setting:`INSTALLED_APPS`.
+    INSTALLED_APPS = [
+        ...
+        'polls.apps.PollsAppConfig',
+        ...
+    ]
 
 For application authors
 -----------------------
@@ -90,32 +93,24 @@ would provide a proper name for the admin::
         name = 'rock_n_roll'
         verbose_name = "Rock ’n’ roll"
 
-You can make your application load this :class:`~django.apps.AppConfig`
-subclass by default as follows::
-
-    # rock_n_roll/__init__.py
-
-    default_app_config = 'rock_n_roll.apps.RockNRollConfig'
+``RockNRollConfig`` will be loaded automatically when :setting:`INSTALLED_APPS`
+contains ``'rock_n_roll'``. If you need to prevent this, set
+:attr:`~AppConfig.default` to ``False`` in the class definition.
 
-That will cause ``RockNRollConfig`` to be used when :setting:`INSTALLED_APPS`
-contains ``'rock_n_roll'``. This allows you to make use of
-:class:`~django.apps.AppConfig` features without requiring your users to update
-their :setting:`INSTALLED_APPS` setting. Besides this use case, it's best to
-avoid using ``default_app_config`` and instead specify the app config class in
-:setting:`INSTALLED_APPS` as described next.
+You can provide several :class:`AppConfig` subclasses with different behaviors.
+To tell Django which one to use by default, set :attr:`~AppConfig.default` to
+``True`` in its definition. If your users want to pick a non-default
+configuration, they must replace ``'rock_n_roll'`` with the dotted path to that
+specific class in their :setting:`INSTALLED_APPS` setting.
 
-You can also tell your users to put ``'rock_n_roll.apps.RockNRollConfig'`` in
-their :setting:`INSTALLED_APPS` setting. You can even provide several different
-:class:`~django.apps.AppConfig` subclasses with different behaviors and allow
-your users to choose one via their :setting:`INSTALLED_APPS` setting.
+The :attr:`AppConfig.name` attribute tells Django which application this
+configuration applies to. You can define any other attribute documented in the
+:class:`~django.apps.AppConfig` API reference.
 
-The recommended convention is to put the configuration class in a submodule of
-the application called ``apps``. However, this isn't enforced by Django.
-
-You must include the :attr:`~django.apps.AppConfig.name` attribute for Django
-to determine which application this configuration applies to. You can define
-any attributes documented in the :class:`~django.apps.AppConfig` API
-reference.
+:class:`AppConfig` subclasses may be defined anywhere. The ``apps.py``
+convention merely allows Django to load them automatically when
+:setting:`INSTALLED_APPS` contains the path to an application module rather
+than the path to a configuration class.
 
 .. note::
 
@@ -126,6 +121,11 @@ reference.
 
         from django.apps import apps as django_apps
 
+.. versionchanged:: 3.2
+
+    In previous versions, a ``default_app_config`` variable in the application
+    module was used to identify the default application configuration class.
+
 For application users
 ---------------------
 
@@ -147,8 +147,13 @@ configuration::
         # ...
     ]
 
-Again, defining project-specific configuration classes in a submodule called
-``apps`` is a convention, not a requirement.
+This example shows project-specific configuration classes located in a
+submodule called ``apps.py``. This is a convention, not a requirement.
+:class:`AppConfig` subclasses may be defined anywhere.
+
+In this situation, :setting:`INSTALLED_APPS` must contain the dotted path to
+the configuration class because it lives outside of an application and thus
+cannot be automatically detected.
 
 Application configuration
 =========================
@@ -198,6 +203,22 @@ Configurable attributes
     required; for instance if the app package is a `namespace package`_ with
     multiple paths.
 
+.. attribute:: AppConfig.default
+
+    .. versionadded:: 3.2
+
+    Set this attribute to ``False`` to prevent Django from selecting a
+    configuration class automatically. This is useful when ``apps.py`` defines
+    only one :class:`AppConfig` subclass but you don't want Django to use it by
+    default.
+
+    Set this attribute to ``True`` to tell Django to select a configuration
+    class automatically. This is useful when ``apps.py`` defines more than one
+    :class:`AppConfig` subclass and you want Django to use one of them by
+    default.
+
+    By default, this attribute isn't set.
+
 Read-only attributes
 --------------------
 
@@ -412,7 +433,8 @@ processes all applications in the order of :setting:`INSTALLED_APPS`.
 
    If it's an application configuration class, Django imports the root package
    of the application, defined by its :attr:`~AppConfig.name` attribute. If
-   it's a Python package, Django creates a default application configuration.
+   it's a Python package, Django looks for an application configuration in an
+   ``apps.py`` submodule, or else creates a default application configuration.
 
    *At this stage, your code shouldn't import any models!*
 
diff --git a/docs/releases/3.2.txt b/docs/releases/3.2.txt
index 2f3045f971..5e75f497f4 100644
--- a/docs/releases/3.2.txt
+++ b/docs/releases/3.2.txt
@@ -31,6 +31,28 @@ officially support the latest release of each series.
 What's new in Django 3.2
 ========================
 
+Automatic :class:`~django.apps.AppConfig` discovery
+---------------------------------------------------
+
+Most pluggable applications define an :class:`~django.apps.AppConfig` subclass
+in an ``apps.py`` submodule. Many define a ``default_app_config`` variable
+pointing to this class in their ``__init__.py``.
+
+When the ``apps.py`` submodule exists and defines a single
+:class:`~django.apps.AppConfig` subclass, Django now uses that configuration
+automatically, so you can remove ``default_app_config``.
+
+``default_app_config`` made it possible to declare only the application's path
+in :setting:`INSTALLED_APPS` (e.g. ``'django.contrib.admin'``) rather than the
+app config's path (e.g. ``'django.contrib.admin.apps.AdminConfig'``). It was
+introduced for backwards-compatibility with the former style, with the intent
+to switch the ecosystem to the latter, but the switch didn't happen.
+
+With automatic ``AppConfig`` discovery, ``default_app_config`` is no longer
+needed. As a consequence, it's deprecated.
+
+See :ref:`configuring-applications-ref` for full details.
+
 Minor features
 --------------
 
@@ -387,6 +409,12 @@ Miscellaneous
   :attr:`~django.db.models.Model._default_manager` to check that related
   instances exist.
 
+* When an application defines an :class:`~django.apps.AppConfig` subclass in
+  an ``apps.py`` submodule, Django now uses this configuration automatically,
+  even if it isn't enabled with ``default_app_config``. Set ``default = False``
+  in the :class:`~django.apps.AppConfig` subclass if you need to prevent this
+  behavior. See :ref:`whats-new-3.2` for more details.
+
 .. _deprecated-features-3.2:
 
 Features deprecated in 3.2
@@ -408,3 +436,7 @@ Miscellaneous
   ``allowlist`` instead of ``whitelist``, and ``domain_allowlist`` instead of
   ``domain_whitelist``. You may need to rename ``whitelist`` in existing
   migrations.
+
+* The ``default_app_config`` application configuration variable is deprecated,
+  due to the now automatic ``AppConfig`` discovery. See :ref:`whats-new-3.2`
+  for more details.