Ticket #2359: 01-core-changes.4.diff

a/django/oldforms/__init__.py

@@ -1 +1 @@
-from django.core import validators
-from django.core.exceptions import PermissionDenied
-from django.utils.html import escape
+from django.utils.safestring import mark_safe
-from django.conf import settings
-from django.utils.translation import gettext, ngettext
-
@@ -183 +184 @@
-
-    def html_error_list(self):
-        if self.errors():
-'<ul class="errorlist"><li>%s</li></ul>' % '</li><li>'.join([escape(e) for e in self.errors()]
+mark_safe('<ul class="errorlist"><li>%s</li></ul>' % '</li><li>'.join([escape(e) for e in self.errors()])
-        else:
-''
+mark_safe('')
-
-    def get_id(self):
-        return self.formfield.get_id()
@@ -217 +218 @@
-        return bool(len(self.errors()))
-
-    def html_combined_error_list(self):
-''.join([field.html_error_list() for field in self.formfield_dict.values() if hasattr(field, 'errors')]
+mark_safe(''.join([field.html_error_list() for field in self.formfield_dict.values() if hasattr(field, 'errors')])
-
-class InlineObjectCollection(object):
-    "An object that acts like a sparse list of form field collections."
@@ -404 +405 @@
-            maxlength = 'maxlength="%s" ' % self.maxlength
-        if isinstance(data, unicode):
-            data = data.encode(settings.DEFAULT_CHARSET)
-
+mark_safe(
-            (self.input_type, self.get_id(), self.__class__.__name__, self.is_required and ' required' or '',
-
+)
-
-    def html2python(data):
-        return data
@@ -430 +431 @@
-            data = ''
-        if isinstance(data, unicode):
-            data = data.encode(settings.DEFAULT_CHARSET)
-
+mark_safe(
-            (self.get_id(), self.__class__.__name__, self.is_required and ' required' or '',
-
+)
-
-class HiddenField(FormField):
-    def __init__(self, field_name, is_required=False, validator_list=None):
@@ -441 +442 @@
-        self.validator_list = validator_list[:]
-
-    def render(self, data):
-
-
+mark_safe(
+)
-
-class CheckboxField(FormField):
-    def __init__(self, field_name, checked_by_default=False, validator_list=None, is_required=False):
@@ -456 +457 @@
-        checked_html = ''
-        if data or (data is '' and self.checked_by_default):
-            checked_html = ' checked="checked"'
-
+mark_safe(
-            (self.get_id(), self.__class__.__name__,
-
+)
-
-    def html2python(data):
-        "Convert value from browser ('on' or '') to a Python boolean"
@@ -489 +490 @@
-                selected_html = ' selected="selected"'
-            output.append('    <option value="%s"%s>%s</option>' % (escape(value), selected_html, escape(display_name)))
-        output.append('  </select>')
-'\n'.join(output
+mark_safe('\n'.join(output)
-
-    def isValidChoice(self, data, form):
-        str_data = str(data)
@@ -542 +543 @@
-                output = ['<ul%s>' % (self.ul_class and ' class="%s"' % self.ul_class or '')]
-                output.extend(['<li>%s %s</li>' % (d['field'], d['label']) for d in self.datalist])
-                output.append('</ul>')
-''.join(output
+mark_safe(''.join(output)
-            def __iter__(self):
-                for d in self.datalist:
-                    yield d
@@ -557 +558 @@
-            datalist.append({
-                'value': value,
-                'name': display_name,
-
-
-
+mark_safe(
+)
+mark_safe(
-                    (self.get_id() + '_' + str(i), display_name),
-
+)
-        return RadioFieldRenderer(datalist, self.ul_class)
-
-    def isValidChoice(self, data, form):
@@ -600 +601 @@
-                selected_html = ' selected="selected"'
-            output.append('    <option value="%s"%s>%s</option>' % (escape(value), selected_html, escape(choice)))
-        output.append('  </select>')
-'\n'.join(output
+mark_safe('\n'.join(output)
-
-    def isValidChoice(self, field_data, all_data):
-        # data is something like ['1', '2', '3']
@@ -653 +654 @@
-                (self.get_id() + escape(value), self.__class__.__name__, field_name, checked_html,
-                self.get_id() + escape(value), choice))
-        output.append('</ul>')
-'\n'.join(output
+mark_safe('\n'.join(output)
-
-####################
-# FILE UPLOADS     #
@@ -674 +675 @@
-            raise validators.CriticalValidationError, gettext("The submitted file is empty.")
-
-    def render(self, data):
-
-
+mark_safe(
+)
-
-    def html2python(data):
-        if data is None:

a/django/template/__init__.py

@@ -60 +60 @@
-from django.template.context import Context, RequestContext, ContextPopException
-from django.utils.functional import curry
-from django.utils.text import smart_split
+from django.utils.safestring import SafeData, EscapeData, mark_safe, mark_for_escaping
+from django.utils.html import escape
-
-__all__ = ('Template', 'Context', 'RequestContext', 'compile_string')
-
@@ -576 +578 @@
-                    arg_vals.append(arg)
-                else:
-                    arg_vals.append(resolve_variable(arg, context))
-
+
+
+
+
+
+
+
+
+
+
+
-        return obj
-
-    def args_check(name, func, provided):
@@ -765 +777 @@
-
-    def render(self, context):
-        output = self.filter_expression.resolve(context)
-
+
+
+
+
+
-
-class DebugVariableNode(VariableNode):
-    def render(self, context):
@@ -775 +791 @@
-            if not hasattr(e, 'source'):
-                e.source = self.source
-            raise
-
+
+
+
+
+
-
-def generic_tag_compiler(params, defaults, name, node_class, parser, token):
-    "Returns a template.Node subclass."

a/django/template/context.py

@@ -9 +9 @@
-
-class Context(object):
-    "A stack container for variable context"
+
+    autoescape = False
+
-    def __init__(self, dict_=None):
-        dict_ = dict_ or {}
-        self.dicts = [dict_]
@@ -98 +101 @@
-            processors = tuple(processors)
-        for processor in get_standard_processors() + processors:
-            self.update(processor(request))
+

a/django/template/defaultfilters.py

@@ -3 +3 @@
-from django.template import resolve_variable, Library
-from django.conf import settings
-from django.utils.translation import gettext
+from django.utils.safestring import mark_safe, SafeData
-import re
-import random as random_module
-
@@ -49 +50 @@
-    "Adds slashes - useful for passing strings to JavaScript, for example."
-    return value.replace('\\', '\\\\').replace('"', '\\"').replace("'", "\\'")
-addslashes = stringfilter(addslashes)
+addslashes.is_safe = True
-
-def capfirst(value):
-    "Capitalizes the first character of the value"
-    return value and value[0].upper() + value[1:]
-capfirst = stringfilter(capfirst)
-
+
+
-def fix_ampersands(value):
-    "Replaces ampersands with ``&`` entities"
-    from django.utils.html import fix_ampersands
-    return fix_ampersands(value)
-fix_ampersands = stringfilter(fix_ampersands)
+fix_ampersands.is_safe = True
-
-def floatformat(text, arg=-1):
-    """
@@ -93 +97 @@
-        return '%d' % int(f)
-    else:
-        formatstr = '%%.%df' % abs(d)
-
+
+
-
-
+, autoescape = None
-    "Displays text with line numbers"
-    from django.utils.html import escape
-    lines = value.split('\n')
-    # Find the maximum width of the line count, for use with zero padding string format command
-    width = str(len(str(len(lines))))
-
-
-
+
+
+
+
+
+
+
-linenumbers = stringfilter(linenumbers)
+linenumbers.is_safe = True
+linenumbers.needs_autoescape = True
-
-def lower(value):
-    "Converts a string into all lowercase"
-    return value.lower()
-lower = stringfilter(lower)
+lower.is_safe = True
-
-def make_list(value):
-    """
@@ -118 +130 @@
-    """
-    return list(value)
-make_list = stringfilter(make_list)
+make_list.is_safe = False
-
-def slugify(value):
-    "Converts to lowercase, removes non-alpha chars and converts spaces to hyphens"
-    value = re.sub('[^\w\s-]', '', value).strip().lower()
-re.sub('[-\s]+', '-', value
+mark_safe(re.sub('[-\s]+', '-', value)
-slugify = stringfilter(slugify)
+slugify.is_safe = True
-
-def stringformat(value, arg):
-    """
@@ -138 +152 @@
-        return ("%" + str(arg)) % value
-    except (ValueError, TypeError):
-        return ""
+stringformat.is_safe = True
-
-def title(value):
-    "Converts a string into titlecase"
-    return re.sub("([a-z])'([A-Z])", lambda m: m.group(0).lower(), value.title())
-title = stringfilter(title)
+title.is_safe = False
-
-def truncatewords(value, arg):
-    """
@@ -159 +175 @@
-        value = str(value)
-    return truncate_words(value, length)
-truncatewords = stringfilter(truncatewords)
+truncatewords.is_safe = True
-
-def truncatewords_html(value, arg):
-    """
@@ -180 +197 @@
-    "Converts a string into all uppercase"
-    return value.upper()
-upper = stringfilter(upper)
+upper.is_safe = False
-
-def urlencode(value):
-    "Escapes a value for use in a URL"
@@ -188 +206 @@
-        value = str(value)
-    return urllib.quote(value)
-urlencode = stringfilter(urlencode)
+urlencode.is_safe = False
-
-def urlize(value):
-    "Converts URLs in plain text into clickable links"
-    from django.utils.html import urlize
-urlize(value, nofollow=True
+mark_safe(urlize(value, nofollow=True)
-urlize = stringfilter(urlize)
+urlize.is_safe = True
-
-def urlizetrunc(value, limit):
-    """
@@ -203 +223 @@
-    Argument: Length to truncate URLs to.
-    """
-    from django.utils.html import urlize
-urlize(value, trim_url_limit=int(limit), nofollow=True
+mark_safe(urlize(value, trim_url_limit=int(limit), nofollow=True)
-urlizetrunc = stringfilter(urlizetrunc)
+urlize.is_safe = True
-
-def wordcount(value):
-    "Returns the number of words"
-    return len(value.split())
-wordcount = stringfilter(wordcount)
+wordcount.is_safe = False
-
-def wordwrap(value, arg):
-    """
@@ -220 +242 @@
-    from django.utils.text import wrap
-    return wrap(value, int(arg))
-wordwrap = stringfilter(wordwrap)
+wordwrap.is_safe = True
-
-def ljust(value, arg):
-    """
@@ -229 +252 @@
-    """
-    return value.ljust(int(arg))
-ljust = stringfilter(ljust)
+ljust.is_safe = True
-
-def rjust(value, arg):
-    """
@@ -238 +262 @@
-    """
-    return value.rjust(int(arg))
-rjust = stringfilter(rjust)
+rjust.is_safe = True
-
-def center(value, arg):
-    "Centers the value in a field of a given width"
-    return value.center(int(arg))
-center = stringfilter(center)
+center.is_safe = True
-
-def cut(value, arg):
-    "Removes all values of arg from the given string"
-    return value.replace(arg, '')
-cut = stringfilter(cut)
+cut.is_safe = False
-
-###################
-# HTML STRINGS    #
-###################
-
-def escape(value):
-
+
+
+
+
+
+
+
+
+
+
-    from django.utils.html import escape
-escape(value
+mark_safe(escape(value)
-escape = stringfilter(escape)
+force_escape.is_safe = True
-
-
+, autoescape = None
-    "Converts newlines into <p> and <br />s"
-    from django.utils.html import linebreaks
-
+
+
-linebreaks = stringfilter(linebreaks)
+linebreaks.is_safe = True
+linebreaks.needs_autoescape = True
-
-
+, autoescape = None
-    "Converts newlines into <br />s"
-
+
+
+
+
+
+
-linebreaksbr = stringfilter(linebreaksbr)
+linebreaksbr.is_safe = True
+linebreaksbr.needs_autoescape = True
+
+def safe(value):
+    "Marks the value as a string that should not be auto-escaped."
+    from django.utils.safestring import mark_safe
+    return mark_safe(value)
+safe = stringfilter(safe)
+safe.is_safe = True
-
-def removetags(value, tags):
-    "Removes a space separated list of [X]HTML tags from the output"
@@ -280 +334 @@
-    value = endtag_re.sub('', value)
-    return value
-removetags = stringfilter(removetags)
+removetags.is_safe = True
-
-def striptags(value):
-    "Strips all [X]HTML tags"
-    from django.utils.html import strip_tags
-    return strip_tags(value)
-striptags = stringfilter(striptags)
+striptags.is_safe = True
-
-###################
-# LISTS           #
@@ -299 +355 @@
-    decorated = [(resolve_variable('var.' + arg, {'var' : item}), item) for item in value]
-    decorated.sort()
-    return [item[1] for item in decorated]
+dictsort.is_safe = False
-
-def dictsortreversed(value, arg):
-    """
@@ -309 +366 @@
-    decorated.sort()
-    decorated.reverse()
-    return [item[1] for item in decorated]
+dictsortreversed.is_safe = False
-
-def first(value):
-    "Returns the first item in a list"
@@ -316 +374 @@
-        return value[0]
-    except IndexError:
-        return ''
+first.is_safe = True
-
-def join(value, arg):
-    "Joins a list with a string, like Python's ``str.join(list)``"
-    try:
-return
+data =
-    except AttributeError: # fail silently but nicely
-        return value
+    safe_args = reduce(lambda lhs, rhs: lhs and isinstance(rhs, SafeData), value, True)
+    if safe_args:
+        return mark_safe(data)
+    else:
+        return data
+join.is_safe = True
-
-def length(value):
-    "Returns the length of the value - useful for lists"
-    return len(value)
+length.is_safe = False
-
-def length_is(value, arg):
-    "Returns a boolean of whether the value's length is the argument"
-    return len(value) == int(arg)
+length.is_safe = False
-
-def random(value):
-    "Returns a random item from the list"
-    return random_module.choice(value)
+length.is_safe = True
-
-def slice_(value, arg):
-    """
@@ -355 +423 @@
-
-    except (ValueError, TypeError):
-        return value # Fail silently.
+slice_.is_safe = True
-
-
+, autoescape = None
-    """
-    Recursively takes a self-nested list and returns an HTML unordered list --
-    WITHOUT opening and closing <ul> tags.
@@ -377 +446 @@
-        </ul>
-        </li>
-    """
+    if autoescape:
+        from django.utils.html import conditional_escape
+        escaper = conditional_escape
+    else:
+        escaper = lambda x: x
+
-    def _helper(value, tabs):
-        indent = '\t' * tabs
-        if value[1]:
-value[0]
+escaper(value[0])
-                '\n'.join([_helper(v, tabs+1) for v in value[1]]), indent, indent)
-        else:
-
-
+
+
+
+
-
-###################
-# INTEGERS        #
@@ -393 +470 @@
-def add(value, arg):
-    "Adds the arg to the value"
-    return int(value) + int(arg)
+add.is_safe = False
-
-def get_digit(value, arg):
-    """
@@ -412 +490 @@
-        return int(str(value)[-arg])
-    except IndexError:
-        return 0
+get_digit.is_safe = False
-
-###################
-# DATES           #
@@ -425 +504 @@
-    if arg is None:
-        arg = settings.DATE_FORMAT
-    return format(value, arg)
+date.is_safe = False
-
-def time(value, arg=None):
-    "Formats a time according to the given format"
@@ -434 +514 @@
-    if arg is None:
-        arg = settings.TIME_FORMAT
-    return time_format(value, arg)
+time.is_safe = False
-
-def timesince(value, arg=None):
-    'Formats a date as the time since that date (i.e. "4 days, 6 hours")'
@@ -443 +524 @@
-    if arg:
-        return timesince(arg, value)
-    return timesince(value)
+timesince.is_safe = False
-
-def timeuntil(value, arg=None):
-    'Formats a date as the time until that date (i.e. "4 days, 6 hours")'
@@ -453 +535 @@
-    if arg:
-        return timesince(arg, value)
-    return timesince(datetime.now(), value)
+timeuntil.is_safe = False
-
-###################
-# LOGIC           #
@@ -461 +544 @@
-def default(value, arg):
-    "If value is unavailable, use given default"
-    return value or arg
+default.is_safe = False
-
-def default_if_none(value, arg):
-    "If value is None, use given default"
-    if value is None:
-        return arg
-    return value
+default_if_none.is_safe = False
-
-def divisibleby(value, arg):
-    "Returns true if the value is devisible by the argument"
-    return int(value) % int(arg) == 0
+divisibleby.is_safe = False
-
-def yesno(value, arg=None):
-    """
@@ -501 +587 @@
-    if value:
-        return yes
-    return no
+yesno.is_safe = False
-
-###################
-# MISC            #
@@ -523 +610 @@
-    if bytes < 1024 * 1024 * 1024:
-        return "%.1f MB" % (bytes / (1024 * 1024))
-    return "%.1f GB" % (bytes / (1024 * 1024 * 1024))
+filesizeformat.is_safe = True
-
-def pluralize(value, arg='s'):
-    """
@@ -550 +638 @@
-        except TypeError: # len() of unsized object
-            pass
-    return singular_suffix
+pluralize.is_safe = False
-
-def phone2numeric(value):
-    "Takes a phone number and converts it in to its numerical equivalent"
-    from django.utils.text import phone2numeric
-    return phone2numeric(value)
+phone2numeric.is_safe = True
-
-def pprint(value):
-    "A wrapper around pprint.pprint -- for debugging, really"
@@ -563 +653 @@
-        return pformat(value)
-    except Exception, e:
-        return "Error in formatting:%s" % e
+pprint.is_safe = True
-
-# Syntax: register.filter(name of filter, callback)
-register.filter(add)
@@ -581 +672 @@
-register.filter(first)
-register.filter(fix_ampersands)
-register.filter(floatformat)
+register.filter(force_escape)
-register.filter(get_digit)
-register.filter(join)
-register.filter(length)
@@ -597 +689 @@
-register.filter(removetags)
-register.filter(random)
-register.filter(rjust)
+register.filter(safe)
-register.filter('slice', slice_)
-register.filter(slugify)
-register.filter(stringformat)

a/django/template/defaulttags.py

@@ -4 +4 @@
-from django.template import TemplateSyntaxError, VariableDoesNotExist, BLOCK_TAG_START, BLOCK_TAG_END, VARIABLE_TAG_START, VARIABLE_TAG_END, SINGLE_BRACE_START, SINGLE_BRACE_END, COMMENT_TAG_START, COMMENT_TAG_END
-from django.template import get_library, Library, InvalidTemplateLibrary
-from django.conf import settings
+from django.utils.safestring import mark_safe
-import sys
-
-register = Library()
-
+class AutoEscapeControlNode(Node):
+    """Implements the actions of both the autoescape and noautescape tags."""
+    def __init__(self, setting, nodelist):
+        self.setting, self.nodelist = setting, nodelist
+
+    def render(self, context):
+        old_setting = context.autoescape
+        context.autoescape = self.setting
+        output = self.nodelist.render(context)
+        context.autoescape = old_setting
+        if self.setting:
+            return mark_safe(output)
+        else:
+            return output
+
-class CommentNode(Node):
-    def render(self, context):
-        return ''
@@ -41 +57 @@
-    def render(self, context):
-        output = self.nodelist.render(context)
-        # apply filters
-
+
+
+
-
-class FirstOfNode(Node):
-    def __init__(self, vars):
@@ -234 +252 @@
-            return ''
-        output = [] # list of dictionaries in the format {'grouper': 'key', 'list': [list of contents]}
-        for obj in obj_list:
-
+
+
+
-            # TODO: Is this a sensible way to determine equality?
-            if output and repr(output[-1]['grouper']) == repr(grouper):
-                output[-1]['list'].append(obj)
@@ -355 +375 @@
-        return str(int(round(ratio)))
-
-#@register.tag
+def autoescape(parser, token):
+    """
+    Force autoescape behaviour for this block.
+    """
+    nodelist = parser.parse(('endautoescape',))
+    parser.delete_first_token()
+    return AutoEscapeControlNode(True, nodelist)
+autoescape = register.tag(autoescape)
+
+#@register.tag
-def comment(parser, token):
-    """
-    Ignore everything between ``{% comment %}`` and ``{% endcomment %}``
@@ -457 +487 @@
-
-    Sample usage::
-
-
+force_
-            This text will be HTML-escaped, and will appear in lowercase.
-        {% endfilter %}
-    """
-    _, rest = token.contents.split(None, 1)
-    filter_expr = parser.compile_filter("var|%s" % (rest))
+    for func, unused in filter_expr.filters:
+        if getattr(func, '_decorated_function', func).__name__ in ('escape', 'safe'):
+            raise TemplateSyntaxError('"filter %s" is not permitted.  Use the "autoescape" tag instead.' % func.__name__)
-    nodelist = parser.parse(('endfilter',))
-    parser.delete_first_token()
-    return FilterNode(filter_expr, nodelist)
@@ -704 +737 @@
-ifchanged = register.tag(ifchanged)
-
-#@register.tag
+def noautoescape(parser, token):
+    """
+    Force autoescape behaviour to be disabled for this block.
+    """
+    nodelist = parser.parse(('endnoautoescape',))
+    parser.delete_first_token()
+    return AutoEscapeControlNode(False, nodelist)
+autoescape = register.tag(noautoescape)
+
+#@register.tag
-def ssi(parser, token):
-    """
-    Output the contents of a given file into the page.

a/django/utils/html.py

@@ -1 +1 @@
-"HTML utilities suitable for global use."
-
-import re, string
+from django.utils.safestring import SafeData
-
-# Configuration for urlize() function
-LEADING_PUNCTUATION  = ['(', '<', '&lt;']
@@ -27 +28 @@
-        html = str(html)
-    return html.replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;')
-
-
+
+
+
+
+
+
+
+
-    "Converts newlines into <p> and <br />s"
-    value = re.sub(r'\r\n|\r|\n', '\n', value) # normalize newlines
-    paras = re.split('\n{2,}', value)
-
+
+
+
+
-    return '\n\n'.join(paras)
-
-def strip_tags(value):

/dev/null

@@ +1 @@
+"""
+Functions for working with "safe strings": strings that can be displayed safely
+without further escaping in HTML. Here, a "safe string" means that the producer
+of the string has already turned characters that should not be interpreted by
+the HTML engine (e.g. '<') into the appropriate entities.
+"""
+from django.utils.functional import curry
+
+class EscapeData(object):
+    pass
+
+class EscapeString(str, EscapeData):
+    """
+    A string that should be HTML-escaped when output.
+    """
+    pass
+
+class EscapeUnicode(unicode, EscapeData):
+    """
+    A unicode object that should be HTML-escaped when output.
+    """
+    pass
+
+class SafeData(object):
+    pass
+
+class SafeString(str, SafeData):
+    """
+    A string subclass that has been specifically marked as "safe" for HTML
+    output purposes.
+    """
+    def __add__(self, rhs):
+        """
+        Concatenating a safe string with another safe string or safe unicode
+        object is safe. Otherwise, the result is no longer safe.
+        """
+        if isinstance(rhs, SafeUnicode):
+            return SafeUnicode(self + rhs)
+        elif isinstance(rhs, SafeString):
+            return SafeString(self + rhs)
+        else:
+            return super(SafeString, self).__add__(rhs)
+
+    def __str__(self):
+        return self
+
+class SafeUnicode(unicode, SafeData):
+    """
+    A unicode subclass that has been specifically marked as "safe" for HTML
+    output purposes.
+    """
+    def __add__(self, rhs):
+        """
+        Concatenating a safe unicode object with another safe string or safe
+        unicode object is safe. Otherwise, the result is no longer safe.
+        """
+        if isinstance(rhs, SafeData):
+            return SafeUnicode(self + rhs)
+        else:
+            return super(SafeUnicode, self).__add__(rhs)
+
+    def _proxy_method(self, *args, **kwargs):
+        """
+        Wrap a call to a normal unicode method up so that we return safe
+        results. The method that is being wrapped is passed in the 'method'
+        argument.
+        """
+        method = kwargs.pop('method')
+        data = method(self, *args, **kwargs)
+        if isinstance(data, str):
+            return SafeString(data)
+        else:
+            return SafeUnicode(data)
+
+    encode = curry(_proxy_method, method = unicode.encode)
+    decode = curry(_proxy_method, method = unicode.decode)
+
+
+def mark_safe(s):
+    """
+    Explicitly mark a string as safe for (HTML) output purposes. The returned
+    object can be used everywhere a string or unicode object is appropriate.
+
+    Can safely be called multiple times on a single string.
+    """
+    if isinstance(s, SafeData):
+        return s
+    if isinstance(s, str):
+        return SafeString(s)
+    if isinstance(s, unicode):
+        return SafeUnicode(s)
+    return SafeString(str(s))
+
+def mark_for_escaping(s):
+    """
+    Explicitly mark a string as requiring HTML escaping upon output. Has no
+    effect on SafeData subclasses.
+
+    Can be safely called multiple times on a single string (the effect is only
+    applied once).
+    """
+    if isinstance(s, SafeData) or isinstance(s, EscapeData):
+        return s
+    if isinstance(s, str):
+        return EscapeString(s)
+    if isinstance(s, unicode):
+        return EscapeUnicode(s)
+    return EscapeString(str(s))
+

a/docs/templates.txt

@@ -270 +270 @@
-two similarly-named ``{% block %}`` tags in a template, that template's parent
-wouldn't know which one of the blocks' content to use.
-
+Automatic HTML escaping
+=======================
+
+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 like
+
+::
+
+    Hello, {{ name }}.
+
+seems like a harmless way to display the user's name. However, if you are
+displaying data that the user entered directly and they entered their name as
+
+::
+
+    <script>alert('hello')</script>
+
+this would always display a Javascript alert box whenever 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 an
+auto-escaping template tag. 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.
+
+Because 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, auto-escaping is not in effect. To enable it inside your template,
+wrap the affected content in the ``autoescape`` tag, like so::
+
+    {% autoescape %}
+        Hello {{ name }}
+    {% endautoescape %}
+
+Since the auto-escaping tag passes its effect onto templates that extend the
+current one as well as templates included via the ``include`` tag (just like
+all block tags), if you wrap your main HTML content in an ``autoescape`` tag,
+you will have automatic escaping applied to all of your content.
+
+At times, you might want to disable auto-escaping when it would otherwise be
+in effect. You can do this with the ``noautoescape`` tag. For example::
+
+    {% autoescape %}
+        Hello {{ name }}
+
+        {% noautoescape %}
+            This will not be auto-escaped: {{ data }}.
+
+            Nor this: {{ other_data }}
+    &