
<!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="en">
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
    <title>The Django template language: for Python programmers &#8212; Django 3.0.15.dev 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" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></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>
    <script type="text/javascript" src="../../_static/language_data.js"></script>
    <link rel="index" title="Index" href="../../genindex.html" />
    <link rel="search" title="Search" href="../../search.html" />
    <link rel="next" title="TemplateResponse and SimpleTemplateResponse" href="../template-response.html" />
    <link rel="prev" title="Built-in template tags and filters" href="builtins.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 = "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>

    <div class="document">
  <div id="custom-doc" class="yui-t6">
    <div id="hd">
      <h1><a href="../../index.html">Django 3.0.15.dev 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">
    &laquo; <a href="builtins.html" title="Built-in template tags and filters">previous</a>
     |
    <a href="../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="../template-response.html" title="&lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;TemplateResponse&lt;/span&gt;&lt;/code&gt; and &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;SimpleTemplateResponse&lt;/span&gt;&lt;/code&gt;">next</a> &raquo;</div>
    </div>

    <div id="bd">
      <div id="yui-main">
        <div class="yui-b">
          <div class="yui-g" id="ref-templates-api">
            
  <div class="section" id="s-the-django-template-language-for-python-programmers">
<span id="the-django-template-language-for-python-programmers"></span><h1>The Django template language: for Python programmers<a class="headerlink" href="#the-django-template-language-for-python-programmers" title="Permalink to this headline">¶</a></h1>
<p>This document explains the Django template system from a technical
perspective – how it works and how to extend it. If you’re looking for
reference on the language syntax, see <a class="reference internal" href="language.html"><span class="doc">The Django template language</span></a>.</p>
<p>It assumes an understanding of templates, contexts, variables, tags, and
rendering. Start with the <a class="reference internal" href="../../topics/templates.html#template-language-intro"><span class="std std-ref">introduction to the Django template language</span></a> if you aren’t familiar with these concepts.</p>
<div class="section" id="s-overview">
<span id="overview"></span><h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Using the template system in Python is a three-step process:</p>
<ol class="arabic simple">
<li>You configure an <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>.</li>
<li>You compile template code into a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a>.</li>
<li>You render the template with a <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a>.</li>
</ol>
<p>Django projects generally rely on the <a class="reference internal" href="../../topics/templates.html#template-engines"><span class="std std-ref">high level, backend agnostic APIs</span></a> for each of these steps instead of the template system’s
lower level APIs:</p>
<ol class="arabic simple">
<li>For each <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a> backend
in the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> setting, Django instantiates an
<a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>. <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a>
wraps <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> and adapts it to the common template backend API.</li>
<li>The <a class="reference internal" href="../../topics/templates.html#module-django.template.loader" title="django.template.loader"><code class="xref py py-mod docutils literal notranslate"><span class="pre">django.template.loader</span></code></a> module provides functions such as
<a class="reference internal" href="../../topics/templates.html#django.template.loader.get_template" title="django.template.loader.get_template"><code class="xref py py-func docutils literal notranslate"><span class="pre">get_template()</span></code></a> for loading templates. They
return a <code class="docutils literal notranslate"><span class="pre">django.template.backends.django.Template</span></code> which wraps the
actual <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.Template</span></code></a>.</li>
<li>The <code class="docutils literal notranslate"><span class="pre">Template</span></code> obtained in the previous step has a
<a class="reference internal" href="../../topics/templates.html#django.template.backends.base.Template.render" title="django.template.backends.base.Template.render"><code class="xref py py-meth docutils literal notranslate"><span class="pre">render()</span></code></a> method which
marshals a context and possibly a request into a <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> and
delegates the rendering to the underlying <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a>.</li>
</ol>
</div>
<div class="section" id="s-configuring-an-engine">
<span id="configuring-an-engine"></span><h2>Configuring an engine<a class="headerlink" href="#configuring-an-engine" title="Permalink to this headline">¶</a></h2>
<p>If you are using the <a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a>
backend, this probably isn’t the documentation you’re looking for. An instance
of the <code class="docutils literal notranslate"><span class="pre">Engine</span></code> class described below is accessible using the <code class="docutils literal notranslate"><span class="pre">engine</span></code>
attribute of that backend and any attribute defaults mentioned below are
overridden by what’s passed by
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a>.</p>
<dl class="class">
<dt id="django.template.Engine">
<em class="property">class </em><code class="descname">Engine</code>(<em>dirs=None</em>, <em>app_dirs=False</em>, <em>context_processors=None</em>, <em>debug=False</em>, <em>loaders=None</em>, <em>string_if_invalid=''</em>, <em>file_charset='utf-8'</em>, <em>libraries=None</em>, <em>builtins=None</em>, <em>autoescape=True</em>)<a class="headerlink" href="#django.template.Engine" title="Permalink to this definition">¶</a></dt>
<dd><p>When instantiating an <code class="docutils literal notranslate"><span class="pre">Engine</span></code> all arguments must be passed as keyword
arguments:</p>
<ul>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">dirs</span></code> is a list of directories where the engine should look for
template source files. It is used to configure
<a class="reference internal" href="#django.template.loaders.filesystem.Loader" title="django.template.loaders.filesystem.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">filesystem.Loader</span></code></a>.</p>
<p>It defaults to an empty list.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">app_dirs</span></code> only affects the default value of <code class="docutils literal notranslate"><span class="pre">loaders</span></code>. See below.</p>
<p>It defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">autoescape</span></code> controls whether HTML autoescaping is enabled.</p>
<p>It defaults to <code class="docutils literal notranslate"><span class="pre">True</span></code>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Only set it to <code class="docutils literal notranslate"><span class="pre">False</span></code> if you’re rendering non-HTML templates!</p>
</div>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">context_processors</span></code> is a list of dotted Python paths to callables
that are used to populate the context when a template is rendered with a
request. These callables take a request object as their argument and
return a <a class="reference external" href="https://docs.python.org/3/library/stdtypes.html#dict" title="(in Python v3.9)"><code class="xref py py-class docutils literal notranslate"><span class="pre">dict</span></code></a> of items to be merged into the context.</p>
<p>It defaults to an empty list.</p>
<p>See <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a> for more information.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">debug</span></code> is a boolean that turns on/off template debug mode. If it is
<code class="docutils literal notranslate"><span class="pre">True</span></code>, the template engine will store additional debug information
which can be used to display a detailed report for any exception raised
during template rendering.</p>
<p>It defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">loaders</span></code> is a list of template loader classes, specified as strings.
Each <code class="docutils literal notranslate"><span class="pre">Loader</span></code> class knows how to import templates from a particular
source. Optionally, a tuple can be used instead of a string. The first
item in the tuple should be the <code class="docutils literal notranslate"><span class="pre">Loader</span></code> class name, subsequent items
are passed to the <code class="docutils literal notranslate"><span class="pre">Loader</span></code> during initialization.</p>
<p>It defaults to a list containing:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">'django.template.loaders.filesystem.Loader'</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">'django.template.loaders.app_directories.Loader'</span></code> if and only if
<code class="docutils literal notranslate"><span class="pre">app_dirs</span></code> is <code class="docutils literal notranslate"><span class="pre">True</span></code>.</li>
</ul>
<p>If <code class="docutils literal notranslate"><span class="pre">debug</span></code> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, these loaders are wrapped in
<a class="reference internal" href="#django.template.loaders.cached.Loader" title="django.template.loaders.cached.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.loaders.cached.Loader</span></code></a>.</p>
<p>See <a class="reference internal" href="#template-loaders"><span class="std std-ref">Loader types</span></a> for details.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> is the output, as a string, that the template
system should use for invalid (e.g. misspelled) variables.</p>
<p>It defaults to the empty string.</p>
<p>See <a class="reference internal" href="#invalid-template-variables"><span class="std std-ref">How invalid variables are handled</span></a> for details.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">file_charset</span></code> is the charset used to read template files on disk.</p>
<p>It defaults to <code class="docutils literal notranslate"><span class="pre">'utf-8'</span></code>.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'libraries'</span></code>: A dictionary of labels and dotted Python paths of template
tag modules to register with the template engine. This is used to add new
libraries or provide alternate labels for existing ones. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Engine</span><span class="p">(</span>
    <span class="n">libraries</span><span class="o">=</span><span class="p">{</span>
        <span class="s1">&#39;myapp_tags&#39;</span><span class="p">:</span> <span class="s1">&#39;path.to.myapp.tags&#39;</span><span class="p">,</span>
        <span class="s1">&#39;admin.urls&#39;</span><span class="p">:</span> <span class="s1">&#39;django.contrib.admin.templatetags.admin_urls&#39;</span><span class="p">,</span>
    <span class="p">},</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Libraries can be loaded by passing the corresponding dictionary key to
the <a class="reference internal" href="builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></code></a> tag.</p>
</li>
<li><p class="first"><code class="docutils literal notranslate"><span class="pre">'builtins'</span></code>: A list of dotted Python paths of template tag modules to
add to <a class="reference internal" href="builtins.html"><span class="doc">built-ins</span></a>. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">Engine</span><span class="p">(</span>
    <span class="n">builtins</span><span class="o">=</span><span class="p">[</span><span class="s1">&#39;myapp.builtins&#39;</span><span class="p">],</span>
<span class="p">)</span>
</pre></div>
</div>
<p>Tags and filters from built-in libraries can be used without first calling
the <a class="reference internal" href="builtins.html#std:templatetag-load"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">{%</span> <span class="pre">load</span> <span class="pre">%}</span></code></a> tag.</p>
</li>
</ul>
</dd></dl>

<dl class="staticmethod">
<dt id="django.template.Engine.get_default">
<em class="property">static </em><code class="descclassname">Engine.</code><code class="descname">get_default</code>()<a class="headerlink" href="#django.template.Engine.get_default" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the underlying <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> from the first configured
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a> engine. Raises
<a class="reference internal" href="../exceptions.html#django.core.exceptions.ImproperlyConfigured" title="django.core.exceptions.ImproperlyConfigured"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ImproperlyConfigured</span></code></a> if no engines are
configured.</p>
<p>It’s required for preserving APIs that rely on a globally available,
implicitly configured engine. Any other use is strongly discouraged.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Engine.from_string">
<code class="descclassname">Engine.</code><code class="descname">from_string</code>(<em>template_code</em>)<a class="headerlink" href="#django.template.Engine.from_string" title="Permalink to this definition">¶</a></dt>
<dd><p>Compiles the given template code and returns a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> object.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Engine.get_template">
<code class="descclassname">Engine.</code><code class="descname">get_template</code>(<em>template_name</em>)<a class="headerlink" href="#django.template.Engine.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads a template with the given name, compiles it and returns a
<a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> object.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Engine.select_template">
<code class="descclassname">Engine.</code><code class="descname">select_template</code>(<em>template_name_list</em>)<a class="headerlink" href="#django.template.Engine.select_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Like <a class="reference internal" href="#django.template.Engine.get_template" title="django.template.Engine.get_template"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_template()</span></code></a>, except it takes a list of names
and returns the first template that was found.</p>
</dd></dl>

</div>
<div class="section" id="s-loading-a-template">
<span id="loading-a-template"></span><h2>Loading a template<a class="headerlink" href="#loading-a-template" title="Permalink to this headline">¶</a></h2>
<p>The recommended way to create a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> is by calling the factory
methods of the <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>: <a class="reference internal" href="#django.template.Engine.get_template" title="django.template.Engine.get_template"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_template()</span></code></a>,
<a class="reference internal" href="#django.template.Engine.select_template" title="django.template.Engine.select_template"><code class="xref py py-meth docutils literal notranslate"><span class="pre">select_template()</span></code></a> and <a class="reference internal" href="#django.template.Engine.from_string" title="django.template.Engine.from_string"><code class="xref py py-meth docutils literal notranslate"><span class="pre">from_string()</span></code></a>.</p>
<p>In a Django project where the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> setting defines a
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a> engine, it’s
possible to instantiate a <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> directly. If more than one
<a class="reference internal" href="../../topics/templates.html#django.template.backends.django.DjangoTemplates" title="django.template.backends.django.DjangoTemplates"><code class="xref py py-class docutils literal notranslate"><span class="pre">DjangoTemplates</span></code></a> engine is defined,
the first one will be used.</p>
<dl class="class">
<dt id="django.template.Template">
<em class="property">class </em><code class="descname">Template</code><a class="headerlink" href="#django.template.Template" title="Permalink to this definition">¶</a></dt>
<dd><p>This class lives at <code class="docutils literal notranslate"><span class="pre">django.template.Template</span></code>. The constructor takes
one argument — the raw template code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">Template</span>

<span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;My name is {{ my_name }}.&quot;</span><span class="p">)</span>
</pre></div>
</div>
</dd></dl>

