Patch #613256: Add nescape method to xml.sax.saxutils.

Doc/lib/xmlsaxutils.tex

@@ -22,6 +22,17 @@ either in direct use, or as base classes.
   strings; each key will be replaced with its corresponding value.
 \end{funcdesc}
 
+\begin{funcdesc}{unescape}{data\optional{, entities}}
+  Unescape \character{\&}, \character{\<}, and \character{\>}
+  in a string of data.
+
+  You can unescape other strings of data by passing a dictionary as the
+  optional \var{entities} parameter.  The keys and values must all be
+  strings; each key will be replaced with its corresponding value.
+
+  \versionadded{2.3}
+\end{funcdesc}
+
 \begin{funcdesc}{quoteattr}{data\optional{, entities}}
   Similar to \function{escape()}, but also prepares \var{data} to be
   used as an attribute value.  The return value is a quoted version of

Lib/test/output/test_sax

@@ -29,6 +29,9 @@ Passed test_nsattrs_wattr
 Passed test_quoteattr_basic
 Passed test_single_double_quoteattr
 Passed test_single_quoteattr
+Passed test_unescape_all
+Passed test_unescape_basic
+Passed test_unescape_extra
 Passed test_xmlgen_attr_escape
 Passed test_xmlgen_basic
 Passed test_xmlgen_content
@@ -36,4 +39,4 @@ Passed test_xmlgen_content_escape
 Passed test_xmlgen_ignorable
 Passed test_xmlgen_ns
 Passed test_xmlgen_pi
-37 tests, 0 failures
+40 tests, 0 failures

Lib/test/test_sax.py

@@ -8,7 +8,8 @@ try:
 except SAXReaderNotAvailable:
     # don't try to test this module if we cannot create a parser
     raise ImportError("no XML parsers available")
-from xml.sax.saxutils import XMLGenerator, escape, quoteattr, XMLFilterBase
+from xml.sax.saxutils import XMLGenerator, escape, unescape, quoteattr, \
+                             XMLFilterBase
 from xml.sax.expatreader import create_parser
 from xml.sax.xmlreader import InputSource, AttributesImpl, AttributesNSImpl
 from cStringIO import StringIO
@@ -70,6 +71,17 @@ def test_escape_all():
 def test_escape_extra():
     return escape("Hei p deg", {"" : "å"}) == "Hei på deg"
 
+# ===== unescape
+
+def test_unescape_basic():
+    return unescape("Donald Duck & Co") == "Donald Duck & Co"
+
+def test_unescape_all():
+    return unescape("&lt;Donald Duck &amp; Co&gt;") == "<Donald Duck & Co>"
+
+def test_unescape_extra():
+    return unescape("Hei p deg", {"" : "&aring;"}) == "Hei p&aring; deg"
+
 # ===== quoteattr
 
 def test_quoteattr_basic():

Lib/xml/sax/saxutils.py

@@ -12,6 +12,11 @@ try:
 except AttributeError:
     _StringTypes = [types.StringType]
 
+def __dict_replace(s, d):
+    """Replace substrings of a string using a dictionary."""
+    for key, value in d.items():
+        s = s.replace(key, value)
+    return s
 
 def escape(data, entities={}):
     """Escape &, <, and > in a string of data.
@@ -20,12 +25,27 @@ def escape(data, entities={}):
     the optional entities parameter.  The keys and values must all be
     strings; each key will be replaced with its corresponding value.
     """
+
+    # must do ampersand first
     data = data.replace("&", "&amp;")
-    data = data.replace("<", "&lt;")
-    data = data.replace(">", "&gt;")
-    for chars, entity in entities.items():
-        data = data.replace(chars, entity)
-    return data
+    data = __dict_replace(data, {"<" : "&lt;",
+                                 ">" : "&gt;",
+                                 })
+    return __dict_replace(data, entities)
+
+def unescape(data, entities={}):
+    """Unescape &amp;, &lt;, and &gt; in a string of data.
+
+    You can unescape other strings of data by passing a dictionary as
+    the optional entities parameter.  The keys and values must all be
+    strings; each key will be replaced with its corresponding value.
+    """
+    data = __dict_replace(data, {"&lt;"  : "<",
+                                 "&gt;"  : ">",
+                                 })
+    # must do ampersand last
+    data = data.replace("&amp;", "&")
+    return __dict_replace(data, entities)
 
 def quoteattr(data, entities={}):
     """Escape and quote an attribute value.

Misc/ACKS

@@ -56,6 +56,7 @@ Pablo Bleyer
 Erik van Blokland
 Finn Bock
 Paul Boddie
+Matthew Boedicker
 David Bolen
 Jurjen Bos
 Peter Bosch

Misc/NEWS

@@ -352,6 +352,9 @@ Extension modules
 Library
 -------
 
+- xml.sax.saxutils.unescape has been added, to replace entity references
+  with their entity value.
+
 - Queue.Queue.{put,get} now support an optional timeout argument.
 
 - Various features of Tk 8.4 are exposed in Tkinter.py. The multiple