The Context

  • class jinja2.runtime.Context
  • The template context holds the variables of a template. It stores thevalues passed to the template and also the names the template exports.Creating instances is neither supported nor useful as it’s createdautomatically at various stages of the template evaluation and should notbe created by hand.

The context is immutable. Modifications on parentmust nothappen and modifications on vars are allowed from generatedtemplate code only. Template filters and global functions marked ascontextfunction()s get the active context passed as first argumentand are allowed to access the context read-only.

The template context supports read only dict operations (get,keys, values, items, iterkeys, itervalues, iteritems,getitem, contains). Additionally there is a resolve()method that doesn’t fail with a KeyError but returns anUndefined object for missing variables.

  • parent

  • A dict of read only, global variables the template looks up. Thesecan either come from another Context, from theEnvironment.globals or Template.globals or pointsto a dict created by combining the globals with the variablespassed to the render function. It must not be altered.

  • vars

  • The template local variables. This list contains environment andcontext functions from the parent scope as well as localmodifications and exported variables from the template. The templatewill modify this dict during template evaluation but filters andcontext functions are not allowed to modify it.

  • environment

  • The environment that loaded the template.

  • exported_vars

  • This set contains all the names the template exports. The values forthe names are in the vars dict. In order to get a copy of theexported variables as dict, get_exported() can be used.

  • name

  • The load name of the template owning this context.

  • blocks

  • A dict with the current mapping of blocks in the template. The keysin this dict are the names of the blocks, and the values a list ofblocks registered. The last item in each list is the current activeblock (latest in the inheritance chain).

  • eval_ctx

  • The current Evaluation Context.

  • call(callable, *args, **kwargs)

  • Call the callable with the arguments and keyword argumentsprovided but inject the active context or environment as firstargument if the callable is a contextfunction() orenvironmentfunction().

  • get_all()

  • Return the complete context as dict including the exportedvariables. For optimizations reasons this might not return anactual copy so be careful with using it.

  • get_exported()

  • Get a new dict with the exported variables.

  • resolve(key)

  • Looks up a variable like getitem or get but returns anUndefined object with the name of the name looked up.

Implementation

Context is immutable for the same reason Python’s frame locals areimmutable inside functions. Both Jinja2 and Python are not using thecontext / frame locals as data storage for variables but only as primarydata source.

When a template accesses a variable the template does not define, Jinja2looks up the variable in the context, after that the variable is treatedas if it was defined in the template.