<div class="admonition-behind-the-scenes admonition">
<p class="first admonition-title">Behind the scenes</p>
<p>The system only parses your raw template code once – when you create the
<code class="docutils literal notranslate"><span class="pre">Template</span></code> object. From then on, it’s stored internally as a tree
structure for performance.</p>
<p class="last">Even the parsing itself is quite fast. Most of the parsing happens via a
single call to a single, short, regular expression.</p>
</div>
</div>
<div class="section" id="s-rendering-a-context">
<span id="rendering-a-context"></span><h2>Rendering a context<a class="headerlink" href="#rendering-a-context" title="Permalink to this headline">¶</a></h2>
<p>Once you have a compiled <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> object, you can render a context
with it. You can reuse the same template to render it several times with
different contexts.</p>
<dl class="class">
<dt id="django.template.Context">
<em class="property">class </em><code class="descname">Context</code>(<em>dict_=None</em>)<a class="headerlink" href="#django.template.Context" title="Permalink to this definition">¶</a></dt>
<dd><p>The constructor of <code class="docutils literal notranslate"><span class="pre">django.template.Context</span></code> takes an optional argument —
a dictionary mapping variable names to variable values.</p>
<p>For details, see <a class="reference internal" href="#playing-with-context"><span class="std std-ref">Playing with Context objects</span></a> below.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Template.render">
<code class="descclassname">Template.</code><code class="descname">render</code>(<em>context</em>)<a class="headerlink" href="#django.template.Template.render" title="Permalink to this definition">¶</a></dt>
<dd><p>Call the <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> object’s <code class="docutils literal notranslate"><span class="pre">render()</span></code> method with a
<a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> to “fill” the template:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">Context</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;My name is {{ my_name }}.&quot;</span><span class="p">)</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">&quot;my_name&quot;</span><span class="p">:</span> <span class="s2">&quot;Adrian&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">context</span><span class="p">)</span>
<span class="go">&quot;My name is Adrian.&quot;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">context</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">&quot;my_name&quot;</span><span class="p">:</span> <span class="s2">&quot;Dolores&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">context</span><span class="p">)</span>
<span class="go">&quot;My name is Dolores.&quot;</span>
</pre></div>
</div>
</dd></dl>

<div class="section" id="s-variables-and-lookups">
<span id="variables-and-lookups"></span><h3>Variables and lookups<a class="headerlink" href="#variables-and-lookups" title="Permalink to this headline">¶</a></h3>
<p>Variable names must consist of any letter (A-Z), any digit (0-9), an underscore
(but they must not start with an underscore) or a dot.</p>
<p>Dots have a special meaning in template rendering. A dot in a variable name
signifies a <strong>lookup</strong>. Specifically, when the template system encounters a
dot in a variable name, it tries the following lookups, in this order:</p>
<ul class="simple">
<li>Dictionary lookup. Example: <code class="docutils literal notranslate"><span class="pre">foo[&quot;bar&quot;]</span></code></li>
<li>Attribute lookup. Example: <code class="docutils literal notranslate"><span class="pre">foo.bar</span></code></li>
<li>List-index lookup. Example: <code class="docutils literal notranslate"><span class="pre">foo[bar]</span></code></li>
</ul>
<p>Note that “bar” in a template expression like <code class="docutils literal notranslate"><span class="pre">{{</span> <span class="pre">foo.bar</span> <span class="pre">}}</span></code> will be
interpreted as a literal string and not using the value of the variable “bar”,
if one exists in the template context.</p>
<p>The template system uses the first lookup type that works. It’s short-circuit
logic. Here are a few examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">Context</span><span class="p">,</span> <span class="n">Template</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;My name is {{ person.first_name }}.&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="p">{</span><span class="s2">&quot;person&quot;</span><span class="p">:</span> <span class="p">{</span><span class="s2">&quot;first_name&quot;</span><span class="p">:</span> <span class="s2">&quot;Joe&quot;</span><span class="p">,</span> <span class="s2">&quot;last_name&quot;</span><span class="p">:</span> <span class="s2">&quot;Johnson&quot;</span><span class="p">}}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">(</span><span class="n">d</span><span class="p">))</span>
<span class="go">&quot;My name is Joe.&quot;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonClass</span><span class="p">:</span> <span class="k">pass</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">first_name</span> <span class="o">=</span> <span class="s2">&quot;Ron&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span><span class="o">.</span><span class="n">last_name</span> <span class="o">=</span> <span class="s2">&quot;Nasty&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({</span><span class="s2">&quot;person&quot;</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="go">&quot;My name is Ron.&quot;</span>

