  **New in Django development version**
  
  The output from template tags is **not** automatically run through the
  auto-escaping filters. However, there are still a couple of things you should
  keep in mind when writing a template tag:
  
  If the ``render()`` function of your template stores the result in a context
  variable (rather than returning the result in a string), it should take care
  to call ``mark_safe()`` if appropriate. When the variable is ultimately
  rendered, it will be affected by the auto-escape setting in effect at the
 
</s> remove When you are writing a custom filter, you need to give some thought to how
this filter will interact with Django's auto-escaping behaviour.  Firstly, you
should realise that there are three types of strings that can be passed around
inside the template code:

 * raw strings are the native Python ``str`` or ``unicode`` types. On
   output, they are escaped if auto-escaping is in effect and presented
   unchanged, otherwise.

 * "safe" strings are strings that are safe from further escaping at output
   time. Any necessary escaping has already been done. They are commonly used
   for output that contains raw HTML that is intended to be intrepreted on the
   client side.

   Internally, these strings are of type ``SafeString`` or ``SafeUnicode``,
   although they share a common base class in ``SafeData``, so you can test
   for them using code like::

    if isinstance(value, SafeData):
        # Do something with the "safe" string.

 * strings which are marked as "needing escaping" are *always* escaped on
   output, regardless of whether they are in an ``autoescape`` block or not.
   These strings are only escaped once, however, even if auto-escaping
   applies. This type of string is internally represented by the types
   ``EscapeString`` and ``EscapeUnicode``. You will not normally need to worry
   about these; they exist for the implementation of the ``escape`` filter.

When you are writing a filter, your code will typically fall into one of two
situations:

 1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``,
    ``'``, ``"`` or ``&``) into the result that were not already present. In
    this case, you can let Django take care of all the auto-escaping handling
    for you. All you need to do is put the ``is_safe`` attribute on your
    filter function and set it to ``True``. This attribute tells Django that
    is a "safe" string is passed into your filter, the result will still be
    "safe" and if a non-safe string is passed in, Django will automatically
    escape it, if necessary. The reason ``is_safe`` is necessary is because
    there are plenty of normal string operations that will turn a ``SafeData``
    object back into a normal ``str`` or ``unicode`` object and, rather than
    try to catch them all, which would be very difficult, Django repairs the
    damage after the filter has completed.

    For example, suppose you have a filter that adds the string ``xx`` to the
    end of any input. Since this introduces no dangerous HTML characters into
    the result (aside from any that were already present), you should mark
    your filter with ``is_safe``::
 </s> add When writing a custom filter, give some thought to how the filter will interact
with Django's auto-escaping behavior. Note that three types of strings can be
passed around inside the template code:

    * **Raw strings** are the native Python ``str`` or ``unicode`` types. On
      output, they're escaped if auto-escaping is in effect and presented
      unchanged, otherwise.

    * **Safe strings** are strings that have been marked safe from further
      escaping at output time. Any necessary escaping has already been done.
      They're commonly used for output that contains raw HTML that is intended
      to be interpreted as-is on the client side.

      Internally, these strings are of type ``SafeString`` or ``SafeUnicode``.
      They share a common base class of ``SafeData``, so you can test
      for them using code like::

          if isinstance(value, SafeData):
              # Do something with the "safe" string.

    * **Strings marked as "needing escaping"** are *always* escaped on
      output, regardless of whether they are in an ``autoescape`` block or not.
      These strings are only escaped once, however, even if auto-escaping
      applies.

      Internally, these strings are of type ``EscapeString`` or
      ``EscapeUnicode``. Generally you don't have to worry about these; they
      exist for the implementation of the ``escape`` filter.

