Utilities

These helper functions and classes are useful if you add custom filters orfunctions to a Jinja2 environment.

  • jinja2.environmentfilter(f)
  • Decorator for marking environment dependent filters. The currentEnvironment is passed to the filter as first argument.
  • jinja2.contextfilter(f)
  • Decorator for marking context dependent filters. The currentContext will be passed as first argument.
  • jinja2.evalcontextfilter(f)
  • Decorator for marking eval-context dependent filters. An evalcontext object is passed as first argument. For more informationabout the eval context, see Evaluation Context.

Changelog

New in version 2.4.

  • jinja2.environmentfunction(f)
  • This decorator can be used to mark a function or method as environmentcallable. This decorator works exactly like the contextfunction()decorator just that the first argument is the active Environmentand not context.
  • jinja2.contextfunction(f)
  • This decorator can be used to mark a function or method context callable.A context callable is passed the active Context as first argument whencalled from the template. This is useful if a function wants to get accessto the context or functions provided on the context object. For examplea function that returns a sorted list of template variables the currenttemplate exports could look like this:
  1. @contextfunction
  2. def get_exported_names(context):
  3.     return sorted(context.exported_vars)
  • jinja2.evalcontextfunction(f)
  • This decorator can be used to mark a function or method as an evalcontext callable. This is similar to the contextfunction()but instead of passing the context, an evaluation context object ispassed. For more information about the eval context, seeEvaluation Context.

Changelog

New in version 2.4.

  • jinja2.clear_caches()
  • Jinja2 keeps internal caches for environments and lexers. These areused so that Jinja2 doesn’t have to recreate environments and lexers allthe time. Normally you don’t have to care about that but if you aremeasuring memory consumption you may want to clean the caches.
  • jinja2.isundefined(_obj)
  • Check if the object passed is undefined. This does nothing more thanperforming an instance check against Undefined but looks nicer.This can be used for custom filters or tests that want to react toundefined variables. For example a custom default filter can look likethis:
  1. def default(var, default=''):
  2.     if is_undefined(var):
  3.         return default
  4.     return var
  • markupsafe.escape(s) → markup
  • Convert the characters &, <, >, ‘, and ” in string s to HTML-safesequences. Use this if you need to display text that might containsuch characters in HTML. Marks return value as markup string.
  • class markupsafe.Markup
  • A string that is ready to be safely inserted into an HTML or XMLdocument, either because it was escaped or because it was markedsafe.

Passing an object to the constructor converts it to text and wrapsit to mark it safe without escaping. To escape the text, use theescape() class method instead.

  1. >>> Markup('Hello, <em>World</em>!')
  2. Markup('Hello, <em>World</em>!')
  3. >>> Markup(42)
  4. Markup('42')
  5. >>> Markup.escape('Hello, <em>World</em>!')
  6. Markup('Hello &lt;em&gt;World&lt;/em&gt;!')

This implements the html() interface that some frameworksuse. Passing an object that implements html() will wrap theoutput of that method, marking it safe.

  1. >>> class Foo:
  2. ...     def __html__(self):
  3. ...         return '<a href="/foo">foo</a>'
  4. ...
  5. >>> Markup(Foo())
  6. Markup('<a href="/foo">foo</a>')

This is a subclass of the text type (str in Python 3,unicode in Python 2). It has the same methods as that type, butall methods escape their arguments and return a Markup instance.

  1. >>> Markup('<em>%s</em>') % 'foo & bar'
  2. Markup('<em>foo &amp; bar</em>')
  3. >>> Markup('<em>Hello</em> ') + '<foo>'
  4. Markup('<em>Hello</em> &lt;foo&gt;')
  • classmethod escape(s)

  • Escape a string. Calls escape() and ensures that forsubclasses the correct type is returned.

  • striptags()

  • unescape() the markup, remove tags, and normalizewhitespace to single spaces.
  1. >>> Markup('Main &raquo;        <em>About</em>').striptags()
  2. 'Main » About'
  • unescape()
  • Convert escaped markup back into a text string. This replacesHTML entities with the characters they represent.
  1. >>> Markup('Main &raquo; <em>About</em>').unescape()
  2. 'Main » <em>About</em>'