<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;The first stooge in the list is {{ stooges.0 }}.&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">&quot;stooges&quot;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&quot;Larry&quot;</span><span class="p">,</span> <span class="s2">&quot;Curly&quot;</span><span class="p">,</span> <span class="s2">&quot;Moe&quot;</span><span class="p">]})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">c</span><span class="p">)</span>
<span class="go">&quot;The first stooge in the list is Larry.&quot;</span>
</pre></div>
</div>
<p>If any part of the variable is callable, the template system will try calling
it. Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonClass2</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">return</span> <span class="s2">&quot;Samantha&quot;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;My name is {{ person.name }}.&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({</span><span class="s2">&quot;person&quot;</span><span class="p">:</span> <span class="n">PersonClass2</span><span class="p">}))</span>
<span class="go">&quot;My name is Samantha.&quot;</span>
</pre></div>
</div>
<p>Callable variables are slightly more complex than variables which only require
straight lookups. Here are some things to keep in mind:</p>
<ul>
<li><p class="first">If the variable raises an exception when called, the exception will be
propagated, unless the exception has an attribute
<code class="docutils literal notranslate"><span class="pre">silent_variable_failure</span></code> whose value is <code class="docutils literal notranslate"><span class="pre">True</span></code>. If the exception
<em>does</em> have a <code class="docutils literal notranslate"><span class="pre">silent_variable_failure</span></code> attribute whose value is
<code class="docutils literal notranslate"><span class="pre">True</span></code>, the variable will render as the value of the engine’s
<code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> configuration option (an empty string, by default).
Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">t</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s2">&quot;My name is {{ person.first_name }}.&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonClass3</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">first_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">raise</span> <span class="ne">AssertionError</span><span class="p">(</span><span class="s2">&quot;foo&quot;</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass3</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({</span><span class="s2">&quot;person&quot;</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">AssertionError</span>: <span class="n">foo</span>

<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">SilentAssertionError</span><span class="p">(</span><span class="ne">Exception</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">silent_variable_failure</span> <span class="o">=</span> <span class="kc">True</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">PersonClass4</span><span class="p">:</span>
<span class="gp">... </span>    <span class="k">def</span> <span class="nf">first_name</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="gp">... </span>        <span class="k">raise</span> <span class="n">SilentAssertionError</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">p</span> <span class="o">=</span> <span class="n">PersonClass4</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">t</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">Context</span><span class="p">({</span><span class="s2">&quot;person&quot;</span><span class="p">:</span> <span class="n">p</span><span class="p">}))</span>
<span class="go">&quot;My name is .&quot;</span>
</pre></div>
</div>
<p>Note that <a class="reference internal" href="../exceptions.html#django.core.exceptions.ObjectDoesNotExist" title="django.core.exceptions.ObjectDoesNotExist"><code class="xref py py-exc docutils literal notranslate"><span class="pre">django.core.exceptions.ObjectDoesNotExist</span></code></a>, which is the
base class for all Django database API <code class="docutils literal notranslate"><span class="pre">DoesNotExist</span></code> exceptions, has
<code class="docutils literal notranslate"><span class="pre">silent_variable_failure</span> <span class="pre">=</span> <span class="pre">True</span></code>. So if you’re using Django templates
with Django model objects, any <code class="docutils literal notranslate"><span class="pre">DoesNotExist</span></code> exception will fail
silently.</p>
</li>
<li><p class="first">A variable can only be called if it has no required arguments. Otherwise,
the system will return the value of the engine’s <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code>
option.</p>
</li>
</ul>
<ul id="alters-data-description">
<li><p class="first">There can be side effects when calling some variables, and it’d be either
foolish or a security hole to allow the template system to access them.</p>
<p>A good example is the <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 notranslate"><span class="pre">delete()</span></code></a> method on
each Django model object. The template system shouldn’t be allowed to do
something like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">I</span> <span class="n">will</span> <span class="n">now</span> <span class="n">delete</span> <span class="n">this</span> <span class="n">valuable</span> <span class="n">data</span><span class="o">.</span> <span class="p">{{</span> <span class="n">data</span><span class="o">.</span><span class="n">delete</span> <span class="p">}}</span>
</pre></div>
</div>
<p>To prevent this, set an <code class="docutils literal notranslate"><span class="pre">alters_data</span></code> attribute on the callable
variable. The template system won’t call a variable if it has
<code class="docutils literal notranslate"><span class="pre">alters_data=True</span></code> set, and will instead replace the variable with
<code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code>, unconditionally.  The
dynamically-generated <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 notranslate"><span class="pre">delete()</span></code></a> and
<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 notranslate"><span class="pre">save()</span></code></a> methods on Django model objects get
<code class="docutils literal notranslate"><span class="pre">alters_data=True</span></code> automatically. Example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span> <span class="nf">sensitive_function</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
    <span class="bp">self</span><span class="o">.</span><span class="n">database_record</span><span class="o">.</span><span class="n">delete</span><span class="p">()</span>
<span class="n">sensitive_function</span><span class="o">.</span><span class="n">alters_data</span> <span class="o">=</span> <span class="kc">True</span>
</pre></div>
</div>
</li>
<li><p class="first">Occasionally you may want to turn off this feature for other reasons,
and tell the template system to leave a variable uncalled no matter
what.  To do so, set a <code class="docutils literal notranslate"><span class="pre">do_not_call_in_templates</span></code> attribute on the
callable with the value <code class="docutils literal notranslate"><span class="pre">True</span></code>.  The template system then will act as
if your variable is not callable (allowing you to access attributes of
the callable, for example).</p>
</li>
</ul>
</div>
<div class="section" id="s-how-invalid-variables-are-handled">
<span id="s-invalid-template-variables"></span><span id="how-invalid-variables-are-handled"></span><span id="invalid-template-variables"></span><h3>How invalid variables are handled<a class="headerlink" href="#how-invalid-variables-are-handled" title="Permalink to this headline">¶</a></h3>
<p>Generally, if a variable doesn’t exist, the template system inserts the value
of the engine’s <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> configuration option, which is set to
<code class="docutils literal notranslate"><span class="pre">''</span></code> (the empty string) by default.</p>
<p>Filters that are applied to an invalid variable will only be applied if
<code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> is set to <code class="docutils literal notranslate"><span class="pre">''</span></code> (the empty string). If
<code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> is set to any other value, variable filters will be
ignored.</p>
<p>This behavior is slightly different for the <code class="docutils literal notranslate"><span class="pre">if</span></code>, <code class="docutils literal notranslate"><span class="pre">for</span></code> and <code class="docutils literal notranslate"><span class="pre">regroup</span></code>
template tags. If an invalid variable is provided to one of these template
tags, the variable will be interpreted as <code class="docutils literal notranslate"><span class="pre">None</span></code>. Filters are always
applied to invalid variables within these template tags.</p>
<p>If <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> contains a <code class="docutils literal notranslate"><span class="pre">'%s'</span></code>, the format marker will be
replaced with the name of the invalid variable.</p>
<div class="admonition-for-debug-purposes-only admonition">
<p class="first admonition-title">For debug purposes only!</p>
<p>While <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> can be a useful debugging tool, it is a bad
idea to turn it on as a ‘development default’.</p>
<p>Many templates, including some of Django’s, rely upon the silence of the
template system when a nonexistent variable is encountered. If you assign a
value other than <code class="docutils literal notranslate"><span class="pre">''</span></code> to <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code>, you will experience
rendering problems with these templates and sites.</p>
<p class="last">Generally, <code class="docutils literal notranslate"><span class="pre">string_if_invalid</span></code> should only be enabled in order to debug
a specific template problem, then cleared once debugging is complete.</p>
</div>
</div>
<div class="section" id="s-built-in-variables">
<span id="built-in-variables"></span><h3>Built-in variables<a class="headerlink" href="#built-in-variables" title="Permalink to this headline">¶</a></h3>
<p>Every context contains <code class="docutils literal notranslate"><span class="pre">True</span></code>, <code class="docutils literal notranslate"><span class="pre">False</span></code> and <code class="docutils literal notranslate"><span class="pre">None</span></code>. As you would expect,
these variables resolve to the corresponding Python objects.</p>
</div>
<div class="section" id="s-limitations-with-string-literals">
<span id="limitations-with-string-literals"></span><h3>Limitations with string literals<a class="headerlink" href="#limitations-with-string-literals" title="Permalink to this headline">¶</a></h3>
<p>Django’s template language has no way to escape the characters used for its own
syntax. For example, the <a class="reference internal" href="builtins.html#std:templatetag-templatetag"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">templatetag</span></code></a> tag is required if you need to
output character sequences like <code class="docutils literal notranslate"><span class="pre">{%</span></code> and <code class="docutils literal notranslate"><span class="pre">%}</span></code>.</p>
<p>A similar issue exists if you want to include these sequences in template filter
or tag arguments. For example, when parsing a block tag, Django’s template
parser looks for the first occurrence of <code class="docutils literal notranslate"><span class="pre">%}</span></code> after a <code class="docutils literal notranslate"><span class="pre">{%</span></code>. This prevents
the use of <code class="docutils literal notranslate"><span class="pre">&quot;%}&quot;</span></code> as a string literal. For example, a <code class="docutils literal notranslate"><span class="pre">TemplateSyntaxError</span></code>
will be raised for the following expressions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="o">%</span> <span class="n">include</span> <span class="s2">&quot;template.html&quot;</span> <span class="n">tvar</span><span class="o">=</span><span class="s2">&quot;Some string literal with %} in it.&quot;</span> <span class="o">%</span><span class="p">}</span>

