diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/intro/tutorial01.txt | 9 | ||||
| -rw-r--r-- | docs/ref/applications.txt | 35 | ||||
| -rw-r--r-- | docs/ref/contrib/admin/index.txt | 51 | ||||
| -rw-r--r-- | docs/ref/contrib/gis/tutorial.txt | 2 | ||||
| -rw-r--r-- | docs/releases/1.7.txt | 17 | ||||
| -rw-r--r-- | docs/topics/auth/default.txt | 5 |
6 files changed, 74 insertions, 45 deletions
diff --git a/docs/intro/tutorial01.txt b/docs/intro/tutorial01.txt index 1bf11e47ae..16b2596da9 100644 --- a/docs/intro/tutorial01.txt +++ b/docs/intro/tutorial01.txt @@ -435,7 +435,7 @@ look like this: :filename: mysite/settings.py INSTALLED_APPS = ( - 'django.contrib.admin.apps.AdminConfig', + 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', @@ -444,13 +444,6 @@ look like this: 'polls', ) -.. admonition:: Doesn't match what you see? - - If you're seeing ``'django.contrib.admin'`` instead of - ``'django.contrib.admin.apps.AdminConfig'``, you're probably using a - version of Django that doesn't match this tutorial version. You'll want - to either switch to the older tutorial or the newer Django version. - Now Django knows to include the ``polls`` app. Let's run another command: .. code-block:: bash diff --git a/docs/ref/applications.txt b/docs/ref/applications.txt index e496f24487..33f885e416 100644 --- a/docs/ref/applications.txt +++ b/docs/ref/applications.txt @@ -49,9 +49,15 @@ Configuring applications To configure an application, subclass :class:`~django.apps.AppConfig` and put the dotted path to that subclass in :setting:`INSTALLED_APPS`. -Django uses the default :class:`~django.apps.AppConfig` class when -:setting:`INSTALLED_APPS` simply contains the dotted path to an application -module. +When :setting:`INSTALLED_APPS` simply contains the dotted path to an +application module, Django checks for a ``default_app_config`` variable in +that module. + +If it's defined, it's the dotted path to the :class:`~django.apps.AppConfig` +subclass for that application. + +If there is no ``default_app_config``, Django uses the base +:class:`~django.apps.AppConfig` class. For application authors ----------------------- @@ -67,8 +73,23 @@ would provide a proper name for the admin:: name = 'rock_n_roll' verbose_name = "Rock ’n’ roll" -You would then tell your users to add ``'rock_n_roll.apps.RockNRollConfig'`` -to their :setting:`INSTALLED_APPS`. +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' + +That will cause ``RockNRollConfig`` to be used when :setting:`INSTALLED_APPS` +just 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. + +Of course, 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. @@ -87,7 +108,7 @@ configuration:: # anthology/apps.py - from rock_n_roll.app import RockNRollConfig + from rock_n_roll.apps import RockNRollConfig class GypsyJazzConfig(RockNRollConfig): verbose_name = "Gypsy jazz" @@ -213,7 +234,7 @@ Application registry .. method:: apps.is_installed(app_name) 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'. + ``app_name`` is the full name of the app, e.g. ``'django.contrib.admin'``. Unlike :meth:`~django.apps.apps.get_app_config`, this method can be called safely at import time. If the registry is still being populated, it may diff --git a/docs/ref/contrib/admin/index.txt b/docs/ref/contrib/admin/index.txt index 7fc34c96de..281ea4674b 100644 --- a/docs/ref/contrib/admin/index.txt +++ b/docs/ref/contrib/admin/index.txt @@ -23,12 +23,7 @@ The admin is enabled in the default project template used by For reference, here are the requirements: -1. Add ``'django.contrib.admin.apps.AdminConfig'`` to your - :setting:`INSTALLED_APPS` setting. - - .. versionchanged:: 1.7 - - :setting:`INSTALLED_APPS` used to contain ``'django.contrib.admin'``. +1. Add ``'django.contrib.admin'`` to your :setting:`INSTALLED_APPS` setting. 2. The admin has four dependencies - :mod:`django.contrib.auth`, :mod:`django.contrib.contenttypes`, @@ -136,16 +131,23 @@ The register decorator Discovery of admin files ------------------------ -The admin needs to be instructed to look for ``admin.py`` files in your project. -The easiest solution is to put ``'django.contrib.admin.apps.AdminConfig'`` in -your :setting:`INSTALLED_APPS` setting. +When you put ``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` +setting, Django automatically looks for an ``admin`` module in each +application and imports it. .. class:: apps.AdminConfig .. versionadded:: 1.7 - This class calls :func:`~django.contrib.admin.autodiscover()` when Django - starts. + This is the default :class:`~django.apps.AppConfig` class for the admin. + It calls :func:`~django.contrib.admin.autodiscover()` when Django starts. + +.. class:: apps.SimpleAdminConfig + + .. versionadded:: 1.7 + + This class works like :class:`~django.contrib.admin.apps.AdminConfig`, + except it doesn't call :func:`~django.contrib.admin.autodiscover()`. .. function:: autodiscover @@ -155,13 +157,23 @@ your :setting:`INSTALLED_APPS` setting. .. versionchanged:: 1.7 Previous versions of Django recommended calling this function directly - in the URLconf. :class:`~django.contrib.admin.apps.AdminConfig` - replaces that mechanism and is more robust. + in the URLconf. As of Django 1.7 this isn't needed anymore. + :class:`~django.contrib.admin.apps.AdminConfig` takes care of running + the auto-discovery automatically. If you are using a custom ``AdminSite``, it is common to import all of the ``ModelAdmin`` subclasses into your code and register them to the custom -``AdminSite``. In that case, simply put ``'django.contrib.admin'`` in your -:setting:`INSTALLED_APPS` setting, as you don't need autodiscovery. +``AdminSite``. In that case, in order to disable auto-discovery, you should +put ``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of +``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` setting. + +.. versionchanged:: 1.7 + + In previous versions, the admin needed to be instructed to look for + ``admin.py`` files with :func:`~django.contrib.admin.autodiscover()`. + As of Django 1.7, auto-discovery is enabled by default and must be + explicitly disabled when it's undesirable. + ``ModelAdmin`` options ---------------------- @@ -2426,11 +2438,12 @@ In this example, we register the ``AdminSite`` instance (r'^myadmin/', include(admin_site.urls)), ) -Note that you don't need autodiscovery of ``admin`` modules when using your +Note that you may not want autodiscovery of ``admin`` modules when using your own ``AdminSite`` instance since you will likely be importing all the per-app -``admin`` modules in your ``myproject.admin`` module. This means you likely do -not need ``'django.contrib.admin.app.AdminConfig'`` in your -:setting:`INSTALLED_APPS` and can just use ``'django.contrib.admin'``. +``admin`` modules in your ``myproject.admin`` module. This means you need to +put ``'django.contrib.admin.app.SimpleAdminConfig'`` instead of +``'django.contrib.admin'`` in your :setting:`INSTALLED_APPS` setting. + Multiple admin sites in the same URLconf ---------------------------------------- diff --git a/docs/ref/contrib/gis/tutorial.txt b/docs/ref/contrib/gis/tutorial.txt index f3eeb64e59..ff27c9b6ec 100644 --- a/docs/ref/contrib/gis/tutorial.txt +++ b/docs/ref/contrib/gis/tutorial.txt @@ -115,7 +115,7 @@ In addition, modify the :setting:`INSTALLED_APPS` setting to include and ``world`` (your newly created application):: INSTALLED_APPS = ( - 'django.contrib.admin.apps.AdminConfig', + 'django.contrib.admin', 'django.contrib.auth', 'django.contrib.contenttypes', 'django.contrib.sessions', diff --git a/docs/releases/1.7.txt b/docs/releases/1.7.txt index df115c6c15..684daa988c 100644 --- a/docs/releases/1.7.txt +++ b/docs/releases/1.7.txt @@ -89,17 +89,14 @@ Improvements thus far include: * The name of applications can be customized in the admin with the :attr:`~django.apps.AppConfig.verbose_name` of application configurations. +* The admin automatically calls :func:`~django.contrib.admin.autodiscover()` + when Django starts. You can consequently remove this line from your + URLconf. + * Django imports all application configurations and models as soon as it starts, through a deterministic and straightforward process. This should make it easier to diagnose import issues such as import loops. -* The admin has an :class:`~django.contrib.admin.apps.AdminConfig` application - configuration class. When Django starts, this class takes care of calling - :func:`~django.contrib.admin.autodiscover()`. To use it, simply replace - ``'django.contrib.admin'`` in :setting:`INSTALLED_APPS` with - ``'django.contrib.admin.apps.AdminConfig'`` and remove - ``admin.autodiscover()`` from your URLconf. - New method on Field subclasses ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -698,6 +695,12 @@ regressions cannot be ruled out. You may encounter the following exceptions: results. The code will be executed when you first need its results. This concept is known as "lazy evaluation". +* ``django.contrib.admin`` will now automatically perform autodiscovery of + ``admin`` modules in installed applications. To prevent it, change your + :setting:`INSTALLED_APPS` to contain + ``'django.contrib.admin.apps.SimpleAdminConfig'`` instead of + ``'django.contrib.admin'``. + Standalone scripts ^^^^^^^^^^^^^^^^^^ diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index bfac4c922e..a721fb548c 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -67,9 +67,8 @@ Creating superusers ------------------- :djadmin:`manage.py migrate <migrate>` prompts you to create a superuser the -first time you run it with ``'django.contrib.auth'`` in your -:setting:`INSTALLED_APPS`. If you need to create a superuser at a later date, -you can use a command line utility:: +first time you run it with ``'django.contrib.auth'`` installed. If you need to +create a superuser at a later date, you can use a command line utility:: $ python manage.py createsuperuser --username=joe --email=joe@example.com |