Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Documented django.setup(). #2609

Closed
wants to merge 1 commit into from

3 participants

@aaugustin
Owner

No description provided.

docs/ref/applications.txt
@@ -307,13 +307,61 @@ 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, among other things.

The "among other things" here is ambiguous. It should either be clarified, or removed.

@aaugustin Owner

"Removed" works for me. (It does three things that are listed just below; populating the app registry is the third and most complicated.)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/applications.txt
((26 lines not shown))
+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.
+
+ You should make sure that this stage can complete without importing any
+ models. Therefore your applications' root packages and the modules that
+ define your application configuration classes shouldn't import any models,
+ recursively.
+
+ Technically, you could import models once their application configuration
+ is loaded. However, in order to avoid creating constraints on the order of
+ :setting:`INSTALLED_APPS`, it's strongly recommended not import any models
+ at this stage.

Both of the above paragraphs are tackling the "don't import models here" problem. Perhaps this should be made bold, or to stand out in some other way for people who are skimming.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@ericholscher

:+1: -- Great to have this functionality explicitly defined. Added a few nits above, but in general it looks great.

docs/ref/applications.txt
@@ -307,13 +307,61 @@ 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, among other things.
+
+.. function:: django.setup()
+
+ Configures Django:
@timgraham Owner

I would say "Configures Django by" then "* Loading..." etc.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/applications.txt
@@ -307,13 +307,61 @@ 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, among other things.
+
+.. function:: django.setup()
@timgraham Owner

You will need to add something like ".. currentmodule:: django" so this doesn't live in the "django.apps" namespace (if you build the docs you'll see the links from the other pages don't work).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/applications.txt
((7 lines not shown))
+How applications are loaded
+---------------------------
+
+When Django starts, :func:`django.setup()` is responsible for populating the
+application registry, among other things.
+
+.. function:: django.setup()
+
+ Configures Django:
+
+ * Loads the settings.
+ * Sets up logging.
+ * Initializes the application registry.
+
+ This function is called automatically when running an HTTP server via WSGI
+ or a management command. It must be invoked explicitly in other cases, for
@timgraham Owner

consider something like "and before all management commands" (right now, a reader might think "via WSGI or a management command" are somehow related)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/applications.txt
((20 lines not shown))
+
+ This function is called automatically when running an HTTP server via WSGI
+ or a management command. It must be invoked explicitly in other cases, for
+ instance in plain Python scripts.
+
+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.
+
+ You should make sure that this stage can complete without importing any
+ models. Therefore your applications' root packages and the modules that
+ define your application configuration classes shouldn't import any models,
@timgraham Owner

shouldn't recursively import any models.?

@aaugustin Owner

"recursively" is confusing, no matter where I put it :-/

What aboun "shouldn't import any models, even indirectly" ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
docs/ref/applications.txt
((28 lines not shown))
+#. 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.
+
+ You should make sure that this stage can complete without importing any
+ models. Therefore your applications' root packages and the modules that
+ define your application configuration classes shouldn't import any models,
+ recursively.
+
+ Technically, you could import models once their application configuration
+ is loaded. However, in order to avoid creating constraints on the order of
+ :setting:`INSTALLED_APPS`, it's strongly recommended not import any models
+ at this stage.
+
+#. Then Django attemps to import the ``models`` submodule of each application,
@timgraham Owner

attempts*

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@aaugustin aaugustin Documented django.setup().
Thanks Eric Holscher and Tim Graham for the review.
24f32b6
@aaugustin
Owner

Merged.

@aaugustin aaugustin closed this
@aaugustin aaugustin deleted the aaugustin:setup-docs branch
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Apr 26, 2014
  1. @aaugustin

    Documented django.setup().

    aaugustin authored
    Thanks Eric Holscher and Tim Graham for the review.
This page is out of date. Refresh to see the latest.
Showing with 66 additions and 5 deletions.
  1. +64 −3 docs/ref/applications.txt
  2. +2 −2 docs/ref/django-admin.txt
View
67 docs/ref/applications.txt
@@ -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
4 docs/ref/django-admin.txt
@@ -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
Something went wrong with that request. Please try again.