<span class="p">{</span><span class="o">%</span> <span class="k">with</span> <span class="n">tvar</span><span class="o">=</span><span class="s2">&quot;Some string literal with %} in it.&quot;</span> <span class="o">%</span><span class="p">}{</span><span class="o">%</span> <span class="n">endwith</span> <span class="o">%</span><span class="p">}</span>
</pre></div>
</div>
<p>The same issue can be triggered by using a reserved sequence in filter
arguments:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{{</span> <span class="n">some</span><span class="o">.</span><span class="n">variable</span><span class="o">|</span><span class="n">default</span><span class="p">:</span><span class="s2">&quot;}}&quot;</span> <span class="p">}}</span>
</pre></div>
</div>
<p>If you need to use strings with these sequences, store them in template
variables or use a custom template tag or filter to workaround the limitation.</p>
</div>
</div>
<div class="section" id="s-playing-with-context-objects">
<span id="s-playing-with-context"></span><span id="playing-with-context-objects"></span><span id="playing-with-context"></span><h2>Playing with <code class="docutils literal notranslate"><span class="pre">Context</span></code> objects<a class="headerlink" href="#playing-with-context-objects" title="Permalink to this headline">¶</a></h2>
<p>Most of the time, you’ll instantiate <a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> objects by passing in a
fully-populated dictionary to <code class="docutils literal notranslate"><span class="pre">Context()</span></code>. But you can add and delete items
from a <code class="docutils literal notranslate"><span class="pre">Context</span></code> object once it’s been instantiated, too, using standard
dictionary syntax:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">Context</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">({</span><span class="s2">&quot;foo&quot;</span><span class="p">:</span> <span class="s2">&quot;bar&quot;</span><span class="p">})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;bar&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">del</span> <span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">KeyError</span>: <span class="n">&#39;foo&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;newvariable&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;hello&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;newvariable&#39;</span><span class="p">]</span>
<span class="go">&#39;hello&#39;</span>
</pre></div>
</div>
<dl class="method">
<dt id="django.template.Context.get">
<code class="descclassname">Context.</code><code class="descname">get</code>(<em>key</em>, <em>otherwise=None</em>)<a class="headerlink" href="#django.template.Context.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the value for <code class="docutils literal notranslate"><span class="pre">key</span></code> if <code class="docutils literal notranslate"><span class="pre">key</span></code> is in the context, else returns
<code class="docutils literal notranslate"><span class="pre">otherwise</span></code>.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Context.setdefault">
<code class="descclassname">Context.</code><code class="descname">setdefault</code>(<em>key</em>, <em>default=None</em>)<a class="headerlink" href="#django.template.Context.setdefault" title="Permalink to this definition">¶</a></dt>
<dd><p>If <code class="docutils literal notranslate"><span class="pre">key</span></code> is in the context, returns its value. Otherwise inserts <code class="docutils literal notranslate"><span class="pre">key</span></code>
with a value of <code class="docutils literal notranslate"><span class="pre">default</span></code> and returns <code class="docutils literal notranslate"><span class="pre">default</span></code>.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.Context.pop">
<code class="descclassname">Context.</code><code class="descname">pop</code>()<a class="headerlink" href="#django.template.Context.pop" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="method">
<dt id="django.template.Context.push">
<code class="descclassname">Context.</code><code class="descname">push</code>()<a class="headerlink" href="#django.template.Context.push" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<dl class="exception">
<dt id="django.template.ContextPopException">
<em class="property">exception </em><code class="descname">ContextPopException</code><a class="headerlink" href="#django.template.ContextPopException" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>A <code class="docutils literal notranslate"><span class="pre">Context</span></code> object is a stack. That is, you can <code class="docutils literal notranslate"><span class="pre">push()</span></code> and <code class="docutils literal notranslate"><span class="pre">pop()</span></code> it.
If you <code class="docutils literal notranslate"><span class="pre">pop()</span></code> too much, it’ll raise
<code class="docutils literal notranslate"><span class="pre">django.template.ContextPopException</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">()</span>
<span class="go">{}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="go">{&#39;foo&#39;: &#39;second level&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;overwritten&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;overwritten&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="gt">Traceback (most recent call last):</span>
<span class="c">...</span>
<span class="gr">ContextPopException</span>
</pre></div>
</div>
<p>You can also use <code class="docutils literal notranslate"><span class="pre">push()</span></code> as a context manager to ensure a matching <code class="docutils literal notranslate"><span class="pre">pop()</span></code>
is called.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">():</span>
<span class="gp">... </span>    <span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;second level&#39;</span>
<span class="gp">... </span>    <span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;first level&#39;</span>
</pre></div>
</div>
<p>All arguments passed to <code class="docutils literal notranslate"><span class="pre">push()</span></code> will be passed to the <code class="docutils literal notranslate"><span class="pre">dict</span></code> constructor
used to build the new context level.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">c</span><span class="o">.</span><span class="n">push</span><span class="p">(</span><span class="n">foo</span><span class="o">=</span><span class="s1">&#39;second level&#39;</span><span class="p">):</span>
<span class="gp">... </span>    <span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;first level&#39;</span>
</pre></div>
</div>
<dl class="method">
<dt id="django.template.Context.update">
<code class="descclassname">Context.</code><code class="descname">update</code>(<em>other_dict</em>)<a class="headerlink" href="#django.template.Context.update" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>In addition to <code class="docutils literal notranslate"><span class="pre">push()</span></code> and <code class="docutils literal notranslate"><span class="pre">pop()</span></code>, the <code class="docutils literal notranslate"><span class="pre">Context</span></code>
object also defines an <code class="docutils literal notranslate"><span class="pre">update()</span></code> method. This works like <code class="docutils literal notranslate"><span class="pre">push()</span></code>
but takes a dictionary as an argument and pushes that dictionary onto
the stack instead of an empty one.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;updated&#39;</span><span class="p">})</span>
<span class="go">{&#39;foo&#39;: &#39;updated&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;updated&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">pop</span><span class="p">()</span>
<span class="go">{&#39;foo&#39;: &#39;updated&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;first level&#39;</span>
</pre></div>
</div>
<p>Like <code class="docutils literal notranslate"><span class="pre">push()</span></code>, you can use <code class="docutils literal notranslate"><span class="pre">update()</span></code> as a context manager to ensure a
matching <code class="docutils literal notranslate"><span class="pre">pop()</span></code> is called.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="k">with</span> <span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;second level&#39;</span><span class="p">}):</span>
<span class="gp">... </span>    <span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span>
<span class="go">&#39;first level&#39;</span>
</pre></div>
</div>
<p>Using a <code class="docutils literal notranslate"><span class="pre">Context</span></code> as a stack comes in handy in <a class="reference internal" href="../../howto/custom-template-tags.html#howto-writing-custom-template-tags"><span class="std std-ref">some custom template
tags</span></a>.</p>
<dl class="method">
<dt id="django.template.Context.flatten">
<code class="descclassname">Context.</code><code class="descname">flatten</code>()<a class="headerlink" href="#django.template.Context.flatten" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Using <code class="docutils literal notranslate"><span class="pre">flatten()</span></code> method you can get whole <code class="docutils literal notranslate"><span class="pre">Context</span></code> stack as one dictionary
including builtin variables.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">&#39;bar&#39;</span><span class="p">:</span> <span class="s1">&#39;second level&#39;</span><span class="p">})</span>
<span class="go">{&#39;bar&#39;: &#39;second level&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c</span><span class="o">.</span><span class="n">flatten</span><span class="p">()</span>
<span class="go">{&#39;True&#39;: True, &#39;None&#39;: None, &#39;foo&#39;: &#39;first level&#39;, &#39;False&#39;: False, &#39;bar&#39;: &#39;second level&#39;}</span>
</pre></div>
</div>
<p>A <code class="docutils literal notranslate"><span class="pre">flatten()</span></code> method is also internally used to make <code class="docutils literal notranslate"><span class="pre">Context</span></code> objects comparable.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">c1</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c1</span><span class="p">[</span><span class="s1">&#39;foo&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;first level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c1</span><span class="p">[</span><span class="s1">&#39;bar&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;second level&#39;</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c2</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c2</span><span class="o">.</span><span class="n">update</span><span class="p">({</span><span class="s1">&#39;bar&#39;</span><span class="p">:</span> <span class="s1">&#39;second level&#39;</span><span class="p">,</span> <span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;first level&#39;</span><span class="p">})</span>
<span class="go">{&#39;foo&#39;: &#39;first level&#39;, &#39;bar&#39;: &#39;second level&#39;}</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">c1</span> <span class="o">==</span> <span class="n">c2</span>
<span class="go">True</span>
</pre></div>
</div>
<p>Result from <code class="docutils literal notranslate"><span class="pre">flatten()</span></code> can be useful in unit tests to compare <code class="docutils literal notranslate"><span class="pre">Context</span></code>
against <code class="docutils literal notranslate"><span class="pre">dict</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ContextTest</span><span class="p">(</span><span class="n">unittest</span><span class="o">.</span><span class="n">TestCase</span><span class="p">):</span>
    <span class="k">def</span> <span class="nf">test_against_dictionary</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
        <span class="n">c1</span> <span class="o">=</span> <span class="n">Context</span><span class="p">()</span>
        <span class="n">c1</span><span class="p">[</span><span class="s1">&#39;update&#39;</span><span class="p">]</span> <span class="o">=</span> <span class="s1">&#39;value&#39;</span>
        <span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">c1</span><span class="o">.</span><span class="n">flatten</span><span class="p">(),</span> <span class="p">{</span>
            <span class="s1">&#39;True&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
            <span class="s1">&#39;None&#39;</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
            <span class="s1">&#39;False&#39;</span><span class="p">:</span> <span class="kc">False</span><span class="p">,</span>
            <span class="s1">&#39;update&#39;</span><span class="p">:</span> <span class="s1">&#39;value&#39;</span><span class="p">,</span>
        <span class="p">})</span>
</pre></div>
</div>
<div class="section" id="s-using-requestcontext">
<span id="s-subclassing-context-requestcontext"></span><span id="using-requestcontext"></span><span id="subclassing-context-requestcontext"></span><h3>Using <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code><a class="headerlink" href="#using-requestcontext" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.template.RequestContext">
<em class="property">class </em><code class="descname">RequestContext</code>(<em>request</em>, <em>dict_=None</em>, <em>processors=None</em>)<a class="headerlink" href="#django.template.RequestContext" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>Django comes with a special <code class="docutils literal notranslate"><span class="pre">Context</span></code> class,
<code class="docutils literal notranslate"><span class="pre">django.template.RequestContext</span></code>, that acts slightly differently from the
normal <code class="docutils literal notranslate"><span class="pre">django.template.Context</span></code>. The first difference is that it takes an
<a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> as its first argument. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="p">{</span>
    <span class="s1">&#39;foo&#39;</span><span class="p">:</span> <span class="s1">&#39;bar&#39;</span><span class="p">,</span>
<span class="p">})</span>
</pre></div>
</div>
<p>The second difference is that it automatically populates the context with a
few variables, according to the engine’s <code class="docutils literal notranslate"><span class="pre">context_processors</span></code> configuration
option.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">context_processors</span></code> option is a list of callables – called <strong>context
processors</strong> – that take a request object as their argument and return a
dictionary of items to be merged into the context. In the default generated
settings file, the default template engine contains the following context
processors:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">[</span>
    <span class="s1">&#39;django.template.context_processors.debug&#39;</span><span class="p">,</span>
    <span class="s1">&#39;django.template.context_processors.request&#39;</span><span class="p">,</span>
    <span class="s1">&#39;django.contrib.auth.context_processors.auth&#39;</span><span class="p">,</span>
    <span class="s1">&#39;django.contrib.messages.context_processors.messages&#39;</span><span class="p">,</span>
<span class="p">]</span>
</pre></div>
</div>
<p>In addition to these, <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a> always enables
<code class="docutils literal notranslate"><span class="pre">'django.template.context_processors.csrf'</span></code>.  This is a security related
context processor required by the admin and other contrib apps, and, in case
of accidental misconfiguration, it is deliberately hardcoded in and cannot be
turned off in the <code class="docutils literal notranslate"><span class="pre">context_processors</span></code> option.</p>
<p>Each processor is applied in order. That means, if one processor adds a
variable to the context and a second processor adds a variable with the same
name, the second will override the first. The default processors are explained
below.</p>
<div class="admonition-when-context-processors-are-applied admonition">
<p class="first admonition-title">When context processors are applied</p>
<p>Context processors are applied on top of context data. This means that a
context processor may overwrite variables you’ve supplied to your
<a class="reference internal" href="#django.template.Context" title="django.template.Context"><code class="xref py py-class docutils literal notranslate"><span class="pre">Context</span></code></a> or <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a>, so take care to avoid
variable names that overlap with those supplied by your context
processors.</p>
<p>If you want context data to take priority over context processors, use the
following pattern:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">RequestContext</span>

<span class="n">request_context</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
<span class="n">request_context</span><span class="o">.</span><span class="n">push</span><span class="p">({</span><span class="s2">&quot;my_name&quot;</span><span class="p">:</span> <span class="s2">&quot;Adrian&quot;</span><span class="p">})</span>
</pre></div>
</div>
<p class="last">Django does this to allow context data to override context processors in
APIs such as <a class="reference internal" href="../../topics/http/shortcuts.html#django.shortcuts.render" title="django.shortcuts.render"><code class="xref py py-func docutils literal notranslate"><span class="pre">render()</span></code></a> and
<a class="reference internal" href="../template-response.html#django.template.response.TemplateResponse" title="django.template.response.TemplateResponse"><code class="xref py py-class docutils literal notranslate"><span class="pre">TemplateResponse</span></code></a>.</p>
</div>
<p>Also, you can give <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a> a list of additional processors,
using the optional, third positional argument, <code class="docutils literal notranslate"><span class="pre">processors</span></code>. In this
example, the <a class="reference internal" href="#django.template.RequestContext" title="django.template.RequestContext"><code class="xref py py-class docutils literal notranslate"><span class="pre">RequestContext</span></code></a> instance gets an <code class="docutils literal notranslate"><span class="pre">ip_address</span></code> variable:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">django.http</span> <span class="kn">import</span> <span class="n">HttpResponse</span>
<span class="kn">from</span> <span class="nn">django.template</span> <span class="kn">import</span> <span class="n">RequestContext</span><span class="p">,</span> <span class="n">Template</span>

<span class="k">def</span> <span class="nf">ip_address_processor</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="k">return</span> <span class="p">{</span><span class="s1">&#39;ip_address&#39;</span><span class="p">:</span> <span class="n">request</span><span class="o">.</span><span class="n">META</span><span class="p">[</span><span class="s1">&#39;REMOTE_ADDR&#39;</span><span class="p">]}</span>

<span class="k">def</span> <span class="nf">client_ip_view</span><span class="p">(</span><span class="n">request</span><span class="p">):</span>
    <span class="n">template</span> <span class="o">=</span> <span class="n">Template</span><span class="p">(</span><span class="s1">&#39;{{ title }}: {{ ip_address }}&#39;</span><span class="p">)</span>
    <span class="n">context</span> <span class="o">=</span> <span class="n">RequestContext</span><span class="p">(</span><span class="n">request</span><span class="p">,</span> <span class="p">{</span>
        <span class="s1">&#39;title&#39;</span><span class="p">:</span> <span class="s1">&#39;Your IP Address&#39;</span><span class="p">,</span>
    <span class="p">},</span> <span class="p">[</span><span class="n">ip_address_processor</span><span class="p">])</span>
    <span class="k">return</span> <span class="n">HttpResponse</span><span class="p">(</span><span class="n">template</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">context</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="s-built-in-template-context-processors">
<span id="s-context-processors"></span><span id="built-in-template-context-processors"></span><span id="context-processors"></span><h3>Built-in template context processors<a class="headerlink" href="#built-in-template-context-processors" title="Permalink to this headline">¶</a></h3>
<p>Here’s what each of the built-in processors does:</p>
<div class="section" id="s-django-contrib-auth-context-processors-auth">
<span id="django-contrib-auth-context-processors-auth"></span><h4><code class="docutils literal notranslate"><span class="pre">django.contrib.auth.context_processors.auth</span></code><a class="headerlink" href="#django-contrib-auth-context-processors-auth" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.contrib.auth.context_processors.auth">
<code class="descname">auth</code>()<a class="headerlink" href="#django.contrib.auth.context_processors.auth" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain these
variables:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">user</span></code> – An <code class="docutils literal notranslate"><span class="pre">auth.User</span></code> instance representing the currently
logged-in user (or an <code class="docutils literal notranslate"><span class="pre">AnonymousUser</span></code> instance, if the client isn’t
logged in).</li>
<li><code class="docutils literal notranslate"><span class="pre">perms</span></code> – An instance of
<code class="docutils literal notranslate"><span class="pre">django.contrib.auth.context_processors.PermWrapper</span></code>, representing the
permissions that the currently logged-in user has.</li>
</ul>
</div>
<div class="section" id="s-django-template-context-processors-debug">
<span id="django-template-context-processors-debug"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.debug</span></code><a class="headerlink" href="#django-template-context-processors-debug" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.debug">
<code class="descname">debug</code>()<a class="headerlink" href="#django.template.context_processors.debug" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain these two
variables – but only if your <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a> setting is set to <code class="docutils literal notranslate"><span class="pre">True</span></code> and
the request’s IP address (<code class="docutils literal notranslate"><span class="pre">request.META['REMOTE_ADDR']</span></code>) is in the
<a class="reference internal" href="../settings.html#std:setting-INTERNAL_IPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INTERNAL_IPS</span></code></a> setting:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">debug</span></code> – <code class="docutils literal notranslate"><span class="pre">True</span></code>. You can use this in templates to test whether
you’re in <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a> mode.</li>
<li><code class="docutils literal notranslate"><span class="pre">sql_queries</span></code> – A list of <code class="docutils literal notranslate"><span class="pre">{'sql':</span> <span class="pre">...,</span> <span class="pre">'time':</span> <span class="pre">...}</span></code> dictionaries,
representing every SQL query that has happened so far during the request
and how long it took. The list is in order by database alias and then by
query. It’s lazily generated on access.</li>
</ul>
</div>
<div class="section" id="s-django-template-context-processors-i18n">
<span id="django-template-context-processors-i18n"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.i18n</span></code><a class="headerlink" href="#django-template-context-processors-i18n" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.i18n">
<code class="descname">i18n</code>()<a class="headerlink" href="#django.template.context_processors.i18n" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain these
variables:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">LANGUAGES</span></code> – The value of the <a class="reference internal" href="../settings.html#std:setting-LANGUAGES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">LANGUAGES</span></code></a> setting.</li>
<li><code class="docutils literal notranslate"><span class="pre">LANGUAGE_BIDI</span></code> – <code class="docutils literal notranslate"><span class="pre">True</span></code> if the current language is a right-to-left
language, e.g. Hebrew, Arabic. <code class="docutils literal notranslate"><span class="pre">False</span></code> if it’s a left-to-right language,
e.g. English, French, German.</li>
<li><code class="docutils literal notranslate"><span class="pre">LANGUAGE_CODE</span></code> – <code class="docutils literal notranslate"><span class="pre">request.LANGUAGE_CODE</span></code>, if it exists. Otherwise,
the value of the <a class="reference internal" href="../settings.html#std:setting-LANGUAGE_CODE"><code class="xref std std-setting docutils literal notranslate"><span class="pre">LANGUAGE_CODE</span></code></a> setting.</li>
</ul>
<p>See <a class="reference internal" href="../../topics/i18n/translation.html#i18n-template-tags"><span class="std std-ref">i18n template tags</span></a> for template tags that
generate the same values.</p>
</div>
<div class="section" id="s-django-template-context-processors-media">
<span id="django-template-context-processors-media"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.media</span></code><a class="headerlink" href="#django-template-context-processors-media" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal notranslate"><span class="pre">MEDIA_URL</span></code>, providing the value of the <a class="reference internal" href="../settings.html#std:setting-MEDIA_URL"><code class="xref std std-setting docutils literal notranslate"><span class="pre">MEDIA_URL</span></code></a> setting.</p>
</div>
<div class="section" id="s-django-template-context-processors-static">
<span id="django-template-context-processors-static"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.static</span></code><a class="headerlink" href="#django-template-context-processors-static" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.static">
<code class="descname">static</code>()<a class="headerlink" href="#django.template.context_processors.static" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal notranslate"><span class="pre">STATIC_URL</span></code>, providing the value of the <a class="reference internal" href="../settings.html#std:setting-STATIC_URL"><code class="xref std std-setting docutils literal notranslate"><span class="pre">STATIC_URL</span></code></a> setting.</p>
</div>
<div class="section" id="s-django-template-context-processors-csrf">
<span id="django-template-context-processors-csrf"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.csrf</span></code><a class="headerlink" href="#django-template-context-processors-csrf" title="Permalink to this headline">¶</a></h4>
<p>This processor adds a token that is needed by the <a class="reference internal" href="builtins.html#std:templatetag-csrf_token"><code class="xref std std-ttag docutils literal notranslate"><span class="pre">csrf_token</span></code></a> template
tag for protection against <a class="reference internal" href="../csrf.html"><span class="doc">Cross Site Request Forgeries</span></a>.</p>
</div>
<div class="section" id="s-django-template-context-processors-request">
<span id="django-template-context-processors-request"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.request</span></code><a class="headerlink" href="#django-template-context-processors-request" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal notranslate"><span class="pre">request</span></code>, which is the current <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a>.</p>
</div>
<div class="section" id="s-django-template-context-processors-tz">
<span id="django-template-context-processors-tz"></span><h4><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.tz</span></code><a class="headerlink" href="#django-template-context-processors-tz" title="Permalink to this headline">¶</a></h4>
<dl class="function">
<dt id="django.template.context_processors.tz">
<code class="descname">tz</code>()<a class="headerlink" href="#django.template.context_processors.tz" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>

<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain a variable
<code class="docutils literal notranslate"><span class="pre">TIME_ZONE</span></code>, providing the name of the currently active time zone.</p>
</div>
<div class="section" id="s-django-contrib-messages-context-processors-messages">
<span id="django-contrib-messages-context-processors-messages"></span><h4><code class="docutils literal notranslate"><span class="pre">django.contrib.messages.context_processors.messages</span></code><a class="headerlink" href="#django-contrib-messages-context-processors-messages" title="Permalink to this headline">¶</a></h4>
<p>If this processor is enabled, every <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code> will contain these two
variables:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">messages</span></code> – A list of messages (as strings) that have been set
via the <a class="reference internal" href="../contrib/messages.html"><span class="doc">messages framework</span></a>.</li>
<li><code class="docutils literal notranslate"><span class="pre">DEFAULT_MESSAGE_LEVELS</span></code> – A mapping of the message level names to
<a class="reference internal" href="../contrib/messages.html#message-level-constants"><span class="std std-ref">their numeric value</span></a>.</li>
</ul>
</div>
</div>
<div class="section" id="s-writing-your-own-context-processors">
<span id="writing-your-own-context-processors"></span><h3>Writing your own context processors<a class="headerlink" href="#writing-your-own-context-processors" title="Permalink to this headline">¶</a></h3>
<p>A context processor has a simple interface: It’s a Python function that takes
one argument, an <a class="reference internal" href="../request-response.html#django.http.HttpRequest" title="django.http.HttpRequest"><code class="xref py py-class docutils literal notranslate"><span class="pre">HttpRequest</span></code></a> object, and returns a
dictionary that gets added to the template context. Each context processor
<em>must</em> return a dictionary.</p>
<p>Custom context processors can live anywhere in your code base. All Django
cares about is that your custom context processors are pointed to by the
<code class="docutils literal notranslate"><span class="pre">'context_processors'</span></code> option in your <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> setting — or the
<code class="docutils literal notranslate"><span class="pre">context_processors</span></code> argument of <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a> if you’re
using it directly.</p>
</div>
</div>
<div class="section" id="s-loading-templates">
<span id="loading-templates"></span><h2>Loading templates<a class="headerlink" href="#loading-templates" title="Permalink to this headline">¶</a></h2>
<p>Generally, you’ll store templates in files on your filesystem rather than
using the low-level <a class="reference internal" href="#django.template.Template" title="django.template.Template"><code class="xref py py-class docutils literal notranslate"><span class="pre">Template</span></code></a> API yourself. Save
templates in a directory specified as a <strong>template directory</strong>.</p>
<p>Django searches for template directories in a number of places, depending on
your template loading settings (see “Loader types” below), but the most basic
way of specifying template directories is by using the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> option.</p>
<div class="section" id="s-the-dirs-option">
<span id="the-dirs-option"></span><h3>The <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> option<a class="headerlink" href="#the-dirs-option" title="Permalink to this headline">¶</a></h3>
<p>Tell Django what your template directories are by using the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> option in the <a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> setting in your settings
file — or the <code class="docutils literal notranslate"><span class="pre">dirs</span></code> argument of <a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>. This
should be set to a list of strings that contain full paths to your template
directories:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[</span>
    <span class="p">{</span>
        <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
        <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="s1">&#39;/home/html/templates/lawrence.com&#39;</span><span class="p">,</span>
            <span class="s1">&#39;/home/html/templates/default&#39;</span><span class="p">,</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">]</span>
</pre></div>
</div>
<p>Your templates can go anywhere you want, as long as the directories and
templates are readable by the Web server. They can have any extension you want,
such as <code class="docutils literal notranslate"><span class="pre">.html</span></code> or <code class="docutils literal notranslate"><span class="pre">.txt</span></code>, or they can have no extension at all.</p>
<p>Note that these paths should use Unix-style forward slashes, even on Windows.</p>
</div>
<div class="section" id="s-loader-types">
<span id="s-template-loaders"></span><span id="loader-types"></span><span id="template-loaders"></span><h3>Loader types<a class="headerlink" href="#loader-types" title="Permalink to this headline">¶</a></h3>
<p>By default, Django uses a filesystem-based template loader, but Django comes
with a few other template loaders, which know how to load templates from other
sources.</p>
<p>Some of these other loaders are disabled by default, but you can activate them
by adding a <code class="docutils literal notranslate"><span class="pre">'loaders'</span></code> option to your <code class="docutils literal notranslate"><span class="pre">DjangoTemplates</span></code> backend in the
<a class="reference internal" href="../settings.html#std:setting-TEMPLATES"><code class="xref std std-setting docutils literal notranslate"><span class="pre">TEMPLATES</span></code></a> setting or passing a <code class="docutils literal notranslate"><span class="pre">loaders</span></code> argument to
<a class="reference internal" href="#django.template.Engine" title="django.template.Engine"><code class="xref py py-class docutils literal notranslate"><span class="pre">Engine</span></code></a>. <code class="docutils literal notranslate"><span class="pre">loaders</span></code> should be a list of strings or
tuples, where each represents a template loader class. Here are the template
loaders that come with Django:</p>
<p><code class="docutils literal notranslate"><span class="pre">django.template.loaders.filesystem.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.filesystem.Loader">
<em class="property">class </em><code class="descclassname">filesystem.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.filesystem.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from the filesystem, according to
<a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a>.</p>
<p>This loader is enabled by default. However it won’t find any templates
until you set <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DIRS</span></code></a> to a non-empty list:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
    <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
    <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BASE_DIR</span><span class="p">,</span> <span class="s1">&#39;templates&#39;</span><span class="p">)],</span>
<span class="p">}]</span>
</pre></div>
</div>
<p>You can also override <code class="docutils literal notranslate"><span class="pre">'DIRS'</span></code> and specify specific directories for a
particular filesystem loader:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
    <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
    <span class="s1">&#39;OPTIONS&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s1">&#39;loaders&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="p">(</span>
                <span class="s1">&#39;django.template.loaders.filesystem.Loader&#39;</span><span class="p">,</span>
                <span class="p">[</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BASE_DIR</span><span class="p">,</span> <span class="s1">&#39;templates&#39;</span><span class="p">)],</span>
            <span class="p">),</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">}]</span>
</pre></div>
</div>
</dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">django.template.loaders.app_directories.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.app_directories.Loader">
<em class="property">class </em><code class="descclassname">app_directories.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.app_directories.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from Django apps on the filesystem. For each app in
<a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a>, the loader looks for a <code class="docutils literal notranslate"><span class="pre">templates</span></code>
subdirectory. If the directory exists, Django looks for templates in there.</p>
<p>This means you can store templates with your individual apps. This also
helps to distribute Django apps with default templates.</p>
<p>For example, for this setting:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">INSTALLED_APPS</span> <span class="o">=</span> <span class="p">[</span><span class="s1">&#39;myproject.polls&#39;</span><span class="p">,</span> <span class="s1">&#39;myproject.music&#39;</span><span class="p">]</span>
</pre></div>
</div>
<p>…then <code class="docutils literal notranslate"><span class="pre">get_template('foo.html')</span></code> will look for <code class="docutils literal notranslate"><span class="pre">foo.html</span></code> in these
directories, in this order:</p>
<ul class="simple">
<li><code class="docutils literal notranslate"><span class="pre">/path/to/myproject/polls/templates/</span></code></li>
<li><code class="docutils literal notranslate"><span class="pre">/path/to/myproject/music/templates/</span></code></li>
</ul>
<p>… and will use the one it finds first.</p>
<p>The order of <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a> is significant! For example, if you
want to customize the Django admin, you might choose to override the
standard <code class="docutils literal notranslate"><span class="pre">admin/base_site.html</span></code> template, from <code class="docutils literal notranslate"><span class="pre">django.contrib.admin</span></code>,
with your own <code class="docutils literal notranslate"><span class="pre">admin/base_site.html</span></code> in <code class="docutils literal notranslate"><span class="pre">myproject.polls</span></code>. You must
then make sure that your <code class="docutils literal notranslate"><span class="pre">myproject.polls</span></code> comes <em>before</em>
<code class="docutils literal notranslate"><span class="pre">django.contrib.admin</span></code> in <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a>, otherwise
<code class="docutils literal notranslate"><span class="pre">django.contrib.admin</span></code>’s will be loaded first and yours will be ignored.</p>
<p>Note that the loader performs an optimization when it first runs:
it caches a list of which <a class="reference internal" href="../settings.html#std:setting-INSTALLED_APPS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">INSTALLED_APPS</span></code></a> packages have a
<code class="docutils literal notranslate"><span class="pre">templates</span></code> subdirectory.</p>
<p>You can enable this loader by setting <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-APP_DIRS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">APP_DIRS</span></code></a> to <code class="docutils literal notranslate"><span class="pre">True</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
    <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
    <span class="s1">&#39;APP_DIRS&#39;</span><span class="p">:</span> <span class="kc">True</span><span class="p">,</span>
<span class="p">}]</span>
</pre></div>
</div>
</dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">django.template.loaders.cached.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.cached.Loader">
<em class="property">class </em><code class="descclassname">cached.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.cached.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>By default (when <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a> is <code class="docutils literal notranslate"><span class="pre">True</span></code>), the template system reads
and compiles your templates every time they’re rendered. While the Django
template system is quite fast, the overhead from reading and compiling
templates can add up.</p>
<p>You configure the cached template loader with a list of other loaders that
it should wrap. The wrapped loaders are used to locate unknown templates
when they’re first encountered. The cached loader then stores the compiled
<code class="docutils literal notranslate"><span class="pre">Template</span></code> in memory. The cached <code class="docutils literal notranslate"><span class="pre">Template</span></code> instance is returned for
subsequent requests to load the same template.</p>
<p>This loader is automatically enabled if <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS['loaders']</span></code></a> isn’t specified and <a class="reference internal" href="../settings.html#std:setting-TEMPLATES-OPTIONS"><code class="xref std std-setting docutils literal notranslate"><span class="pre">OPTIONS['debug']</span></code></a> is <code class="docutils literal notranslate"><span class="pre">False</span></code> (the latter option defaults to the value
of <a class="reference internal" href="../settings.html#std:setting-DEBUG"><code class="xref std std-setting docutils literal notranslate"><span class="pre">DEBUG</span></code></a>).</p>
<p>You can also enable template caching with some custom template loaders
using settings like this:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
    <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
    <span class="s1">&#39;DIRS&#39;</span><span class="p">:</span> <span class="p">[</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">BASE_DIR</span><span class="p">,</span> <span class="s1">&#39;templates&#39;</span><span class="p">)],</span>
    <span class="s1">&#39;OPTIONS&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s1">&#39;loaders&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="p">(</span><span class="s1">&#39;django.template.loaders.cached.Loader&#39;</span><span class="p">,</span> <span class="p">[</span>
                <span class="s1">&#39;django.template.loaders.filesystem.Loader&#39;</span><span class="p">,</span>
                <span class="s1">&#39;django.template.loaders.app_directories.Loader&#39;</span><span class="p">,</span>
                <span class="s1">&#39;path.to.custom.Loader&#39;</span><span class="p">,</span>
            <span class="p">]),</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">}]</span>
</pre></div>
</div>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">All of the built-in Django template tags are safe to use with the
cached loader, but if you’re using custom template tags that come from
third party packages, or that you wrote yourself, you should ensure
that the <code class="docutils literal notranslate"><span class="pre">Node</span></code> implementation for each tag is thread-safe. For more
information, see <a class="reference internal" href="../../howto/custom-template-tags.html#template-tag-thread-safety"><span class="std std-ref">template tag thread safety considerations</span></a>.</p>
</div>
</dd></dl>

<p><code class="docutils literal notranslate"><span class="pre">django.template.loaders.locmem.Loader</span></code></p>
<dl class="class">
<dt id="django.template.loaders.locmem.Loader">
<em class="property">class </em><code class="descclassname">locmem.</code><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.locmem.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from a Python dictionary. This is useful for testing.</p>
<p>This loader takes a dictionary of templates as its first argument:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">TEMPLATES</span> <span class="o">=</span> <span class="p">[{</span>
    <span class="s1">&#39;BACKEND&#39;</span><span class="p">:</span> <span class="s1">&#39;django.template.backends.django.DjangoTemplates&#39;</span><span class="p">,</span>
    <span class="s1">&#39;OPTIONS&#39;</span><span class="p">:</span> <span class="p">{</span>
        <span class="s1">&#39;loaders&#39;</span><span class="p">:</span> <span class="p">[</span>
            <span class="p">(</span><span class="s1">&#39;django.template.loaders.locmem.Loader&#39;</span><span class="p">,</span> <span class="p">{</span>
                <span class="s1">&#39;index.html&#39;</span><span class="p">:</span> <span class="s1">&#39;content here&#39;</span><span class="p">,</span>
            <span class="p">}),</span>
        <span class="p">],</span>
    <span class="p">},</span>
