bpo-30021: Add examples for re.escape(). (#1048) (#1118)

And fix the parameter name.

(cherry picked from commit 8fc7bc2b)

Doc/library/re.rst

@@ -695,11 +695,22 @@ form.
       Added the optional flags argument.
 
 
-.. function:: escape(string)
+.. function:: escape(pattern)
 
-   Return *string* with all non-alphanumerics backslashed; this is useful if you
-   want to match an arbitrary literal string that may have regular expression
-   metacharacters in it.
+   Escape all the characters in *pattern* except ASCII letters and numbers.
+   This is useful if you want to match an arbitrary literal string that may
+   have regular expression metacharacters in it.  For example::
+
+      >>> print re.escape('python.exe')
+      python\.exe
+
+      >>> legal_chars = string.ascii_lowercase + string.digits + "!#$%&'*+-.^_`|~:"
+      >>> print '[%s]+' % re.escape(legal_chars)
+      [abcdefghijklmnopqrstuvwxyz0123456789\!\#\$\%\&\'\*\+\-\.\^\_\`\|\~\:]+
+
+      >>> operators = ['+', '-', '*', '/', '**']
+      >>> print '|'.join(map(re.escape, sorted(operators, reverse=True)))
+      \/|\-|\+|\*\*|\*
 
 
 .. function:: purge()

Doc/tools/susp-ignored.csv

@@ -99,6 +99,8 @@ library/profile,,:lineno,ncalls  tottime  percall  cumtime  percall filename:lin
 library/profile,,:lineno,filename:lineno(function)
 library/pyexpat,,:elem1,<py:elem1 />
 library/pyexpat,,:py,"xmlns:py = ""http://www.python.org/ns/"">"
+library/re,,`,!#$%&'*+-.^_`|~:
+library/re,,`,\!\#\$\%\&\'\*\+\-\.\^_\`\|\~\:
 library/smtplib,,:port,method must support that as well as a regular host:port
 library/socket,,::,'5aef:2b::8'
 library/sqlite3,,:memory,