Skip to content

Documented django.setup(). #2609

Closed
wants to merge 1 commit into from

3 participants

@aaugustin
Django member

No description provided.

@ericholscher ericholscher and 1 other commented on an outdated diff Apr 26, 2014
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.
@ericholscher
ericholscher added a note Apr 26, 2014

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

@aaugustin
Django member
aaugustin added a note Apr 26, 2014

"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
@ericholscher ericholscher commented on an outdated diff Apr 26, 2014
docs/ref/applications.txt
+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.
@ericholscher
ericholscher added a note Apr 26, 2014

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

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

@timgraham timgraham commented on an outdated diff Apr 26, 2014
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
Django member
timgraham added a note Apr 26, 2014

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
@timgraham timgraham commented on an outdated diff Apr 26, 2014
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
Django member
timgraham added a note Apr 26, 2014

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
@timgraham timgraham commented on an outdated diff Apr 26, 2014
docs/ref/applications.txt
+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
Django member
timgraham added a note Apr 26, 2014

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
@timgraham timgraham and 1 other commented on an outdated diff Apr 26, 2014
docs/ref/applications.txt
+
+ 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
Django member
timgraham added a note Apr 26, 2014

shouldn't recursively import any models.?

@aaugustin
Django member
aaugustin added a note Apr 26, 2014

"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
@timgraham timgraham commented on an outdated diff Apr 26, 2014
docs/ref/applications.txt
+#. 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
Django member
timgraham added a note Apr 26, 2014

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
Django member

Merged.

@aaugustin aaugustin closed this Apr 26, 2014
@aaugustin aaugustin deleted the aaugustin:setup-docs branch Apr 26, 2014
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.