<span class="p">}]</span>
</pre></div>
</div>
<p>This loader is disabled by default.</p>
</dd></dl>

<p>Django uses the template loaders in order according to the <code class="docutils literal notranslate"><span class="pre">'loaders'</span></code>
option. It uses each loader until a loader finds a match.</p>
</div>
</div>
<div class="section" id="s-custom-loaders">
<span id="s-custom-template-loaders"></span><span id="custom-loaders"></span><span id="custom-template-loaders"></span><h2>Custom loaders<a class="headerlink" href="#custom-loaders" title="Permalink to this headline">¶</a></h2>
<p>It’s possible to load templates from additional sources using custom template
loaders. Custom <code class="docutils literal notranslate"><span class="pre">Loader</span></code> classes should inherit from
<code class="docutils literal notranslate"><span class="pre">django.template.loaders.base.Loader</span></code> and define the <code class="docutils literal notranslate"><span class="pre">get_contents()</span></code> and
<code class="docutils literal notranslate"><span class="pre">get_template_sources()</span></code> methods.</p>
<div class="section" id="s-loader-methods">
<span id="loader-methods"></span><h3>Loader methods<a class="headerlink" href="#loader-methods" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.template.loaders.base.Loader">
<em class="property">class </em><code class="descname">Loader</code><a class="headerlink" href="#django.template.loaders.base.Loader" title="Permalink to this definition">¶</a></dt>
<dd><p>Loads templates from a given source, such as the filesystem or a database.</p>
<dl class="method">
<dt id="django.template.loaders.base.Loader.get_template_sources">
<code class="descname">get_template_sources</code>(<em>template_name</em>)<a class="headerlink" href="#django.template.loaders.base.Loader.get_template_sources" title="Permalink to this definition">¶</a></dt>
<dd><p>A method that takes a <code class="docutils literal notranslate"><span class="pre">template_name</span></code> and yields
<a class="reference internal" href="#django.template.base.Origin" title="django.template.base.Origin"><code class="xref py py-class docutils literal notranslate"><span class="pre">Origin</span></code></a> instances for each possible
source.</p>
<p>For example, the filesystem loader may receive <code class="docutils literal notranslate"><span class="pre">'index.html'</span></code> as a
<code class="docutils literal notranslate"><span class="pre">template_name</span></code> argument.  This method would yield origins for the
full path of <code class="docutils literal notranslate"><span class="pre">index.html</span></code> as it appears in each template directory
the loader looks at.</p>
<p>The method doesn’t need to verify that the template exists at a given
path, but it should ensure the path is valid. For instance, the
filesystem loader makes sure the path lies under a valid template
directory.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.loaders.base.Loader.get_contents">
<code class="descname">get_contents</code>(<em>origin</em>)<a class="headerlink" href="#django.template.loaders.base.Loader.get_contents" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns the contents for a template given a
<a class="reference internal" href="#django.template.base.Origin" title="django.template.base.Origin"><code class="xref py py-class docutils literal notranslate"><span class="pre">Origin</span></code></a> instance.</p>
<p>This is where a filesystem loader would read contents from the
filesystem, or a database loader would read from the database. If a
matching template doesn’t exist, this should raise a
<a class="reference internal" href="../../topics/templates.html#django.template.TemplateDoesNotExist" title="django.template.TemplateDoesNotExist"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TemplateDoesNotExist</span></code></a> error.</p>
</dd></dl>

