gh-91996: Add an HTTPMethod StrEnum to http (GH-91997)

* Add HTTPMethod enum to http

Create a StrEnum for the 9 common HTTP methods.

Co-authored-by: Ethan Furman <ethan@stoneleaf.us>

4 files changed, 80 insertions, 6 deletions

diff --git a/Doc/library/http.rst b/Doc/library/http.rst
index 1569d504c7..5895a41d84 100644
--- a/Doc/library/http.rst
+++ b/Doc/library/http.rst
@@ -21,8 +21,8 @@ HyperText Transfer Protocol:
 * :mod:`http.cookies` has utilities for implementing state management with cookies
 * :mod:`http.cookiejar` provides persistence of cookies
 
-:mod:`http` is also a module that defines a number of HTTP status codes and
-associated messages through the :class:`http.HTTPStatus` enum:
+
+The :mod:`http` module also defines the following enums that help you work with http related code:
 
 .. class:: HTTPStatus
 
@@ -53,8 +53,8 @@ HTTP status codes
 -----------------
 
 Supported,
-`IANA-registered <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_
-status codes available in :class:`http.HTTPStatus` are:
+`IANA-registered status codes <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_
+available in :class:`http.HTTPStatus` are:
 
 ======= =================================== ==================================================================
 Code    Enum Name                           Details
@@ -136,3 +136,46 @@ equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
 
 .. versionadded:: 3.9
    Added ``103 EARLY_HINTS``, ``418 IM_A_TEAPOT`` and ``425 TOO_EARLY`` status codes.
+
+.. class:: HTTPMethod
+
+   .. versionadded:: 3.11
+
+   A subclass of :class:`enum.StrEnum` that defines a set of HTTP methods and descriptions written in English.
+
+   Usage::
+
+      >>> from http import HTTPMethod
+      >>> HTTMethod.GET
+      HTTMethod.GET
+      >>> HTTMethod.GET == 'GET'
+      True
+      >>> HTTMethod.GET.value
+      'GET'
+      >>> HTTMethod.GET.description
+      'Transfer a current representation of the target resource.'
+      >>> list(HTTPMethod)
+      [HTTPMethod.GET, HTTPMethod.HEAD, ...]
+
+.. _http-methods:
+
+HTTP methods
+-----------------
+
+Supported,
+`IANA-registered methods <https://www.iana.org/assignments/http-methods/http-methods.xhtml>`_
+available in :class:`http.HTTPMethod` are:
+
+=========== =================================== ==================================================================
+Method      Enum Name                           Details
+=========== =================================== ==================================================================
+``GET``     ``GET``                             HTTP/1.1 :rfc:`7231`, Section 4.3.1
+``HEAD``    ``HEAD``                            HTTP/1.1 :rfc:`7231`, Section 4.3.2
+``POST``    ``POST``                            HTTP/1.1 :rfc:`7231`, Section 4.3.3
+``PUT``     ``PUT``                             HTTP/1.1 :rfc:`7231`, Section 4.3.4
+``DELETE``  ``DELETE``                          HTTP/1.1 :rfc:`7231`, Section 4.3.5
+``CONNECT`` ``CONNECT``                         HTTP/1.1 :rfc:`7231`, Section 4.3.6
+``OPTIONS`` ``OPTIONS``                         HTTP/1.1 :rfc:`7231`, Section 4.3.7
+``TRACE``   ``TRACE``                           HTTP/1.1 :rfc:`7231`, Section 4.3.8
+``PATCH``   ``PATCH``                           HTTP/1.1 :rfc:`5789`
+=========== =================================== ==================================================================
diff --git a/Lib/http/__init__.py b/Lib/http/__init__.py
index 8b980e24a5..cd2885dc77 100644
--- a/Lib/http/__init__.py
+++ b/Lib/http/__init__.py
@@ -1,6 +1,6 @@
-from enum import IntEnum, _simple_enum
+from enum import StrEnum, IntEnum, _simple_enum
 
-__all__ = ['HTTPStatus']
+__all__ = ['HTTPStatus', 'HTTPMethod']
 
 
 @_simple_enum(IntEnum)
@@ -149,3 +149,32 @@ class HTTPStatus:
     NETWORK_AUTHENTICATION_REQUIRED = (511,
         'Network Authentication Required',
         'The client needs to authenticate to gain network access')
+
+
+@_simple_enum(StrEnum)
+class HTTPMethod:
+    """HTTP methods and descriptions
+
+    Methods from the following RFCs are all observed:
+
+        * RFC 7231: Hypertext Transfer Protocol (HTTP/1.1), obsoletes 2616
+        * RFC 5789: PATCH Method for HTTP
+    """
+    def __new__(cls, value, description):
+        obj = str.__new__(cls, value)
+        obj._value_ = value
+        obj.description = description
+        return obj
+
+    def __repr__(self):
+        return "<%s.%s>" % (self.__class__.__name__, self._name_)
+
+    CONNECT = 'CONNECT', 'Establish a connection to the server.'
+    DELETE = 'DELETE', 'Remove the target.'
+    GET = 'GET', 'Retrieve the target.'
+    HEAD = 'HEAD', 'Same as GET, but only retrieve the status line and header section.'
+    OPTIONS = 'OPTIONS', 'Describe the communication options for the target.'
+    PATCH = 'PATCH', 'Apply partial modifications to a target.'
+    POST = 'POST', 'Perform target-specific processing with the request payload.'
+    PUT = 'PUT', 'Replace the target with the request payload.'
+    TRACE = 'TRACE', 'Perform a message loop-back test along the path to the target.'
diff --git a/Misc/ACKS b/Misc/ACKS
index 2b9485e7aa..91cd4332d6 100644
--- a/Misc/ACKS
+++ b/Misc/ACKS
@@ -2004,6 +2004,7 @@ Arnaud Ysmal
 Bernard Yue
 Moshe Zadka
 Bader Zaidan
+Yair Zak
 Elias Zamaria
 Milan Zamazal
 Artur Zaprzala
diff --git a/Misc/NEWS.d/next/Library/2022-04-27-19-45-58.gh-issue-91996.YEEIzk.rst b/Misc/NEWS.d/next/Library/2022-04-27-19-45-58.gh-issue-91996.YEEIzk.rst
new file mode 100644
index 0000000000..72d9a597a1
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2022-04-27-19-45-58.gh-issue-91996.YEEIzk.rst
@@ -0,0 +1 @@
+New http.HTTPMethod enum to represent all the available HTTP request methods in a convenient way