Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Documented utils.html.escape and conditional_escape

  • Loading branch information...
commit f33e15036907d6e4bda6116dc84097e9e590d2c8 1 parent cf731a5
Luke Plant authored June 30, 2012
14  django/utils/html.py
@@ -31,11 +31,11 @@
31 31
 trailing_empty_content_re = re.compile(r'(?:<p>(?:&nbsp;|\s|<br \/>)*?</p>\s*)+\Z')
32 32
 del x # Temporary variable
33 33
 
34  
-def escape(html):
  34
+def escape(text):
35 35
     """
36  
-    Returns the given HTML with ampersands, quotes and angle brackets encoded.
  36
+    Returns the given text with ampersands, quotes and angle brackets encoded for use in HTML.
37 37
     """
38  
-    return mark_safe(force_unicode(html).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
  38
+    return mark_safe(force_unicode(text).replace('&', '&amp;').replace('<', '&lt;').replace('>', '&gt;').replace('"', '&quot;').replace("'", '&#39;'))
39 39
 escape = allow_lazy(escape, unicode)
40 40
 
41 41
 _base_js_escapes = (
@@ -63,14 +63,14 @@ def escapejs(value):
63 63
     return value
64 64
 escapejs = allow_lazy(escapejs, unicode)
65 65
 
66  
-def conditional_escape(html):
  66
+def conditional_escape(text):
67 67
     """
68 68
     Similar to escape(), except that it doesn't operate on pre-escaped strings.
69 69
     """
70  
-    if isinstance(html, SafeData):
71  
-        return html
  70
+    if isinstance(text, SafeData):
  71
+        return text
72 72
     else:
73  
-        return escape(html)
  73
+        return escape(text)
74 74
 
75 75
 def linebreaks(value, autoescape=False):
76 76
     """Converts newlines into <p> and <br />s."""
22  docs/ref/utils.txt
@@ -387,6 +387,28 @@ Atom1Feed
387 387
     input is a proper string, then add support for lazy translation objects at the
388 388
     end.
389 389
 
  390
+``django.utils.html``
  391
+=====================
  392
+
  393
+.. module:: django.utils.html
  394
+   :synopsis: HTML helper functions
  395
+
  396
+Usually you should build up HTML using Django's templates to make use of its
  397
+autoescape mechanism, using the utilities in :mod:`django.utils.safestring`
  398
+where appropriate. This module provides some additional low level utilitiesfor
  399
+escaping HTML.
  400
+
  401
+.. function:: escape(text)
  402
+
  403
+    Returns the given text with ampersands, quotes and angle brackets encoded
  404
+    for use in HTML. The input is first passed through
  405
+    :func:`~django.utils.encoding.force_unicode` and the output has
  406
+    :func:`~django.utils.safestring.mark_safe` applied.
  407
+
  408
+.. function:: conditional_escape(text)
  409
+
  410
+    Similar to ``escape()``, except that it doesn't operate on pre-escaped strings,
  411
+    so it will not double escape.
390 412
 
391 413
 ``django.utils.http``
392 414
 =====================

0 notes on commit f33e150

Please sign in to comment.
Something went wrong with that request. Please try again.