<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Applications — Django 1.8.19 documentation</title>
<link rel="stylesheet" href="../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.8.19',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="top" title="Django 1.8.19 documentation" href="../contents.html" />
<link rel="up" title="API Reference" href="index.html" />
<link rel="next" title="System check framework" href="checks.html" />
<link rel="prev" title="API Reference" href="index.html" />
<script type="text/javascript" src="../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body role="document">
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../index.html">Django 1.8.19 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../index.html">Home</a> |
<a title="Table of contents" href="../contents.html">Table of contents</a> |
<a title="Global index" href="../genindex.html">Index</a> |
<a title="Module index" href="../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="index.html" title="API Reference">previous</a>
|
<a href="index.html" title="API Reference" accesskey="U">up</a>
|
<a href="checks.html" title="System check framework">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="ref-applications">
<div class="section" id="s-module-django.apps">
<span id="s-applications"></span><span id="module-django.apps"></span><span id="applications"></span><h1>Applications<a class="headerlink" href="#module-django.apps" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<p>Django contains a registry of installed applications that stores configuration
and provides introspection. It also maintains a list of available <a class="reference internal" href="../topics/db/models.html"><span class="doc">models</span></a>.</p>
<p>This registry is simply called <a class="reference internal" href="#django.apps.apps" title="django.apps.apps"><code class="xref py py-attr docutils literal"><span class="pre">apps</span></code></a> and it’s available in
<a class="reference internal" href="#module-django.apps" title="django.apps"><code class="xref py py-mod docutils literal"><span class="pre">django.apps</span></code></a>:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span> <span class="nn">django.apps</span> <span class="k">import</span> <span class="n">apps</span>
<span class="gp">>>> </span><span class="n">apps</span><span class="o">.</span><span class="n">get_app_config</span><span class="p">(</span><span class="s1">'admin'</span><span class="p">)</span><span class="o">.</span><span class="n">verbose_name</span>
<span class="go">'Admin'</span>
</pre></div>
</div>
<div class="section" id="s-projects-and-applications">
<span id="projects-and-applications"></span><h2>Projects and applications<a class="headerlink" href="#projects-and-applications" title="Permalink to this headline">¶</a></h2>
<p>Django has historically used the term <strong>project</strong> to describe an installation
of Django. A project is defined primarily by a settings module.</p>
<p>The term <strong>application</strong> describes a Python package that provides some set of
features. Applications may be reused in various projects.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This terminology is somewhat confusing these days as it became common to
use the phrase “web app” to describe what equates to a Django project.</p>
</div>
<p>Applications include some combination of models, views, templates, template
tags, static files, URLs, middleware, etc. They’re generally wired into
projects with the <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> setting and optionally with other
mechanisms such as URLconfs, the <a class="reference internal" href="settings.html#std:setting-MIDDLEWARE_CLASSES"><code class="xref std std-setting docutils literal"><span class="pre">MIDDLEWARE_CLASSES</span></code></a> setting, or
template inheritance.</p>
<p>It is important to understand that a Django application is just a set of code
that interacts with various parts of the framework. There’s no such thing as
an <code class="docutils literal"><span class="pre">Application</span></code> object. However, there’s a few places where Django needs to
interact with installed applications, mainly for configuration and also for
introspection. That’s why the application registry maintains metadata in an
<a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> instance for each installed application.</p>
</div>
<div class="section" id="s-configuring-applications">
<span id="configuring-applications"></span><h2>Configuring applications<a class="headerlink" href="#configuring-applications" title="Permalink to this headline">¶</a></h2>
<p>To configure an application, subclass <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> and put
the dotted path to that subclass in <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</p>
<p>When <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> simply contains the dotted path to an
application module, Django checks for a <code class="docutils literal"><span class="pre">default_app_config</span></code> variable in
that module.</p>
<p>If it’s defined, it’s the dotted path to the <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a>
subclass for that application.</p>
<p>If there is no <code class="docutils literal"><span class="pre">default_app_config</span></code>, Django uses the base
<a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> class.</p>
<p><code class="docutils literal"><span class="pre">default_app_config</span></code> allows applications that predate Django 1.7 such as
<code class="docutils literal"><span class="pre">django.contrib.admin</span></code> to opt-in to <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> features
without requiring users to update their <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</p>
<p>New applications should avoid <code class="docutils literal"><span class="pre">default_app_config</span></code>. Instead they should
require the dotted path to the appropriate <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a>
subclass to be configured explicitly in <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</p>
<div class="section" id="s-for-application-authors">
<span id="for-application-authors"></span><h3>For application authors<a class="headerlink" href="#for-application-authors" title="Permalink to this headline">¶</a></h3>
<p>If you’re creating a pluggable app called “Rock ’n’ roll”, here’s how you
would provide a proper name for the admin:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># rock_n_roll/apps.py</span>
<span class="kn">from</span> <span class="nn">django.apps</span> <span class="k">import</span> <span class="n">AppConfig</span>
<span class="k">class</span> <span class="nc">RockNRollConfig</span><span class="p">(</span><span class="n">AppConfig</span><span class="p">):</span>
<span class="n">name</span> <span class="o">=</span> <span class="s1">'rock_n_roll'</span>
<span class="n">verbose_name</span> <span class="o">=</span> <span class="s2">"Rock ’n’ roll"</span>
</pre></div>
</div>
<p>You can make your application load this <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a>
subclass by default as follows:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># rock_n_roll/__init__.py</span>
<span class="n">default_app_config</span> <span class="o">=</span> <span class="s1">'rock_n_roll.apps.RockNRollConfig'</span>
</pre></div>
</div>
<p>That will cause <code class="docutils literal"><span class="pre">RockNRollConfig</span></code> to be used when <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>
just contains <code class="docutils literal"><span class="pre">'rock_n_roll'</span></code>. This allows you to make use of
<a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> features without requiring your users to
update their <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> setting.</p>
<p>Of course, you can also tell your users to put
<code class="docutils literal"><span class="pre">'rock_n_roll.apps.RockNRollConfig'</span></code> in their <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>
setting. You can even provide several different
<a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> subclasses with different behaviors and allow
your users to choose one via their <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> setting.</p>
<p>The recommended convention is to put the configuration class in a submodule of
the application called <code class="docutils literal"><span class="pre">apps</span></code>. However, this isn’t enforced by Django.</p>
<p>You must include the <a class="reference internal" href="#django.apps.AppConfig.name" title="django.apps.AppConfig.name"><code class="xref py py-attr docutils literal"><span class="pre">name</span></code></a> attribute for Django
to determine which application this configuration applies to. You can define
any attributes documented in the <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> API
reference.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>If your code imports the application registry in an application’s
<code class="docutils literal"><span class="pre">__init__.py</span></code>, the name <code class="docutils literal"><span class="pre">apps</span></code> will clash with the <code class="docutils literal"><span class="pre">apps</span></code> submodule.
The best practice is to move that code to a submodule and import it. A
workaround is to import the registry under a different name:</p>
<div class="last highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.apps</span> <span class="k">import</span> <span class="n">apps</span> <span class="k">as</span> <span class="n">django_apps</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="s-for-application-users">
<span id="for-application-users"></span><h3>For application users<a class="headerlink" href="#for-application-users" title="Permalink to this headline">¶</a></h3>
<p>If you’re using “Rock ’n’ roll” in a project called <code class="docutils literal"><span class="pre">anthology</span></code>, but you
want it to show up as “Gypsy jazz” instead, you can provide your own
configuration:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="c1"># anthology/apps.py</span>
<span class="kn">from</span> <span class="nn">rock_n_roll.apps</span> <span class="k">import</span> <span class="n">RockNRollConfig</span>
<span class="k">class</span> <span class="nc">GypsyJazzConfig</span><span class="p">(</span><span class="n">RockNRollConfig</span><span class="p">):</span>
<span class="n">verbose_name</span> <span class="o">=</span> <span class="s2">"Gypsy jazz"</span>
<span class="c1"># anthology/settings.py</span>
<span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">[</span>
<span class="s1">'anthology.apps.GypsyJazzConfig'</span><span class="p">,</span>
<span class="c1"># ...</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Again, defining project-specific configuration classes in a submodule called
<code class="docutils literal"><span class="pre">apps</span></code> is a convention, not a requirement.</p>
</div>
</div>
<div class="section" id="s-application-configuration">
<span id="application-configuration"></span><h2>Application configuration<a class="headerlink" href="#application-configuration" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="django.apps.AppConfig">
<em class="property">class </em><code class="descname">AppConfig</code><a class="reference internal" href="../_modules/django/apps/config.html#AppConfig"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.apps.AppConfig" title="Permalink to this definition">¶</a></dt>
<dd><p>Application configuration objects store metadata for an application. Some
attributes can be configured in <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a>
subclasses. Others are set by Django and read-only.</p>
</dd></dl>
<div class="section" id="s-configurable-attributes">
<span id="configurable-attributes"></span><h3>Configurable attributes<a class="headerlink" href="#configurable-attributes" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.apps.AppConfig.name">
<code class="descclassname">AppConfig.</code><code class="descname">name</code><a class="headerlink" href="#django.apps.AppConfig.name" title="Permalink to this definition">¶</a></dt>
<dd><p>Full Python path to the application, e.g. <code class="docutils literal"><span class="pre">'django.contrib.admin'</span></code>.</p>
<p>This attribute defines which application the configuration applies to. It
must be set in all <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> subclasses.</p>
<p>It must be unique across a Django project.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.apps.AppConfig.label">
<code class="descclassname">AppConfig.</code><code class="descname">label</code><a class="headerlink" href="#django.apps.AppConfig.label" title="Permalink to this definition">¶</a></dt>
<dd><p>Short name for the application, e.g. <code class="docutils literal"><span class="pre">'admin'</span></code></p>
<p>This attribute allows relabeling an application when two applications
have conflicting labels. It defaults to the last component of <code class="docutils literal"><span class="pre">name</span></code>.
It should be a valid Python identifier.</p>
<p>It must be unique across a Django project.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.apps.AppConfig.verbose_name">
<code class="descclassname">AppConfig.</code><code class="descname">verbose_name</code><a class="headerlink" href="#django.apps.AppConfig.verbose_name" title="Permalink to this definition">¶</a></dt>
<dd><p>Human-readable name for the application, e.g. “Administration”.</p>
<p>This attribute defaults to <code class="docutils literal"><span class="pre">label.title()</span></code>.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.apps.AppConfig.path">
<code class="descclassname">AppConfig.</code><code class="descname">path</code><a class="headerlink" href="#django.apps.AppConfig.path" title="Permalink to this definition">¶</a></dt>
<dd><p>Filesystem path to the application directory, e.g.
<code class="docutils literal"><span class="pre">'/usr/lib/python3.4/dist-packages/django/contrib/admin'</span></code>.</p>
<p>In most cases, Django can automatically detect and set this, but you can
also provide an explicit override as a class attribute on your
<a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> subclass. In a few situations this is
required; for instance if the app package is a <a class="reference internal" href="#namespace-package">namespace package</a> with
multiple paths.</p>
</dd></dl>
</div>
<div class="section" id="s-read-only-attributes">
<span id="read-only-attributes"></span><h3>Read-only attributes<a class="headerlink" href="#read-only-attributes" title="Permalink to this headline">¶</a></h3>
<dl class="attribute">
<dt id="django.apps.AppConfig.module">
<code class="descclassname">AppConfig.</code><code class="descname">module</code><a class="headerlink" href="#django.apps.AppConfig.module" title="Permalink to this definition">¶</a></dt>
<dd><p>Root module for the application, e.g. <code class="docutils literal"><span class="pre"><module</span> <span class="pre">'django.contrib.admin'</span> <span class="pre">from</span>
<span class="pre">'django/contrib/admin/__init__.pyc'></span></code>.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.apps.AppConfig.models_module">
<code class="descclassname">AppConfig.</code><code class="descname">models_module</code><a class="headerlink" href="#django.apps.AppConfig.models_module" title="Permalink to this definition">¶</a></dt>
<dd><p>Module containing the models, e.g. <code class="docutils literal"><span class="pre"><module</span> <span class="pre">'django.contrib.admin.models'</span>
<span class="pre">from</span> <span class="pre">'django/contrib/admin/models.pyc'></span></code>.</p>
<p>It may be <code class="docutils literal"><span class="pre">None</span></code> if the application doesn’t contain a <code class="docutils literal"><span class="pre">models</span></code> module.
Note that the database related signals such as
<a class="reference internal" href="signals.html#django.db.models.signals.pre_migrate" title="django.db.models.signals.pre_migrate"><code class="xref py py-data docutils literal"><span class="pre">pre_migrate</span></code></a> and
<a class="reference internal" href="signals.html#django.db.models.signals.post_migrate" title="django.db.models.signals.post_migrate"><code class="xref py py-data docutils literal"><span class="pre">post_migrate</span></code></a>
are only emitted for applications that have a <code class="docutils literal"><span class="pre">models</span></code> module.</p>
</dd></dl>
</div>
<div class="section" id="s-methods">
<span id="methods"></span><h3>Methods<a class="headerlink" href="#methods" title="Permalink to this headline">¶</a></h3>
<dl class="method">
<dt id="django.apps.AppConfig.get_models">
<code class="descclassname">AppConfig.</code><code class="descname">get_models</code>()<a class="reference internal" href="../_modules/django/apps/config.html#AppConfig.get_models"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.apps.AppConfig.get_models" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an iterable of <a class="reference internal" href="models/instances.html#django.db.models.Model" title="django.db.models.Model"><code class="xref py py-class docutils literal"><span class="pre">Model</span></code></a> classes for this
application.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.AppConfig.get_model">
<code class="descclassname">AppConfig.</code><code class="descname">get_model</code>(<em>model_name</em>)<a class="reference internal" href="../_modules/django/apps/config.html#AppConfig.get_model"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.apps.AppConfig.get_model" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <a class="reference internal" href="models/instances.html#django.db.models.Model" title="django.db.models.Model"><code class="xref py py-class docutils literal"><span class="pre">Model</span></code></a> with the given
<code class="docutils literal"><span class="pre">model_name</span></code>. Raises <code class="xref py py-exc docutils literal"><span class="pre">LookupError</span></code> if no such model exists in this
application. <code class="docutils literal"><span class="pre">model_name</span></code> is case-insensitive.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.AppConfig.ready">
<code class="descclassname">AppConfig.</code><code class="descname">ready</code>()<a class="reference internal" href="../_modules/django/apps/config.html#AppConfig.ready"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.apps.AppConfig.ready" title="Permalink to this definition">¶</a></dt>
<dd><p>Subclasses can override this method to perform initialization tasks such
as registering signals. It is called as soon as the registry is fully
populated.</p>
<p>You cannot import models in modules that define application configuration
classes, but you can use <a class="reference internal" href="#django.apps.AppConfig.get_model" title="django.apps.AppConfig.get_model"><code class="xref py py-meth docutils literal"><span class="pre">get_model()</span></code></a> to access a model class by
name, like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">ready</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="n">MyModel</span> <span class="o">=</span> <span class="bp">self</span><span class="o">.</span><span class="n">get_model</span><span class="p">(</span><span class="s1">'MyModel'</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Although you can access model classes as described above, avoid
interacting with the database in your <a class="reference internal" href="#django.apps.AppConfig.ready" title="django.apps.AppConfig.ready"><code class="xref py py-meth docutils literal"><span class="pre">ready()</span></code></a> implementation.
This includes model methods that execute queries
(<a class="reference internal" href="models/instances.html#django.db.models.Model.save" title="django.db.models.Model.save"><code class="xref py py-meth docutils literal"><span class="pre">save()</span></code></a>,
<a class="reference internal" href="models/instances.html#django.db.models.Model.delete" title="django.db.models.Model.delete"><code class="xref py py-meth docutils literal"><span class="pre">delete()</span></code></a>, manager methods etc.), and
also raw SQL queries via <code class="docutils literal"><span class="pre">django.db.connection</span></code>. Your
<a class="reference internal" href="#django.apps.AppConfig.ready" title="django.apps.AppConfig.ready"><code class="xref py py-meth docutils literal"><span class="pre">ready()</span></code></a> method will run during startup of every management
command. For example, even though the test database configuration is
separate from the production settings, <code class="docutils literal"><span class="pre">manage.py</span> <span class="pre">test</span></code> would still
execute some queries against your <strong>production</strong> database!</p>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">In the usual initialization process, the <code class="docutils literal"><span class="pre">ready</span></code> method is only called
once by Django. But in some corner cases, particularly in tests which
are fiddling with installed applications, <code class="docutils literal"><span class="pre">ready</span></code> might be called more
than once. In that case, either write idempotent methods, or put a flag
on your <code class="docutils literal"><span class="pre">AppConfig</span></code> classes to prevent re-running code which should
be executed exactly one time.</p>
</div>
</dd></dl>
</div>
<div class="section" id="s-namespace-packages-as-apps-python-3-3">
<span id="s-namespace-package"></span><span id="namespace-packages-as-apps-python-3-3"></span><span id="namespace-package"></span><h3>Namespace packages as apps (Python 3.3+)<a class="headerlink" href="#namespace-packages-as-apps-python-3-3" title="Permalink to this headline">¶</a></h3>
<p>Python versions 3.3 and later support Python packages without an
<code class="docutils literal"><span class="pre">__init__.py</span></code> file. These packages are known as “namespace packages” and may
be spread across multiple directories at different locations on <code class="docutils literal"><span class="pre">sys.path</span></code>
(see <span class="target" id="index-0"></span><a class="pep reference external" href="https://www.python.org/dev/peps/pep-0420"><strong>PEP 420</strong></a>).</p>
<p>Django applications require a single base filesystem path where Django
(depending on configuration) will search for templates, static assets,
etc. Thus, namespace packages may only be Django applications if one of the
following is true:</p>
<ol class="arabic simple">
<li>The namespace package actually has only a single location (i.e. is not
spread across more than one directory.)</li>
<li>The <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> class used to configure the application
has a <a class="reference internal" href="#django.apps.AppConfig.path" title="django.apps.AppConfig.path"><code class="xref py py-attr docutils literal"><span class="pre">path</span></code></a> class attribute, which is the
absolute directory path Django will use as the single base path for the
application.</li>
</ol>
<p>If neither of these conditions is met, Django will raise
<a class="reference internal" href="exceptions.html#django.core.exceptions.ImproperlyConfigured" title="django.core.exceptions.ImproperlyConfigured"><code class="xref py py-exc docutils literal"><span class="pre">ImproperlyConfigured</span></code></a>.</p>
</div>
</div>
<div class="section" id="s-application-registry">
<span id="application-registry"></span><h2>Application registry<a class="headerlink" href="#application-registry" title="Permalink to this headline">¶</a></h2>
<dl class="data">
<dt id="django.apps.apps">
<code class="descname">apps</code><a class="headerlink" href="#django.apps.apps" title="Permalink to this definition">¶</a></dt>
<dd><p>The application registry provides the following public API. Methods that
aren’t listed below are considered private and may change without notice.</p>
</dd></dl>
<dl class="attribute">
<dt id="django.apps.apps.ready">
<code class="descclassname">apps.</code><code class="descname">ready</code><a class="headerlink" href="#django.apps.apps.ready" title="Permalink to this definition">¶</a></dt>
<dd><p>Boolean attribute that is set to <code class="docutils literal"><span class="pre">True</span></code> when the registry is fully
populated.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.apps.get_app_configs">
<code class="descclassname">apps.</code><code class="descname">get_app_configs</code>()<a class="headerlink" href="#django.apps.apps.get_app_configs" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an iterable of <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> instances.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.apps.get_app_config">
<code class="descclassname">apps.</code><code class="descname">get_app_config</code>(<em>app_label</em>)<a class="headerlink" href="#django.apps.apps.get_app_config" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns an <a class="reference internal" href="#django.apps.AppConfig" title="django.apps.AppConfig"><code class="xref py py-class docutils literal"><span class="pre">AppConfig</span></code></a> for the application with the
given <code class="docutils literal"><span class="pre">app_label</span></code>. Raises <code class="xref py py-exc docutils literal"><span class="pre">LookupError</span></code> if no such application
exists.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.apps.is_installed">
<code class="descclassname">apps.</code><code class="descname">is_installed</code>(<em>app_name</em>)<a class="headerlink" href="#django.apps.apps.is_installed" title="Permalink to this definition">¶</a></dt>
<dd><p>Checks whether an application with the given name exists in the registry.
<code class="docutils literal"><span class="pre">app_name</span></code> is the full name of the app, e.g. <code class="docutils literal"><span class="pre">'django.contrib.admin'</span></code>.</p>
</dd></dl>
<dl class="method">
<dt id="django.apps.apps.get_model">
<code class="descclassname">apps.</code><code class="descname">get_model</code>(<em>app_label</em>, <em>model_name</em>)<a class="headerlink" href="#django.apps.apps.get_model" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the <a class="reference internal" href="models/instances.html#django.db.models.Model" title="django.db.models.Model"><code class="xref py py-class docutils literal"><span class="pre">Model</span></code></a> with the given <code class="docutils literal"><span class="pre">app_label</span></code>
and <code class="docutils literal"><span class="pre">model_name</span></code>. As a shortcut, this method also accepts a single
argument in the form <code class="docutils literal"><span class="pre">app_label.model_name</span></code>. <code class="docutils literal"><span class="pre">model_name</span></code> is case-
insensitive.</p>
<p>Raises <code class="xref py py-exc docutils literal"><span class="pre">LookupError</span></code> if no such application or model exists. Raises
<code class="xref py py-exc docutils literal"><span class="pre">ValueError</span></code> when called with a single argument that doesn’t contain
exactly one dot.</p>
</dd></dl>
</div>
<div class="section" id="s-initialization-process">
<span id="initialization-process"></span><h2>Initialization process<a class="headerlink" href="#initialization-process" title="Permalink to this headline">¶</a></h2>
<div class="section" id="s-how-applications-are-loaded">
<span id="how-applications-are-loaded"></span><h3>How applications are loaded<a class="headerlink" href="#how-applications-are-loaded" title="Permalink to this headline">¶</a></h3>
<p>When Django starts, <a class="reference internal" href="#django.setup" title="django.setup"><code class="xref py py-func docutils literal"><span class="pre">django.setup()</span></code></a> is responsible for populating the
application registry.</p>
<dl class="function">
<dt id="django.setup">
<code class="descname">setup</code>()<a class="reference internal" href="../_modules/django.html#setup"><span class="viewcode-link">[source]</span></a><a class="headerlink" href="#django.setup" title="Permalink to this definition">¶</a></dt>
<dd><p>Configures Django by:</p>
<ul class="simple">
<li>Loading the settings.</li>
<li>Setting up logging.</li>
<li>Initializing the application registry.</li>
</ul>
<p>This function is called automatically:</p>
<ul class="simple">
<li>When running an HTTP server via Django’s WSGI support.</li>
<li>When invoking a management command.</li>
</ul>
<p>It must be called explicitly in other cases, for instance in plain Python
scripts.</p>
</dd></dl>
<p>The application registry is initialized in three stages. At each stage, Django
processes all applications in the order of <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</p>
<ol class="arabic">
<li><p class="first">First Django imports each item in <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>.</p>
<p>If it’s an application configuration class, Django imports the root package
of the application, defined by its <a class="reference internal" href="#django.apps.AppConfig.name" title="django.apps.AppConfig.name"><code class="xref py py-attr docutils literal"><span class="pre">name</span></code></a> attribute. If
it’s a Python package, Django creates a default application configuration.</p>
<p><em>At this stage, your code shouldn’t import any models!</em></p>
<p>In other words, your applications’ root packages and the modules that
define your application configuration classes shouldn’t import any models,
even indirectly.</p>
<p>Strictly speaking, Django allows importing models once their application
configuration is loaded. However, in order to avoid needless constraints on
the order of <a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a>, it’s strongly recommended not
import any models at this stage.</p>
<p>Once this stage completes, APIs that operate on application configurations
such as <a class="reference internal" href="#django.apps.apps.get_app_config" title="django.apps.apps.get_app_config"><code class="xref py py-meth docutils literal"><span class="pre">get_app_config()</span></code></a> become usable.</p>
</li>
<li><p class="first">Then Django attempts to import the <code class="docutils literal"><span class="pre">models</span></code> submodule of each application,
if there is one.</p>
<p>You must define or import all models in your application’s <code class="docutils literal"><span class="pre">models.py</span></code> or
<code class="docutils literal"><span class="pre">models/__init__.py</span></code>. Otherwise, the application registry may not be fully
populated at this point, which could cause the ORM to malfunction.</p>
<p>Once this stage completes, APIs that operate on models such as
<a class="reference internal" href="#django.apps.apps.get_model" title="django.apps.apps.get_model"><code class="xref py py-meth docutils literal"><span class="pre">get_model()</span></code></a> become usable.</p>
</li>
<li><p class="first">Finally Django runs the <a class="reference internal" href="#django.apps.AppConfig.ready" title="django.apps.AppConfig.ready"><code class="xref py py-meth docutils literal"><span class="pre">ready()</span></code></a> method of each application
configuration.</p>
</li>
</ol>
</div>
<div class="section" id="s-troubleshooting">
<span id="s-applications-troubleshooting"></span><span id="troubleshooting"></span><span id="applications-troubleshooting"></span><h3>Troubleshooting<a class="headerlink" href="#troubleshooting" title="Permalink to this headline">¶</a></h3>
<p>Here are some common problems that you may encounter during initialization:</p>
<ul>
<li><p class="first"><code class="docutils literal"><span class="pre">AppRegistryNotReady</span></code> This happens when importing an application
configuration or a models module triggers code that depends on the app
registry.</p>
<p>For example, <a class="reference internal" href="utils.html#django.utils.translation.ugettext" title="django.utils.translation.ugettext"><code class="xref py py-func docutils literal"><span class="pre">ugettext()</span></code></a> uses the app
registry to look up translation catalogs in applications. To translate at
import time, you need <a class="reference internal" href="utils.html#django.utils.translation.ugettext_lazy" title="django.utils.translation.ugettext_lazy"><code class="xref py py-func docutils literal"><span class="pre">ugettext_lazy()</span></code></a>
instead. (Using <a class="reference internal" href="utils.html#django.utils.translation.ugettext" title="django.utils.translation.ugettext"><code class="xref py py-func docutils literal"><span class="pre">ugettext()</span></code></a> would be a bug,
because the translation would happen at import time, rather than at each
request depending on the active language.)</p>
<p>Executing database queries with the ORM at import time in models modules
will also trigger this exception. The ORM cannot function properly until all
models are available.</p>
<p>Another common culprit is <a class="reference internal" href="../topics/auth/customizing.html#django.contrib.auth.get_user_model" title="django.contrib.auth.get_user_model"><code class="xref py py-func docutils literal"><span class="pre">django.contrib.auth.get_user_model()</span></code></a>. Use
the <a class="reference internal" href="settings.html#std:setting-AUTH_USER_MODEL"><code class="xref std std-setting docutils literal"><span class="pre">AUTH_USER_MODEL</span></code></a> setting to reference the User model at import
time.</p>
<p>This exception also happens if you forget to call <a class="reference internal" href="#django.setup" title="django.setup"><code class="xref py py-func docutils literal"><span class="pre">django.setup()</span></code></a> in
a standalone Python script.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">ImportError:</span> <span class="pre">cannot</span> <span class="pre">import</span> <span class="pre">name</span> <span class="pre">...</span></code> This happens if the import sequence
ends up in a loop.</p>
<p>To eliminate such problems, you should minimize dependencies between your
models modules and do as little work as possible at import time. To avoid
executing code at import time, you can move it into a function and cache its
results. The code will be executed when you first need its results. This
concept is known as “lazy evaluation”.</p>
</li>
<li><p class="first"><code class="docutils literal"><span class="pre">django.contrib.admin</span></code> automatically performs autodiscovery of <code class="docutils literal"><span class="pre">admin</span></code>
modules in installed applications. To prevent it, change your
<a class="reference internal" href="settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal"><span class="pre">INSTALLED_APPS</span></code></a> to contain
<code class="docutils literal"><span class="pre">'django.contrib.admin.apps.SimpleAdminConfig'</span></code> instead of
<code class="docutils literal"><span class="pre">'django.contrib.admin'</span></code>.</p>
</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Applications</a><ul>
<li><a class="reference internal" href="#projects-and-applications">Projects and applications</a></li>
<li><a class="reference internal" href="#configuring-applications">Configuring applications</a><ul>
<li><a class="reference internal" href="#for-application-authors">For application authors</a></li>
<li><a class="reference internal" href="#for-application-users">For application users</a></li>
</ul>
</li>
<li><a class="reference internal" href="#application-configuration">Application configuration</a><ul>
<li><a class="reference internal" href="#configurable-attributes">Configurable attributes</a></li>
<li><a class="reference internal" href="#read-only-attributes">Read-only attributes</a></li>
<li><a class="reference internal" href="#methods">Methods</a></li>
<li><a class="reference internal" href="#namespace-packages-as-apps-python-3-3">Namespace packages as apps (Python 3.3+)</a></li>
</ul>
</li>
<li><a class="reference internal" href="#application-registry">Application registry</a></li>
<li><a class="reference internal" href="#initialization-process">Initialization process</a><ul>
<li><a class="reference internal" href="#how-applications-are-loaded">How applications are loaded</a></li>
<li><a class="reference internal" href="#troubleshooting">Troubleshooting</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="index.html">API Reference</a></li>
<li>Next: <a href="checks.html">System check framework</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../index.html">Django 1.8.19 documentation</a>
<ul><li><a href="index.html">API Reference</a>
<ul><li>Applications</li></ul>
</li></ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/ref/applications.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Mar 10, 2018</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="index.html" title="API Reference">previous</a>
|
<a href="index.html" title="API Reference" accesskey="U">up</a>
|
<a href="checks.html" title="System check framework">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
