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

And fix the parameter name.

(cherry picked from commit 8fc7bc2b7631ee819ee614e47b6f44bacebe1574)

diff --git a/Doc/library/re.rst b/Doc/library/re.rst
index ddf509bb7d966b16a42c2a97b2fa9269db65cbd7..f01887af64cd795ec5296ff8c75236065a01b8f6 100644 (file)
--- a/Doc/library/re.rst
+++ b/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()

diff --git a/Doc/tools/susp-ignored.csv b/Doc/tools/susp-ignored.csv
index 17b23665b04af660647b803e3af75e23e264e2dc..0b2d742cbe784c8fb76bcacdc2bd480a32b683f6 100644 (file)
--- a/Doc/tools/susp-ignored.csv
+++ b/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,