[Python-checkins] gh-91996: Add an HTTPMethod StrEnum to http (GH-91997)
ethanfurman
webhook-mailer at python.org
Thu May 5 18:39:18 EDT 2022
https://github.com/python/cpython/commit/9a0a7b4868c1e40a1863394bc475132b47d8926f
commit: 9a0a7b4868c1e40a1863394bc475132b47d8926f
branch: main
author: cibofo <53799417+cibofo at users.noreply.github.com>
committer: ethanfurman <ethan at stoneleaf.us>
date: 2022-05-05T15:39:02-07:00
summary:
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 at stoneleaf.us>
files:
A Misc/NEWS.d/next/Library/2022-04-27-19-45-58.gh-issue-91996.YEEIzk.rst
M Doc/library/http.rst
M Lib/http/__init__.py
M Misc/ACKS
diff --git a/Doc/library/http.rst b/Doc/library/http.rst
index 1569d504c7f92..5895a41d849bd 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 8b980e24a5603..cd2885dc7757b 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')
+
+
+ at _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 2b9485e7aa80c..91cd4332d6046 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 0000000000000..72d9a597a1a59
--- /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
More information about the Python-checkins
mailing list