Commit f33e1503 authored by Luke Plant's avatar Luke Plant
Browse files

Documented utils.html.escape and conditional_escape

parent cf731a54

django/utils/html.py

+7 −7
Original line number Diff line number Diff line
@@ -31,11 +31,11 @@ hard_coded_bullets_re = re.compile(r'((?:<p>(?:%s).*?[a-zA-Z].*?</p>\s*)+)' % '| 
trailing_empty_content_re = re.compile(r'(?:<p>(?:&nbsp;|\s|<br \/>)*?</p>\s*)+\Z')

del x # Temporary variable



def escape(html):

def escape(text):

    """

    Returns the given HTML with ampersands, quotes and angle brackets encoded.

    Returns the given text with ampersands, quotes and angle brackets encoded for use in HTML.

    """

    return mark_safe(force_unicode(html).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))

    return mark_safe(force_unicode(text).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))

escape = allow_lazy(escape, unicode)



_base_js_escapes = (
@@ -63,14 +63,14 @@ def escapejs(value): 
    return value

escapejs = allow_lazy(escapejs, unicode)



def conditional_escape(html):

def conditional_escape(text):

    """

    Similar to escape(), except that it doesn't operate on pre-escaped strings.

    """

    if isinstance(html, SafeData):

        return html

    if isinstance(text, SafeData):

        return text

    else:

        return escape(html)

        return escape(text)



def linebreaks(value, autoescape=False):

    """Converts newlines into <p> and <br />s."""

docs/ref/utils.txt

+22 −0
Original line number Diff line number Diff line
@@ -387,6 +387,28 @@ Atom1Feed 
    input is a proper string, then add support for lazy translation objects at the

    end.



``django.utils.html``

=====================



.. module:: django.utils.html

   :synopsis: HTML helper functions



Usually you should build up HTML using Django's templates to make use of its

autoescape mechanism, using the utilities in :mod:`django.utils.safestring`

where appropriate. This module provides some additional low level utilitiesfor

escaping HTML.



.. function:: escape(text)



    Returns the given text with ampersands, quotes and angle brackets encoded

    for use in HTML. The input is first passed through

    :func:`~django.utils.encoding.force_unicode` and the output has

    :func:`~django.utils.safestring.mark_safe` applied.



.. function:: conditional_escape(text)



    Similar to ``escape()``, except that it doesn't operate on pre-escaped strings,

    so it will not double escape.



``django.utils.http``

=====================