mirror of
https://github.com/django/django.git
synced 2024-12-24 18:16:19 +00:00
Documented django.setup().
Thanks Eric Holscher and Tim Graham for the review.
This commit is contained in:
parent
2bcb8bfc8d
commit
58ed387db3
@ -307,13 +307,71 @@ Application registry
|
|||||||
:exc:`ValueError` when called with a single argument that doesn't contain
|
:exc:`ValueError` when called with a single argument that doesn't contain
|
||||||
exactly one dot.
|
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:
|
.. _applications-troubleshooting:
|
||||||
|
|
||||||
Troubleshooting
|
Troubleshooting
|
||||||
===============
|
---------------
|
||||||
|
|
||||||
Django loads application configurations and models as soon as it starts. Here
|
Here are some common problems that you may encounter during initialization:
|
||||||
are some common problems you may encounter:
|
|
||||||
|
|
||||||
* ``RuntimeError: App registry isn't ready yet.`` This happens when importing
|
* ``RuntimeError: App registry isn't ready yet.`` This happens when importing
|
||||||
an application configuration or a models module triggers code that depends
|
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
|
the :setting:`AUTH_USER_MODEL` setting to reference the User model at import
|
||||||
time.
|
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
|
* ``ImportError: cannot import name ...`` This happens if the import sequence
|
||||||
ends up in a loop.
|
ends up in a loop.
|
||||||
|
|
||||||
|
@ -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 sets the :envvar:`DJANGO_SETTINGS_MODULE` environment variable so that
|
||||||
it points to your project's ``settings.py`` file.
|
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
|
.. 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
|
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
|
Django via its ``setup.py`` utility. If it's not on your path, you can find it
|
||||||
|
Loading…
Reference in New Issue
Block a user