Fixed #31180 -- Configured applications automatically.

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::
+``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.
 
-    # rock_n_roll/__init__.py
+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.
 
-    default_app_config = 'rock_n_roll.apps.RockNRollConfig'
+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.
 
-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 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 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!*