Documented django.setup().

Thanks Eric Holscher and Tim Graham for the review.
This commit is contained in:
Aymeric Augustin 2014-04-26 18:32:17 +02:00
parent 2bcb8bfc8d
commit 58ed387db3
2 changed files with 66 additions and 5 deletions

View File

@ -307,13 +307,71 @@ Application registry
:exc:`ValueError` when called with a single argument that doesn't contain
exactly one dot.
Initialization process
======================
How applications are loaded
---------------------------
When Django starts, :func:`django.setup()` is responsible for populating the
application registry.
.. currentmodule:: django
.. function:: setup()
Configures Django by:
* Loading the settings.
* Setting up logging.
* Initializing the application registry.
This function is called automatically:
* When running an HTTP server via Django's WSGI support.
* When invoking a management command.
It must be called explicitly in other cases, for instance in plain Python
scripts.
.. currentmodule:: django.apps
The application registry is initialized in three stages. At each stage, Django
processes all applications in the order of :setting:`INSTALLED_APPS`.
#. First Django imports each item in :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.
*At this stage, your code shouldn't import any models!*
In other words, your applications' root packages and the modules that
define your application configuration classes shouldn't import any models,
even indirectly.
Strictly speaking, Django allows importing models once their application
configuration is loaded. However, in order to avoid needless constraints on
the order of :setting:`INSTALLED_APPS`, it's strongly recommended not
import any models at this stage.
#. Then Django attempts to import the ``models`` submodule of each application,
if there is one.
You must define or import all models in your application's ``models.py`` or
``models/__init__.py``. Otherwise, the application registry may not be fully
populated at this point, which could cause the ORM to malfunction.
#. Finally Django runs the :meth:`~AppConfig.ready()` method of each application
configuration.
.. _applications-troubleshooting:
Troubleshooting
===============
---------------
Django loads application configurations and models as soon as it starts. Here
are some common problems you may encounter:
Here are some common problems that you may encounter during initialization:
* ``RuntimeError: App registry isn't ready yet.`` This happens when importing
an application configuration or a models module triggers code that depends
@ -334,6 +392,9 @@ are some common problems you may encounter:
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.
* ``ImportError: cannot import name ...`` This happens if the import sequence
ends up in a loop.

View File

@ -14,11 +14,11 @@ two things for you before delegating to ``django-admin.py``:
* It sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
it points to your project's ``settings.py`` file.
* It calls ``django.setup()`` to initialize various internals of Django.
* It calls :func:`django.setup()` to initialize various internals of Django.
.. versionadded:: 1.7
``django.setup()`` didn't exist in previous versions of Django.
:func:`django.setup()` didn't exist in previous versions of Django.
The ``django-admin.py`` script should be on your system path if you installed
Django via its ``setup.py`` utility. If it's not on your path, you can find it