PEP 594: provide examples of how to replace the relevant parts of `cg…

…i` (#2304)

pep-0594.rst

@@ -341,13 +341,28 @@ inefficient because every incoming request is handled in a new process.
 
    "[...] designed poorly and are now near-impossible to fix (``cgi``) [...]"
 
-Several people proposed to either keep the ``cgi`` module for features like
-``cgi.parse_qs`` or move ``cgi.escape`` to a different module. The
-functions ``cgi.parse_qs`` and ``cgi.parse_qsl`` have been
-deprecated for a while and are actually aliases for
-``urllib.parse.parse_qs`` and ``urllib.parse.parse_qsl``. The
-function ``cgi.quote`` has been deprecated in favor of ``html.quote``
-with secure default values.
+Replacements for the various parts of ``cgi`` which are not directly
+related to executing code are:
+
+- ``parse`` with ``urllib.parse.parse_qs`` (``parse`` is just a wrapper)
+- ``parse_header`` with ``email.message.Message`` (see example below)
+- ``parse_multipart`` with ``email.message.Message`` (same MIME RFCs)
+- ``FieldStorage``/``MiniFieldStorage`` has no direct replacement
+- ``valid_boundary`` (undocumented) with ``re.compile("^[ -~]{0,200}[!-~]$")``
+
+As an explicit example of how close ``parse_header`` and
+``email.message.Message`` are::
+
+  >>> from cgi import parse_header
+  >>> from email.message import Message
+  >>> parse_header(h)
+  ('application/json', {'charset': 'utf8'})
+  >>> m = Message()
+  >>> m['content-type'] = h
+  >>> m.get_params()
+  [('application/json', ''), ('charset', 'utf8')]
+  >>> m.get_param('charset')
+  'utf8'
 
 
 cgitb
@@ -640,6 +655,8 @@ Update 4
 --------
 * Add Brett as a co-author.
 * Retarget the PEP for Python 3.11.
+* Examples of how to replace the relevant parts of ``cgi``
+  (thanks Martijn Pieters).
 
 
 References