4 files changed, 27 insertions, 8 deletions

diff --git a/Doc/howto/webservers.rst b/Doc/howto/webservers.rst
index 7f68b3b..049fe1b 100644
--- a/Doc/howto/webservers.rst
+++ b/Doc/howto/webservers.rst
@@ -293,7 +293,7 @@ following WSGI-application::
     # -*- coding: UTF-8 -*-
 
     import sys, os
-    from cgi import escape
+    from html import escape
     from flup.server.fcgi import WSGIServer
 
     def app(environ, start_response):
diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index 49d1488..8c75517 100644
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -328,9 +328,9 @@ algorithms implemented in this module in other circumstances.
    attribute value delimited by double quotes, as in ``<a href="...">``.  Note
    that single quotes are never translated.
 
-   If the value to be quoted might include single- or double-quote characters,
-   or both, consider using the :func:`~xml.sax.saxutils.quoteattr` function in the
-   :mod:`xml.sax.saxutils` module instead.
+   .. deprecated:: 3.2
+      This function is unsafe because *quote* is false by default, and therefore
+      deprecated.  Use :func:`html.escape` instead.
 
 
 .. _cgi-security:
@@ -508,8 +508,8 @@ Common problems and solutions
 
 .. rubric:: Footnotes
 
-.. [#] Note that some recent versions of the HTML specification do state what order the
-   field values should be supplied in, but knowing whether a request was
-   received from a conforming browser, or even from a browser at all, is tedious
-   and error-prone.
+.. [#] Note that some recent versions of the HTML specification do state what
+   order the field values should be supplied in, but knowing whether a request
+   was received from a conforming browser, or even from a browser at all, is
+   tedious and error-prone.
 
diff --git a/Doc/library/html.rst b/Doc/library/html.rst
new file mode 100644
index 0000000..2c42cf8
--- /dev/null
+++ b/Doc/library/html.rst
@@ -0,0 +1,18 @@
+:mod:`html` --- HyperText Markup Language support
+=================================================
+
+.. module:: html
+   :synopsis: Helpers for manipulating HTML.
+
+.. versionadded:: 3.2
+
+
+This module defines utilities to manipulate HTML.
+
+.. function:: escape(s, quote=True)
+
+   Convert the characters ``&``, ``<`` and ``>`` in string *s* to HTML-safe
+   sequences.  Use this if you need to display text that might contain such
+   characters in HTML.  If the optional flag *quote* is true, the characters
+   (``"``) and (``'``) are also translated; this helps for inclusion in an HTML
+   attribute value delimited by quotes, as in ``<a href="...">``.
diff --git a/Doc/library/markup.rst b/Doc/library/markup.rst
index ae97b69..49794ef 100644
--- a/Doc/library/markup.rst
+++ b/Doc/library/markup.rst
@@ -20,6 +20,7 @@ definition of the Python bindings for the DOM and SAX interfaces.
 
 .. toctree::
 
+   html.rst
    html.parser.rst
    html.entities.rst
    pyexpat.rst