[Python-checkins] gh-92611: Add details on replacements for cgi utility funcs (GH-92792) (GH-93967)

[brettcannon]

https://github.com/python/cpython/commit/41964de01b93feebc25035d4e6b5e802d157ae98
commit: 41964de01b93feebc25035d4e6b5e802d157ae98
branch: 3.11
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: brettcannon <brett at python.org>
date: 2022-06-21T14:51:27-07:00
summary:

gh-92611: Add details on replacements for cgi utility funcs (GH-92792) (GH-93967)

Per [suggestions on a Discourse thread](https://discuss.python.org/t/pep-594-take-2-removing-dead-batteries-from-the-standard-library/13508/51), discussed in GH-92611 and as a followup to PR GH-92612 , this PR add additional specific per-function replacement information for the utility functions in the `cgi` module deprecated by PEP 594 (PEP-594).

(cherry picked from commit 71354adff07f8beba8374767532bb9da34546e66)

Co-authored-by: CAM Gerlach <CAM.Gerlach at Gerlach.CAM>

files:
M Doc/library/cgi.rst

diff --git a/Doc/library/cgi.rst b/Doc/library/cgi.rst
index 5976c90029c22..983e412afafd9 100644
--- a/Doc/library/cgi.rst
+++ b/Doc/library/cgi.rst
@@ -19,6 +19,12 @@
    The :mod:`cgi` module is deprecated
    (see :pep:`PEP 594 <594#cgi>` for details and alternatives).
 
+   The :class:`FieldStorage` class can typically be replaced with
+   :func:`urllib.parse.parse_qsl` for ``GET`` and ``HEAD`` requests,
+   and the :mod:`email.message` module or
+   `multipart <https://pypi.org/project/multipart/>`_ for ``POST`` and ``PUT``.
+   Most :ref:`utility functions <functions-in-cgi-module>` have replacements.
+
 --------------
 
 Support module for Common Gateway Interface (CGI) scripts.
@@ -293,6 +299,12 @@ algorithms implemented in this module in other circumstances.
    ``sys.stdin``).  The *keep_blank_values*, *strict_parsing* and *separator* parameters are
    passed to :func:`urllib.parse.parse_qs` unchanged.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced by calling :func:`urllib.parse.parse_qs` directly
+      on the desired query string (except for ``multipart/form-data`` input,
+      which can be handled as described for :func:`parse_multipart`).
+
 
 .. function:: parse_multipart(fp, pdict, encoding="utf-8", errors="replace", separator="&")
 
@@ -316,12 +328,31 @@ algorithms implemented in this module in other circumstances.
    .. versionchanged:: 3.10
       Added the *separator* parameter.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced with the functionality in the :mod:`email` package
+      (e.g. :class:`email.message.EmailMessage`/:class:`email.message.Message`)
+      which implements the same MIME RFCs, or with the
+      `multipart <https://pypi.org/project/multipart/>`__ PyPI project.
+
 
 .. function:: parse_header(string)
 
    Parse a MIME header (such as :mailheader:`Content-Type`) into a main value and a
    dictionary of parameters.
 
+   .. deprecated-removed:: 3.11 3.13
+      This function, like the rest of the :mod:`cgi` module, is deprecated.
+      It can be replaced with the functionality in the :mod:`email` package,
+      which implements the same MIME RFCs.
+
+      For example, with :class:`email.message.EmailMessage`::
+
+          from email.message import EmailMessage
+          msg = EmailMessage()
+          msg['content-type'] = 'application/json; charset="utf8"'
+          main, params = msg.get_content_type(), msg['content-type'].params
+
 
 .. function:: test()