diff --git a/Doc/library/http.rst b/Doc/library/http.rst index 1569d504c7f92a..5895a41d849bd1 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 `_ -status codes available in :class:`http.HTTPStatus` are: +`IANA-registered status codes `_ +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 `_ +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 8b980e24a5603f..cd2885dc7757b4 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 @@ def __new__(cls, value, phrase, description=''): 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 2b9485e7aa80c9..91cd4332d60465 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 00000000000000..72d9a597a1a59a --- /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