<dl class="method">
<dt id="django.template.loaders.base.Loader.get_template">
<code class="descname">get_template</code>(<em>template_name</em>, <em>skip=None</em>)<a class="headerlink" href="#django.template.loaders.base.Loader.get_template" title="Permalink to this definition">¶</a></dt>
<dd><p>Returns a <code class="docutils literal notranslate"><span class="pre">Template</span></code> object for a given <code class="docutils literal notranslate"><span class="pre">template_name</span></code> by looping
through results from <a class="reference internal" href="#django.template.loaders.base.Loader.get_template_sources" title="django.template.loaders.base.Loader.get_template_sources"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_template_sources()</span></code></a> and calling
<a class="reference internal" href="#django.template.loaders.base.Loader.get_contents" title="django.template.loaders.base.Loader.get_contents"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_contents()</span></code></a>. This returns the first matching template. If no
template is found, <a class="reference internal" href="../../topics/templates.html#django.template.TemplateDoesNotExist" title="django.template.TemplateDoesNotExist"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TemplateDoesNotExist</span></code></a> is
raised.</p>
<p>The optional <code class="docutils literal notranslate"><span class="pre">skip</span></code> argument is a list of origins to ignore when
extending templates. This allow templates to extend other templates of
the same name. It also used to avoid recursion errors.</p>
<p>In general, it is enough to define <a class="reference internal" href="#django.template.loaders.base.Loader.get_template_sources" title="django.template.loaders.base.Loader.get_template_sources"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_template_sources()</span></code></a> and
<a class="reference internal" href="#django.template.loaders.base.Loader.get_contents" title="django.template.loaders.base.Loader.get_contents"><code class="xref py py-meth docutils literal notranslate"><span class="pre">get_contents()</span></code></a> for custom template loaders. <code class="docutils literal notranslate"><span class="pre">get_template()</span></code>
will usually not need to be overridden.</p>
</dd></dl>

