<!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>System check framework — 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="Using Django" href="index.html" />
<link rel="next" title="“How-to” guides" href="../howto/index.html" />
<link rel="prev" title="Signals" href="signals.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 = "../ref/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="signals.html" title="Signals">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="../howto/index.html" title="&#8220;How-to&#8221; guides">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="topics-checks">
<div class="section" id="s-system-check-framework">
<span id="system-check-framework"></span><h1>System check framework<a class="headerlink" href="#system-check-framework" title="Permalink to this headline">¶</a></h1>
<div class="versionadded">
<span class="title">New in Django 1.7.</span> </div>
<span class="target" id="module-django.core.checks"></span><p>The system check framework is a set of static checks for validating Django
projects. It detects common problems and provides hints for how to fix them.
The framework is extensible so you can easily add your own checks.</p>
<p>Checks can be triggered explicitly via the <a class="reference internal" href="../ref/django-admin.html#django-admin-check"><code class="xref std std-djadmin docutils literal"><span class="pre">check</span></code></a> command. Checks are
triggered implicitly before most commands, including <a class="reference internal" href="../ref/django-admin.html#django-admin-runserver"><code class="xref std std-djadmin docutils literal"><span class="pre">runserver</span></code></a> and
<a class="reference internal" href="../ref/django-admin.html#django-admin-migrate"><code class="xref std std-djadmin docutils literal"><span class="pre">migrate</span></code></a>. For performance reasons, checks are not run as part of the
WSGI stack that is used in deployment. If you need to run system checks on your
deployment server, trigger them explicitly using <a class="reference internal" href="../ref/django-admin.html#django-admin-check"><code class="xref std std-djadmin docutils literal"><span class="pre">check</span></code></a>.</p>
<p>Serious errors will prevent Django commands (such as <a class="reference internal" href="../ref/django-admin.html#django-admin-runserver"><code class="xref std std-djadmin docutils literal"><span class="pre">runserver</span></code></a>) from
running at all. Minor problems are reported to the console. If you have inspected
the cause of a warning and are happy to ignore it, you can hide specific warnings
using the <a class="reference internal" href="../ref/settings.html#std:setting-SILENCED_SYSTEM_CHECKS"><code class="xref std std-setting docutils literal"><span class="pre">SILENCED_SYSTEM_CHECKS</span></code></a> setting in your project settings file.</p>
<p>A full list of all checks that can be raised by Django can be found in the
<a class="reference internal" href="../ref/checks.html"><span class="doc">System check reference</span></a>.</p>
<div class="section" id="s-writing-your-own-checks">
<span id="writing-your-own-checks"></span><h2>Writing your own checks<a class="headerlink" href="#writing-your-own-checks" title="Permalink to this headline">¶</a></h2>
<p>The framework is flexible and allows you to write functions that perform
any other kind of check you may require. The following is an example stub
check function:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.core.checks</span> <span class="k">import</span> <span class="n">Error</span><span class="p">,</span> <span class="n">register</span>
<span class="nd">@register</span><span class="p">()</span>
<span class="k">def</span> <span class="nf">example_check</span><span class="p">(</span><span class="n">app_configs</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">errors</span> <span class="o">=</span> <span class="p">[]</span>
<span class="c1"># ... your check logic here</span>
<span class="k">if</span> <span class="n">check_failed</span><span class="p">:</span>
<span class="n">errors</span><span class="o">.</span><span class="n">append</span><span class="p">(</span>
<span class="n">Error</span><span class="p">(</span>
<span class="s1">'an error'</span><span class="p">,</span>
<span class="n">hint</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">obj</span><span class="o">=</span><span class="n">checked_object</span><span class="p">,</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'myapp.E001'</span><span class="p">,</span>
<span class="p">)</span>
<span class="p">)</span>
<span class="k">return</span> <span class="n">errors</span>
</pre></div>
</div>
<p>The check function <em>must</em> accept an <code class="docutils literal"><span class="pre">app_configs</span></code> argument; this argument is
the list of applications that should be inspected. If None, the check must be
run on <em>all</em> installed apps in the project. The <code class="docutils literal"><span class="pre">**kwargs</span></code> argument is required
for future expansion.</p>
<div class="section" id="s-messages">
<span id="messages"></span><h3>Messages<a class="headerlink" href="#messages" title="Permalink to this headline">¶</a></h3>
<p>The function must return a list of messages. If no problems are found as a result
of the check, the check function must return an empty list.</p>
<p>The warnings and errors raised by the check method must be instances of
<a class="reference internal" href="../ref/checks.html#django.core.checks.CheckMessage" title="django.core.checks.CheckMessage"><code class="xref py py-class docutils literal"><span class="pre">CheckMessage</span></code></a>. An instance of
<a class="reference internal" href="../ref/checks.html#django.core.checks.CheckMessage" title="django.core.checks.CheckMessage"><code class="xref py py-class docutils literal"><span class="pre">CheckMessage</span></code></a> encapsulates a single reportable
error or warning. It also provides context and hints applicable to the
message, and a unique identifier that is used for filtering purposes.</p>
<p>The concept is very similar to messages from the <a class="reference internal" href="../ref/contrib/messages.html"><span class="doc">message framework</span></a> or the <a class="reference internal" href="logging.html"><span class="doc">logging framework</span></a>.
Messages are tagged with a <code class="docutils literal"><span class="pre">level</span></code> indicating the severity of the message.</p>
<p>There are also shortcuts to make creating messages with common levels easier.
When using these classes you can omit the <code class="docutils literal"><span class="pre">level</span></code> argument because it is
implied by the class name.</p>
<ul class="simple">
<li><a class="reference internal" href="../ref/checks.html#django.core.checks.Debug" title="django.core.checks.Debug"><code class="xref py py-class docutils literal"><span class="pre">Debug</span></code></a></li>
<li><a class="reference internal" href="../ref/checks.html#django.core.checks.Info" title="django.core.checks.Info"><code class="xref py py-class docutils literal"><span class="pre">Info</span></code></a></li>
<li><a class="reference internal" href="../ref/checks.html#django.core.checks.Warning" title="django.core.checks.Warning"><code class="xref py py-class docutils literal"><span class="pre">Warning</span></code></a></li>
<li><a class="reference internal" href="../ref/checks.html#django.core.checks.Error" title="django.core.checks.Error"><code class="xref py py-class docutils literal"><span class="pre">Error</span></code></a></li>
<li><a class="reference internal" href="../ref/checks.html#django.core.checks.Critical" title="django.core.checks.Critical"><code class="xref py py-class docutils literal"><span class="pre">Critical</span></code></a></li>
</ul>
</div>
<div class="section" id="s-registering-and-labeling-checks">
<span id="registering-and-labeling-checks"></span><h3>Registering and labeling checks<a class="headerlink" href="#registering-and-labeling-checks" title="Permalink to this headline">¶</a></h3>
<p>Lastly, your check function must be registered explicitly with system check
registry. Checks should be registered in a file that’s loaded when your
application is loaded; for example, in the <a class="reference internal" href="../ref/applications.html#django.apps.AppConfig.ready" title="django.apps.AppConfig.ready"><code class="xref py py-meth docutils literal"><span class="pre">AppConfig.ready()</span></code></a> method.</p>
<dl class="function">
<dt id="django.core.checks.register">
<code class="descname">register</code>(<em>*tags)(function</em>)<a class="headerlink" href="#django.core.checks.register" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<p>You can pass as many tags to <code class="docutils literal"><span class="pre">register</span></code> as you want in order to label your
check. Tagging checks is useful since it allows you to run only a certain
group of checks. For example, to register a compatibility check, you would
make the following call:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.core.checks</span> <span class="k">import</span> <span class="n">register</span><span class="p">,</span> <span class="n">Tags</span>
<span class="nd">@register</span><span class="p">(</span><span class="n">Tags</span><span class="o">.</span><span class="n">compatibility</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">my_check</span><span class="p">(</span><span class="n">app_configs</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="c1"># ... perform compatibility checks and collect errors</span>
<span class="k">return</span> <span class="n">errors</span>
</pre></div>
</div>
<div class="versionadded">
<span class="title">New in Django 1.8.</span> </div>
<p>You can register “deployment checks” that are only relevant to a production
settings file like this:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="nd">@register</span><span class="p">(</span><span class="n">Tags</span><span class="o">.</span><span class="n">security</span><span class="p">,</span> <span class="n">deploy</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="k">def</span> <span class="nf">my_check</span><span class="p">(</span><span class="n">app_configs</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="o">...</span>
</pre></div>
</div>
<p>These checks will only be run if the <a class="reference internal" href="../ref/django-admin.html#django-admin-option---deploy"><code class="xref std std-djadminopt docutils literal"><span class="pre">--deploy</span></code></a> option is passed to
the <a class="reference internal" href="../ref/django-admin.html#django-admin-check"><code class="xref std std-djadmin docutils literal"><span class="pre">check</span></code></a> command.</p>
<p>You can also use <code class="docutils literal"><span class="pre">register</span></code> as a function rather than a decorator by
passing a callable object (usually a function) as the first argument
to <code class="docutils literal"><span class="pre">register</span></code>.</p>
<p>The code below is equivalent to the code above:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">my_check</span><span class="p">(</span><span class="n">app_configs</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">register</span><span class="p">(</span><span class="n">my_check</span><span class="p">,</span> <span class="n">Tags</span><span class="o">.</span><span class="n">security</span><span class="p">,</span> <span class="n">deploy</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
</pre></div>
</div>
<div class="versionchanged">
<span class="title">Changed in Django 1.8:</span> <p>The ability to use register as a function was added.</p>
</div>
</div>
<div class="section" id="s-field-model-and-manager-checks">
<span id="s-field-checking"></span><span id="field-model-and-manager-checks"></span><span id="field-checking"></span><h3>Field, Model, and Manager checks<a class="headerlink" href="#field-model-and-manager-checks" title="Permalink to this headline">¶</a></h3>
<p>In some cases, you won’t need to register your check function – you can
piggyback on an existing registration.</p>
<p>Fields, models, and model managers all implement a <code class="docutils literal"><span class="pre">check()</span></code> method that is
already registered with the check framework. If you want to add extra checks,
you can extend the implementation on the base class, perform any extra
checks you need, and append any messages to those generated by the base class.
It’s recommended that you delegate each check to separate methods.</p>
<p>Consider an example where you are implementing a custom field named
<code class="docutils literal"><span class="pre">RangedIntegerField</span></code>. This field adds <code class="docutils literal"><span class="pre">min</span></code> and <code class="docutils literal"><span class="pre">max</span></code> arguments to the
constructor of <code class="docutils literal"><span class="pre">IntegerField</span></code>. You may want to add a check to ensure that users
provide a min value that is less than or equal to the max value. The following
code snippet shows how you can implement this check:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.core</span> <span class="k">import</span> <span class="n">checks</span>
<span class="kn">from</span> <span class="nn">django.db</span> <span class="k">import</span> <span class="n">models</span>
<span class="k">class</span> <span class="nc">RangedIntegerField</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">IntegerField</span><span class="p">):</span>
<span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="nb">min</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="nb">max</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="nb">super</span><span class="p">(</span><span class="n">RangedIntegerField</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">__init__</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">min</span> <span class="o">=</span> <span class="nb">min</span>
<span class="bp">self</span><span class="o">.</span><span class="n">max</span> <span class="o">=</span> <span class="nb">max</span>
<span class="k">def</span> <span class="nf">check</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="c1"># Call the superclass</span>
<span class="n">errors</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">RangedIntegerField</span><span class="p">,</span> <span class="bp">self</span><span class="p">)</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="c1"># Do some custom checks and add messages to `errors`:</span>
<span class="n">errors</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">_check_min_max_values</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">))</span>
<span class="c1"># Return all errors and warnings</span>
<span class="k">return</span> <span class="n">errors</span>
<span class="k">def</span> <span class="nf">_check_min_max_values</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="k">if</span> <span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">min</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span>
<span class="bp">self</span><span class="o">.</span><span class="n">max</span> <span class="ow">is</span> <span class="ow">not</span> <span class="kc">None</span> <span class="ow">and</span>
<span class="bp">self</span><span class="o">.</span><span class="n">min</span> <span class="o">></span> <span class="bp">self</span><span class="o">.</span><span class="n">max</span><span class="p">):</span>
<span class="k">return</span> <span class="p">[</span>
<span class="n">checks</span><span class="o">.</span><span class="n">Error</span><span class="p">(</span>
<span class="s1">'min greater than max.'</span><span class="p">,</span>
<span class="n">hint</span><span class="o">=</span><span class="s1">'Decrease min or increase max.'</span><span class="p">,</span>
<span class="n">obj</span><span class="o">=</span><span class="bp">self</span><span class="p">,</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'myapp.E001'</span><span class="p">,</span>
<span class="p">)</span>
<span class="p">]</span>
<span class="c1"># When no error, return an empty list</span>
<span class="k">return</span> <span class="p">[]</span>
</pre></div>
</div>
<p>If you wanted to add checks to a model manager, you would take the same
approach on your subclass of <a class="reference internal" href="db/managers.html#django.db.models.Manager" title="django.db.models.Manager"><code class="xref py py-class docutils literal"><span class="pre">Manager</span></code></a>.</p>
<p>If you want to add a check to a model class, the approach is <em>almost</em> the same:
the only difference is that the check is a classmethod, not an instance method:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">MyModel</span><span class="p">(</span><span class="n">models</span><span class="o">.</span><span class="n">Model</span><span class="p">):</span>
<span class="nd">@classmethod</span>
<span class="k">def</span> <span class="nf">check</span><span class="p">(</span><span class="n">cls</span><span class="p">,</span> <span class="o">**</span><span class="n">kwargs</span><span class="p">):</span>
<span class="n">errors</span> <span class="o">=</span> <span class="nb">super</span><span class="p">(</span><span class="n">MyModel</span><span class="p">,</span> <span class="n">cls</span><span class="p">)</span><span class="o">.</span><span class="n">check</span><span class="p">(</span><span class="o">**</span><span class="n">kwargs</span><span class="p">)</span>
<span class="c1"># ... your own checks ...</span>
<span class="k">return</span> <span class="n">errors</span>
</pre></div>
</div>
</div>
<div class="section" id="s-writing-tests">
<span id="writing-tests"></span><h3>Writing Tests<a class="headerlink" href="#writing-tests" title="Permalink to this headline">¶</a></h3>
<p>Messages are comparable. That allows you to easily write tests:</p>
<div class="highlight-default"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.core.checks</span> <span class="k">import</span> <span class="n">Error</span>
<span class="n">errors</span> <span class="o">=</span> <span class="n">checked_object</span><span class="o">.</span><span class="n">check</span><span class="p">()</span>
<span class="n">expected_errors</span> <span class="o">=</span> <span class="p">[</span>
<span class="n">Error</span><span class="p">(</span>
<span class="s1">'an error'</span><span class="p">,</span>
<span class="n">hint</span><span class="o">=</span><span class="kc">None</span><span class="p">,</span>
<span class="n">obj</span><span class="o">=</span><span class="n">checked_object</span><span class="p">,</span>
<span class="nb">id</span><span class="o">=</span><span class="s1">'myapp.E001'</span><span class="p">,</span>
<span class="p">)</span>
<span class="p">]</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">errors</span><span class="p">,</span> <span class="n">expected_errors</span><span class="p">)</span>
</pre></div>
</div>
</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="#">System check framework</a><ul>
<li><a class="reference internal" href="#writing-your-own-checks">Writing your own checks</a><ul>
<li><a class="reference internal" href="#messages">Messages</a></li>
<li><a class="reference internal" href="#registering-and-labeling-checks">Registering and labeling checks</a></li>
<li><a class="reference internal" href="#field-model-and-manager-checks">Field, Model, and Manager checks</a></li>
<li><a class="reference internal" href="#writing-tests">Writing Tests</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="signals.html">Signals</a></li>
<li>Next: <a href="../howto/index.html">“How-to” guides</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">Using Django</a>
<ul><li>System check framework</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/topics/checks.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="signals.html" title="Signals">previous</a>
|
<a href="index.html" title="Using Django" accesskey="U">up</a>
|
<a href="../howto/index.html" title="&#8220;How-to&#8221; guides">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
distrib
>
Mageia
>
6
>
armv7hl
>
media
>
core-updates
>
by-pkgid
>
65530c6176058f9b54858c3b4f6385e6
>
files
>
919