Template filter code falls into one of two situations:

    1. Your filter does not introduce any HTML-unsafe characters (``<``, ``>``,
       ``'``, ``"`` or ``&``) into the result that were not already present. In
       this case, you can let Django take care of all the auto-escaping
       handling for you. All you need to do is put the ``is_safe`` attribute on
       your filter function and set it to ``True``, like so::

           @register.filter
           def myfilter(value):
               return value
           myfilter.is_safe = True

       This attribute tells Django that if a "safe" string is passed into your
       filter, the result will still be "safe" and if a non-safe string is
       passed in, Django will automatically escape it, if necessary.

       You can think of this as meaning "this filter is safe -- it doesn't
       introduce any possibility of unsafe HTML."

       The reason ``is_safe`` is necessary is because there are plenty of
       normal string operations that will turn a ``SafeData`` object back into
       a normal ``str`` or ``unicode`` object and, rather than try to catch
       them all, which would be very difficult, Django repairs the damage after
       the filter has completed.

       For example, suppose you have a filter that adds the string ``xx`` to the
       end of any input. Since this introduces no dangerous HTML characters to
       the result (aside from any that were already present), you should mark
       your filter with ``is_safe``:: </s> remove     When this filter is used in a template where auto-escaping is enabled,
    Django will escape the output whenever the input is not already marked as
    "safe".

    By default, ``is_safe`` defaults to ``False`` and you can omit it from
    any filters where it isn't required.

    Be careful when deciding if your filter really does leave safe strings
    as safe. Sometimes if you are *removing* characters, you can
    inadvertently leave unbalanced HTML tags or entities in the result.
    For example, removing a ``>`` from the input might turn ``<a>`` into
    ``<a``, which would need to be escaped on output to avoid causing
    problems. Similarly, removing a semicolon (``;``) can turn ``&amp;``
    into ``&amp``, which is no longer a valid entity and thus needs
    further escaping. Most cases won't be nearly this tricky, but keep an
    eye out for any problems like that when reviewing your code.

 2. Alternatively, your filter code can manually take care of any necessary
    escaping. This is usually necessary when you are introducing new HTML
    markup into the result. You want to mark the output as safe from further
    escaping so that your HTML markup isn't escaped further, so you'll need to
    handle the input yourself.

    To mark the output as a safe string, use
    ``django.utils.safestring.mark_safe()``.

    Be careful, though. You need to do more than just mark the output as
    safe. You need to ensure it really *is* safe and what you do will often
    depend upon whether or not auto-escaping is in effect. The idea is to
    write filters than can operate in templates where auto-escaping is either
    on or off in order to make things easier for your template authors.

    In order for you filter to know the current auto-escaping state, set the
    ``needs_autoescape`` attribute to ``True`` on your function (if you don't
    specify this attribute, it defaults to ``False``). This attribute tells
    Django that your filter function wants to be passed an extra keyword
    argument, called ``autoescape`` that is ``True`` is auto-escaping is in
    effect and ``False`` otherwise.

    An example might make this clearer. Let's write a filter that emphasizes
    the first character of a string::

        from django.utils.html import conditional_escape
        from django.utils.safestring import mark_safe

        def initial_letter_filter(text, autoescape=None):
            first, other = text[0] ,text[1:]
            if autoescape:
                esc = conditional_escape
            else:
                esc = lambda x: x
            result = '<strong>%s</strong>%s' % (esc(first), esc(other))
            return mark_safe(result)
        initial_letter_filter.needs_autoescape = True

    The ``needs_autoescape`` attribute on the filter function and the
    ``autoescape`` keyword argument mean that our function will know whether
    or not automatic escaping is in effect when the filter is called. We use
    ``autoescape`` to decide whether the input data needs to be passed through
    ``django.utils.html.conditional_escape`` or not (in the latter case, we
    just use the identity function as the "escape" function). The
    ``conditional_escape()`` function is like ``escape()`` except it only
    escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
    instance is passed to ``conditional_escape()``, the data is returned
    unchanged.

    Finally, in the above example, we remember to mark the result as safe
    so that our HTML is inserted directly into the template without further
    escaping.

    There is no need to worry about the ``is_safe`` attribute in this case
    (although including it wouldn't hurt anything). Whenever you are manually
    handling the auto-escaping issues and returning a safe string, the
    ``is_safe`` attribute won't change anything either way.
 </s> add        When this filter is used in a template where auto-escaping is enabled,
       Django will escape the output whenever the input is not already marked as
       "safe".

       By default, ``is_safe`` defaults to ``False``, and you can omit it from
       any filters where it isn't required.

       Be careful when deciding if your filter really does leave safe strings
       as safe. If you're *removing* characters, you might inadvertently leave
       unbalanced HTML tags or entities in the result. For example, removing a
       ``>`` from the input might turn ``<a>`` into ``<a``, which would need to
       be escaped on output to avoid causing problems. Similarly, removing a
       semicolon (``;``) can turn ``&amp;`` into ``&amp``, which is no longer a
       valid entity and thus needs further escaping. Most cases won't be nearly
       this tricky, but keep an eye out for any problems like that when
       reviewing your code.

    2. Alternatively, your filter code can manually take care of any necessary
       escaping. This is necessary when you're introducing new HTML markup into
       the result. You want to mark the output as safe from further
       escaping so that your HTML markup isn't escaped further, so you'll need
       to handle the input yourself.

       To mark the output as a safe string, use ``django.utils.safestring.mark_safe()``.

       Be careful, though. You need to do more than just mark the output as
       safe. You need to ensure it really *is* safe, and what you do depends on
       whether auto-escaping is in effect. The idea is to write filters than
       can operate in templates where auto-escaping is either on or off in
       order to make things easier for your template authors.

       In order for you filter to know the current auto-escaping state, set the
       ``needs_autoescape`` attribute to ``True`` on your function. (If you
       don't specify this attribute, it defaults to ``False``). This attribute
       tells Django that your filter function wants to be passed an extra
       keyword argument, called ``autoescape``, that is ``True`` is
       auto-escaping is in effect and ``False`` otherwise.

       For example, let's write a filter that emphasizes the first character of
       a string::

           from django.utils.html import conditional_escape
           from django.utils.safestring import mark_safe

           def initial_letter_filter(text, autoescape=None):
               first, other = text[0], text[1:]
               if autoescape:
                   esc = conditional_escape
               else:
                   esc = lambda x: x
               result = '<strong>%s</strong>%s' % (esc(first), esc(other))
               return mark_safe(result)
           initial_letter_filter.needs_autoescape = True

       The ``needs_autoescape`` attribute on the filter function and the
       ``autoescape`` keyword argument mean that our function will know whether
       automatic escaping is in effect when the filter is called. We use
       ``autoescape`` to decide whether the input data needs to be passed through
       ``django.utils.html.conditional_escape`` or not. (In the latter case, we
       just use the identity function as the "escape" function.) The
       ``conditional_escape()`` function is like ``escape()`` except it only
       escapes input that is **not** a ``SafeData`` instance. If a ``SafeData``
       instance is passed to ``conditional_escape()``, the data is returned
       unchanged.

       Finally, in the above example, we remember to mark the result as safe
       so that our HTML is inserted directly into the template without further
       escaping.

       There's no need to worry about the ``is_safe`` attribute in this case
       (although including it wouldn't hurt anything). Whenever you manually
       handle the auto-escaping issues and return a safe string, the
       ``is_safe`` attribute won't change anything either way. </s> remove this would always display a Javascript alert box when the page was loaded.
Similarly, if you were displaying some data generated by another process and it
contained a '<' symbol, you couldn't just dump this straight into your HTML,
because it would be treated as the start of an element. The effects of these
sorts of problems can vary from merely annoying to allowing exploits via `Cross
Site Scripting`_ (XSS) attacks.

.. _Cross Site Scripting: http://en.wikipedia.org/wiki/Cross-site_scripting

In order to provide some protection against these problems, Django
provides automatic (but controllable) HTML escaping for data coming from
tempate variables. Inside this tag, any data that comes from template
variables is examined to see if it contains one of the five HTML characters
(<, >, ', " and &) that often need escaping and those characters are converted
to their respective HTML entities. It causes no harm if a character is
converted to an entity when it doesn't need to be, so all five characters are
always converted.

Since some variables will contain data that is *intended* to be rendered
as HTML, template tag and filter writers can mark their output strings as
requiring no further escaping. For example, the ``unordered_list`` filter is
designed to return raw HTML and we want the template processor to simply
display the results as returned, without applying any escaping. That is taken
care of by the filter. The template author need do nothing special in that
case.

By default, automatic HTML escaping is always applied. However, sometimes you
will not want this to occur (for example, if you're using the templating
system to create an email). To control automatic escaping inside your template,
wrap the affected content in the ``autoescape`` tag, like so::
 </s> add With this name value, the template would be rendered as::

    Hello, <script>alert('hello')</script>

...which means the browser would pop-up a JavaScript alert box!

Similarly, what if the name contained a ``'<'`` symbol, like this?

    <b>username

That would result in a rendered template like this::

    Hello, <b>username

...which, in turn, would result in the remainder of the Web page being bolded!

Clearly, user-submitted data shouldn't be trusted blindly and inserted directly
into your Web pages, because a malicious user could use this kind of hole to
do potentially bad things. This type of security exploit is called a
Cross Site Scripting`_ (XSS) attack.

To avoid this problem, you have two options:

    * One, you can make sure to run each untrusted variable through the
      ``escape`` filter (documented below), which converts potentially harmful
      HTML characters to unharmful ones. This was default the default solution
      in Django for its first few years, but the problem is that it puts the
      onus on *you*, the developer / template author, to ensure you're escaping
      everything. It's easy to forget to escape data.

    * Two, you can take advantage of Django's automatic HTML escaping. The
      remainder of this section describes how auto-escaping works.

By default in the Django development version, every template automatically
escapes the output of every variable tag. Specifically, these five characters
are escaped:

    * ``<`` is converted to ``&lt;``
    * ``>`` is converted to ``&gt;``
    * ``'`` (single quote) is converted to ``&#39;``
    * ``"`` (double quote) is converted to ``&quot;``
    * ``&`` is converted to ``&amp;``

Again, we stress that this behavior is on by default. If you're using Django's
template system, you're protected.

How to turn it off
------------------

If you don't want data to be auto-escaped, on a per-site, per-template level or
per-variable level, you can turn it off in several ways.

Why would you want to turn it off? Because sometimes, template variables
contain data that you *intend* to be rendered as raw HTML, in which case you
don't want their contents to be escaped. For example, you might store a blob of
HTML in your database and want to embed that directly into your template. Or,
you might be using Django's template system to produce text that is *not* HTML
-- like an e-mail message, for instance.

For individual variables
~~~~~~~~~~~~~~~~~~~~~~~~

To disable auto-escaping for an individual variable, use the ``safe`` filter::

    This will be escaped: {{ data }}
    This will not be escaped: {{ data|safe }}

Think of *safe* as shorthand for *safe from further escaping* or *can be
safely interpreted as HTML*. In this example, if ``data`` contains ``'<b>'``,
the output will be::

    This will be escaped: &lt;b&gt;
    This will not be escaped: <b>

For template blocks
~~~~~~~~~~~~~~~~~~~

To control auto-escaping for a template, wrap the template (or just a
particular section of the template) in the ``autoescape`` tag, like so:: </s> remove A very real problem when creating HTML (and other) output using templates and
variable substitution is the possibility of accidently inserting some variable
value that affects the resulting HTML. For example, a template fragment such as
::
 </s> add When generating HTML from templates, there's always a risk that a variable will
include characters that affect the resulting HTML. For example, consider this
template fragment:: </s> remove     This will be escaped: &lt;a&gt;
    This will not be escaped: <a>

Generally, you won't need to worry about auto-escaping very much. View
developers and custom filter authors need to think about when their data
shouldn't be escaped and mark it appropriately. They are in a better position
to know when that should happen than the template author, so it is their
responsibility. By default, all output is escaped unless the template
processor is explicitly told otherwise.

You should also note that if you are trying to write a template that might be
used in situations where automatic escaping is enabled or disabled and you
don't know which (such as when your template is included in other templates),
you can safely write as if you were in an ``{% autoescape off %}`` situation.
Scatter ``escape`` filters around for any variables that need escaping. When
auto-escaping is on, these extra filters won't change the output -- any
variables that use the ``escape`` filter do not have further automatic
escaping applied to them.
 </s> add If you're creating a template that might be used in situations where you're
not sure whether auto-escaping is enabled, then add an ``escape`` filter to any
variable that needs escaping. When auto-escaping is on, there's no danger of
the ``escape`` filter *double-escaping* data -- the ``escape`` filter does not
affect auto-escaped variables.
keep in mind when writing a template tag.
  **New in Django development version**
  
  The output from template tags is **not** automatically run through the
  auto-escaping filters. However, there are still a couple of things you should
keep in mind when writing a template tag.
  
  If the ``render()`` function of your template stores the result in a context
  variable (rather than returning the result in a string), it should take care
  to call ``mark_safe()`` if appropriate. When the variable is ultimately
  rendered, it will be affected by the auto-escape setting in effect at the
keep keep keep keep replace keep keep keep keep keep
 Edited templates.txt and templates_python.txt auto-escaping changes from [6671]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6798 bcc190cf-cafb-0310-a4f2-bffc1f526a37 
docs/templates_python.txt