</dd></dl>

<div class="admonition-building-your-own admonition">
<p class="first admonition-title">Building your own</p>
<p class="last">For examples, read the <a class="reference external" href="https://github.com/django/django/blob/master/django/template/loaders">source code for Django’s built-in loaders</a>.</p>
</div>
</div>
</div>
<div class="section" id="s-template-origin">
<span id="template-origin"></span><h2>Template origin<a class="headerlink" href="#template-origin" title="Permalink to this headline">¶</a></h2>
<p>Templates have an <code class="docutils literal notranslate"><span class="pre">origin</span></code> containing attributes depending on the source
they are loaded from.</p>
<dl class="class">
<dt id="django.template.base.Origin">
<em class="property">class </em><code class="descname">Origin</code>(<em>name</em>, <em>template_name=None</em>, <em>loader=None</em>)<a class="headerlink" href="#django.template.base.Origin" title="Permalink to this definition">¶</a></dt>
<dd><dl class="attribute">
<dt id="django.template.base.Origin.name">
<code class="descname">name</code><a class="headerlink" href="#django.template.base.Origin.name" title="Permalink to this definition">¶</a></dt>
<dd><p>The path to the template as returned by the template loader.
For loaders that read from the file system, this is the full
path to the template.</p>
<p>If the template is instantiated directly rather than through a
template loader, this is a string value of <code class="docutils literal notranslate"><span class="pre">&lt;unknown_source&gt;</span></code>.</p>
</dd></dl>

