13.5 The context: Context, RequestContext and context processors

The stack: BaseContext

The levels are the list BaseContext.dicts, bottom first. The bottom level, made with each context, holds "True", "False" and "None": the language has no literals for them, and {{ None }} is a lookup that ends there unless a level above holds the name. A dictionary given to the constructor becomes the next level itself, not a copy.

BaseContext.__getitem__ and BaseContext.get read from the highest level that holds the name; BaseContext.__setitem__ writes to the top level, and BaseContext.setdefault does so only when no level holds the name. BaseContext.set_upward writes to the highest level that already holds it, or else to the top: a named {% cycle %} uses it, so a turn of the cycle inside a {% with %} updates the name where it already stands, and {% endwith %} does not undo it.

BaseContext.push appends a new level made from a dictionary and keyword arguments, and returns it: a ContextDict, a dictionary that is also a context manager, so that with context.push(ship=ship): pops on the way out. Its exit calls BaseContext.pop, which removes the top level, whichever that is, so pushes and pops inside the with must pair up. pop refuses the bottom level, with ContextPopException.

BaseContext.new returns a copy that keeps the context’s attributes but has a fresh stack: the bottom level and the values given. BaseContext.flatten merges the levels into one dictionary, the higher winning, and BaseContext.__eq__ compares by it.

Context: the flags and the bound template

Context is the stack a render uses. Beside the levels it carries Context.autoescape, Context.use_l10n and Context.use_tz, which say whether a value written out is escaped, localised and converted to the current time zone; None, the default of the last two, means localise, and convert when USE_TZ is true. They are attributes, not levels, so push and pop leave them alone: {% autoescape %}, {% localize %} and {% localtime %} each set one for their body and restore it after (Autoescaping and safe strings). Context.render_context is a second stack, a RenderContext, in which nodes keep their own state (Rendering: nodes and the render context).

Context.template is the template the context is bound to, and None outside a render. Template.render binds the context with Context.bind_template only when nothing is bound yet, so the one bound is the outermost: a template it extends or includes finds the context bound. The binding ends with the render. The bound template is how a node reaches its engine: Variable._resolve_lookup reads "string_if_invalid" through it, Node.render_annotated reads "debug", and IncludeNode.render loads the included template. Context.template_name holds its name, for the log record of a failed lookup (Variables and filters: FilterExpression and Variable).

Context.update pushes a mapping as a new level; unlike dict.update, it changes no level already there.

RequestContext and the processors’ level

RequestContext is a Context made from a request, which it keeps as RequestContext.request, with any processors passed as processors=. Its constructor notes the height of the stack in RequestContext._processors_index and pushes two empty levels. The first holds the place of the processors’ output. The second, its comment says, is for new modifications, so that context processors don’t overwrite them: a name set on the context while that level is the top lands there, above the held place.

The processors run when a template is bound, not when the context is made: a RequestContext has no engine, and takes the processors from the bound template’s engine. RequestContext.bind_template calls the processors of that engine’s Engine.template_context_processors, then the context’s own, each with the request; merges the dictionaries they return, a later processor’s name replacing an earlier one’s; and puts the result in the held place, replacing the empty level rather than pushing, so that what is already above it stays above. When the render ends it empties the place again. So the processors run once for each render of an outermost template, and their names exist only while it lasts.

RequestContext.new returns a context with no held place: the stack is reset to the bottom level and the values given, and the index deleted, a comment says for backwards compatibility. A template included by {% include … only %} sees no "csrf_token" or "request"; InclusionNode.render, which also renders against new, copies "csrf_token" across, because, its comment says, inclusion tags are often used for forms.

make_context: the view’s values on top

The backend’s template wrapper makes its context with make_context, from the view’s dictionary and the request, if any. Without a request, make_context makes a Context with the dictionary as the level above the bottom. With one, it makes a RequestContext with no dictionary, then pushes the view’s dictionary on top, unless it is empty.

The order is the point; the comment there says it ensures values from the context override those from the processors. Given to the constructor, the view’s dictionary would sit under the held place, where a processor’s name would hide the view’s. In the Jinja2 backend it is the other way round (Template engines: TEMPLATES and the backends).

The engine’s processors

Engine.template_context_processors imports the paths of the engine’s "context_processors" option, after the one path in _builtin_context_processors: the CSRF processor, hard-coded, a comment says, for easier use of CSRF protection. It comes first whether the option names it or not, and the option’s default is an empty list, so every render of a RequestContext has the "csrf_token" that {% csrf_token %} reads.

A processor runs whether or not the template uses its names. The CSRF processor defers its call of get_token with a SimpleLazyObject, as the docstring of get_token advises, since calling it makes the CSRF middleware add a cookie to the response.

The processors of django/template/context_processors.py:

The tags that push a level

Among the built-in tags, these push a level for the names they give their body, and pop it when the body is done:

• {% for %}: ForNode.render pushes one level for the whole loop, holding "forloop" and the loop variable, which each item overwrites; the enclosing "forloop", read first, becomes "parentloop". An item unpacked into several names gets a level of its own.
• {% with %}: WithNode.render resolves its values, then pushes them for its body (The built-in tags).
• {% include %} and {% block %}: IncludeNode.render pushes the values the tag names, or for {% include … only %} renders against new; BlockNode.render pushes a level holding "block", through which {{ block.super }} reaches the parent’s block (Inheritance and inclusion: {% extends %}, {% block %} and {% include %}).

A tag that stores a value under a name, as {% url … as link %} and {% firstof … as title %} do, sets it on the top level, so the name lasts until that level is popped: set inside a {% with %} or a {% for %}, it is gone after the end tag. A named {% cycle %} is the exception: it writes with BaseContext.set_upward.