<dl class="attribute">
<dt id="django.template.base.Origin.template_name">
<code class="descname">template_name</code><a class="headerlink" href="#django.template.base.Origin.template_name" title="Permalink to this definition">¶</a></dt>
<dd><p>The relative path to the template as passed into the
template loader.</p>
<p>If the template is instantiated directly rather than through a
template loader, this is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
</dd></dl>

<dl class="attribute">
<dt id="django.template.base.Origin.loader">
<code class="descname">loader</code><a class="headerlink" href="#django.template.base.Origin.loader" title="Permalink to this definition">¶</a></dt>
<dd><p>The template loader instance that constructed this <code class="docutils literal notranslate"><span class="pre">Origin</span></code>.</p>
<p>If the template is instantiated directly rather than through a
template loader, this is <code class="docutils literal notranslate"><span class="pre">None</span></code>.</p>
<p><a class="reference internal" href="#django.template.loaders.cached.Loader" title="django.template.loaders.cached.Loader"><code class="xref py py-class docutils literal notranslate"><span class="pre">django.template.loaders.cached.Loader</span></code></a> requires all of its
wrapped loaders to set this attribute, typically by instantiating
the <code class="docutils literal notranslate"><span class="pre">Origin</span></code> with <code class="docutils literal notranslate"><span class="pre">loader=self</span></code>.</p>
</dd></dl>

</dd></dl>

</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="#">The Django template language: for Python programmers</a><ul>
<li><a class="reference internal" href="#overview">Overview</a></li>
<li><a class="reference internal" href="#configuring-an-engine">Configuring an engine</a></li>
<li><a class="reference internal" href="#loading-a-template">Loading a template</a></li>
<li><a class="reference internal" href="#rendering-a-context">Rendering a context</a><ul>
<li><a class="reference internal" href="#variables-and-lookups">Variables and lookups</a></li>
<li><a class="reference internal" href="#how-invalid-variables-are-handled">How invalid variables are handled</a></li>
<li><a class="reference internal" href="#built-in-variables">Built-in variables</a></li>
<li><a class="reference internal" href="#limitations-with-string-literals">Limitations with string literals</a></li>
</ul>
</li>
<li><a class="reference internal" href="#playing-with-context-objects">Playing with <code class="docutils literal notranslate"><span class="pre">Context</span></code> objects</a><ul>
<li><a class="reference internal" href="#using-requestcontext">Using <code class="docutils literal notranslate"><span class="pre">RequestContext</span></code></a></li>
<li><a class="reference internal" href="#built-in-template-context-processors">Built-in template context processors</a><ul>
<li><a class="reference internal" href="#django-contrib-auth-context-processors-auth"><code class="docutils literal notranslate"><span class="pre">django.contrib.auth.context_processors.auth</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-debug"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.debug</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-i18n"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.i18n</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-media"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.media</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-static"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.static</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-csrf"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.csrf</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-request"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.request</span></code></a></li>
<li><a class="reference internal" href="#django-template-context-processors-tz"><code class="docutils literal notranslate"><span class="pre">django.template.context_processors.tz</span></code></a></li>
<li><a class="reference internal" href="#django-contrib-messages-context-processors-messages"><code class="docutils literal notranslate"><span class="pre">django.contrib.messages.context_processors.messages</span></code></a></li>
</ul>
</li>
<li><a class="reference internal" href="#writing-your-own-context-processors">Writing your own context processors</a></li>
</ul>
</li>
<li><a class="reference internal" href="#loading-templates">Loading templates</a><ul>
<li><a class="reference internal" href="#the-dirs-option">The <code class="docutils literal notranslate"><span class="pre">DIRS</span></code> option</a></li>
<li><a class="reference internal" href="#loader-types">Loader types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#custom-loaders">Custom loaders</a><ul>
<li><a class="reference internal" href="#loader-methods">Loader methods</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-origin">Template origin</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="builtins.html"
                        title="previous chapter">Built-in template tags and filters</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="../template-response.html"
                        title="next chapter"><code class="docutils literal notranslate"><span class="pre">TemplateResponse</span></code> and <code class="docutils literal notranslate"><span class="pre">SimpleTemplateResponse</span></code></a></p>
  <div role="note" aria-label="source link">
    <h3>This Page</h3>
    <ul class="this-page-menu">
      <li><a href="../../_sources/ref/templates/api.txt"
            rel="nofollow">Show Source</a></li>
    </ul>
   </div>
<div id="searchbox" style="display: none" role="search">
  <h3>Quick search</h3>
    <div class="searchformwrapper">
    <form class="search" action="../../search.html" method="get">
      <input type="text" name="q" />
      <input type="submit" value="Go" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
              <h3>Last update:</h3>
              <p class="topless">Apr 06, 2021</p>
          </div>
        
      
    </div>

    <div id="ft">
      <div class="nav">
    &laquo; <a href="builtins.html" title="Built-in template tags and filters">previous</a>
     |
    <a href="../index.html" title="API Reference" accesskey="U">up</a>
   |
    <a href="../template-response.html" title="&lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;TemplateResponse&lt;/span&gt;&lt;/code&gt; and &lt;code class=&#34;docutils literal notranslate&#34;&gt;&lt;span class=&#34;pre&#34;&gt;SimpleTemplateResponse&lt;/span&gt;&lt;/code&gt;">next</a> &raquo;</div>
    </div>
  </div>

      <div class="clearer"></div>
    </div>
  </body>
</html>