Debian Codegraph @

Doc/library/http.rst

raw
1 :mod:`!http` --- HTTP modules
2 =============================
3
4 .. module:: http
5 :synopsis: HTTP status codes and messages
6
7 **Source code:** :source:`Lib/http/__init__.py`
8
9 .. index::
10 pair: HTTP; protocol
11 single: HTTP; http (standard module)
12
13 --------------
14
15 :mod:`!http` is a package that collects several modules for working with the
16 HyperText Transfer Protocol:
17
18 * :mod:`http.client` is a low-level HTTP protocol client; for high-level URL
19 opening use :mod:`urllib.request`
20 * :mod:`http.server` contains basic HTTP server classes based on :mod:`socketserver`
21 * :mod:`http.cookies` has utilities for implementing state management with cookies
22 * :mod:`http.cookiejar` provides persistence of cookies
23
24
25 The :mod:`!http` module also defines the following enums that help you work with http related code:
26
27 .. class:: HTTPStatus
28
29 .. versionadded:: 3.5
30
31 A subclass of :class:`enum.IntEnum` that defines a set of HTTP status codes,
32 reason phrases and long descriptions written in English.
33
34 Usage::
35
36 >>> from http import HTTPStatus
37 >>> HTTPStatus.OK
38 HTTPStatus.OK
39 >>> HTTPStatus.OK == 200
40 True
41 >>> HTTPStatus.OK.value
42 200
43 >>> HTTPStatus.OK.phrase
44 'OK'
45 >>> HTTPStatus.OK.description
46 'Request fulfilled, document follows'
47 >>> list(HTTPStatus)
48 [HTTPStatus.CONTINUE, HTTPStatus.SWITCHING_PROTOCOLS, ...]
49
50 .. _http-status-codes:
51
52 HTTP status codes
53 -----------------
54
55 Supported,
56 `IANA-registered status codes <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_
57 available in :class:`http.HTTPStatus` are:
58
59 ======= =================================== ==================================================================
60 Code Enum Name Details
61 ======= =================================== ==================================================================
62 ``100`` ``CONTINUE`` HTTP Semantics :rfc:`9110`, Section 15.2.1
63 ``101`` ``SWITCHING_PROTOCOLS`` HTTP Semantics :rfc:`9110`, Section 15.2.2
64 ``102`` ``PROCESSING`` WebDAV :rfc:`2518`, Section 10.1
65 ``103`` ``EARLY_HINTS`` An HTTP Status Code for Indicating Hints :rfc:`8297`
66 ``200`` ``OK`` HTTP Semantics :rfc:`9110`, Section 15.3.1
67 ``201`` ``CREATED`` HTTP Semantics :rfc:`9110`, Section 15.3.2
68 ``202`` ``ACCEPTED`` HTTP Semantics :rfc:`9110`, Section 15.3.3
69 ``203`` ``NON_AUTHORITATIVE_INFORMATION`` HTTP Semantics :rfc:`9110`, Section 15.3.4
70 ``204`` ``NO_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.5
71 ``205`` ``RESET_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.6
72 ``206`` ``PARTIAL_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.7
73 ``207`` ``MULTI_STATUS`` WebDAV :rfc:`4918`, Section 11.1
74 ``208`` ``ALREADY_REPORTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.1 (Experimental)
75 ``226`` ``IM_USED`` Delta Encoding in HTTP :rfc:`3229`, Section 10.4.1
76 ``300`` ``MULTIPLE_CHOICES`` HTTP Semantics :rfc:`9110`, Section 15.4.1
77 ``301`` ``MOVED_PERMANENTLY`` HTTP Semantics :rfc:`9110`, Section 15.4.2
78 ``302`` ``FOUND`` HTTP Semantics :rfc:`9110`, Section 15.4.3
79 ``303`` ``SEE_OTHER`` HTTP Semantics :rfc:`9110`, Section 15.4.4
80 ``304`` ``NOT_MODIFIED`` HTTP Semantics :rfc:`9110`, Section 15.4.5
81 ``305`` ``USE_PROXY`` HTTP Semantics :rfc:`9110`, Section 15.4.6
82 ``307`` ``TEMPORARY_REDIRECT`` HTTP Semantics :rfc:`9110`, Section 15.4.8
83 ``308`` ``PERMANENT_REDIRECT`` HTTP Semantics :rfc:`9110`, Section 15.4.9
84 ``400`` ``BAD_REQUEST`` HTTP Semantics :rfc:`9110`, Section 15.5.1
85 ``401`` ``UNAUTHORIZED`` HTTP Semantics :rfc:`9110`, Section 15.5.2
86 ``402`` ``PAYMENT_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.3
87 ``403`` ``FORBIDDEN`` HTTP Semantics :rfc:`9110`, Section 15.5.4
88 ``404`` ``NOT_FOUND`` HTTP Semantics :rfc:`9110`, Section 15.5.5
89 ``405`` ``METHOD_NOT_ALLOWED`` HTTP Semantics :rfc:`9110`, Section 15.5.6
90 ``406`` ``NOT_ACCEPTABLE`` HTTP Semantics :rfc:`9110`, Section 15.5.7
91 ``407`` ``PROXY_AUTHENTICATION_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.8
92 ``408`` ``REQUEST_TIMEOUT`` HTTP Semantics :rfc:`9110`, Section 15.5.9
93 ``409`` ``CONFLICT`` HTTP Semantics :rfc:`9110`, Section 15.5.10
94 ``410`` ``GONE`` HTTP Semantics :rfc:`9110`, Section 15.5.11
95 ``411`` ``LENGTH_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.12
96 ``412`` ``PRECONDITION_FAILED`` HTTP Semantics :rfc:`9110`, Section 15.5.13
97 ``413`` ``CONTENT_TOO_LARGE`` HTTP Semantics :rfc:`9110`, Section 15.5.14
98 ``414`` ``URI_TOO_LONG`` HTTP Semantics :rfc:`9110`, Section 15.5.15
99 ``415`` ``UNSUPPORTED_MEDIA_TYPE`` HTTP Semantics :rfc:`9110`, Section 15.5.16
100 ``416`` ``RANGE_NOT_SATISFIABLE`` HTTP Semantics :rfc:`9110`, Section 15.5.17
101 ``417`` ``EXPECTATION_FAILED`` HTTP Semantics :rfc:`9110`, Section 15.5.18
102 ``418`` ``IM_A_TEAPOT`` HTCPCP/1.0 :rfc:`2324`, Section 2.3.2
103 ``421`` ``MISDIRECTED_REQUEST`` HTTP Semantics :rfc:`9110`, Section 15.5.20
104 ``422`` ``UNPROCESSABLE_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.5.21
105 ``423`` ``LOCKED`` WebDAV :rfc:`4918`, Section 11.3
106 ``424`` ``FAILED_DEPENDENCY`` WebDAV :rfc:`4918`, Section 11.4
107 ``425`` ``TOO_EARLY`` Using Early Data in HTTP :rfc:`8470`
108 ``426`` ``UPGRADE_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.22
109 ``428`` ``PRECONDITION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`
110 ``429`` ``TOO_MANY_REQUESTS`` Additional HTTP Status Codes :rfc:`6585`
111 ``431`` ``REQUEST_HEADER_FIELDS_TOO_LARGE`` Additional HTTP Status Codes :rfc:`6585`
112 ``451`` ``UNAVAILABLE_FOR_LEGAL_REASONS`` An HTTP Status Code to Report Legal Obstacles :rfc:`7725`
113 ``500`` ``INTERNAL_SERVER_ERROR`` HTTP Semantics :rfc:`9110`, Section 15.6.1
114 ``501`` ``NOT_IMPLEMENTED`` HTTP Semantics :rfc:`9110`, Section 15.6.2
115 ``502`` ``BAD_GATEWAY`` HTTP Semantics :rfc:`9110`, Section 15.6.3
116 ``503`` ``SERVICE_UNAVAILABLE`` HTTP Semantics :rfc:`9110`, Section 15.6.4
117 ``504`` ``GATEWAY_TIMEOUT`` HTTP Semantics :rfc:`9110`, Section 15.6.5
118 ``505`` ``HTTP_VERSION_NOT_SUPPORTED`` HTTP Semantics :rfc:`9110`, Section 15.6.6
119 ``506`` ``VARIANT_ALSO_NEGOTIATES`` Transparent Content Negotiation in HTTP :rfc:`2295`, Section 8.1 (Experimental)
120 ``507`` ``INSUFFICIENT_STORAGE`` WebDAV :rfc:`4918`, Section 11.5
121 ``508`` ``LOOP_DETECTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.2 (Experimental)
122 ``510`` ``NOT_EXTENDED`` An HTTP Extension Framework :rfc:`2774`, Section 7 (Experimental)
123 ``511`` ``NETWORK_AUTHENTICATION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`, Section 6
124 ======= =================================== ==================================================================
125
126 In order to preserve backwards compatibility, enum values are also present
127 in the :mod:`http.client` module in the form of constants. The enum name is
128 equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
129 ``http.client.OK``).
130
131 .. versionchanged:: 3.7
132 Added ``421 MISDIRECTED_REQUEST`` status code.
133
134 .. versionadded:: 3.8
135 Added ``451 UNAVAILABLE_FOR_LEGAL_REASONS`` status code.
136
137 .. versionadded:: 3.9
138 Added ``103 EARLY_HINTS``, ``418 IM_A_TEAPOT`` and ``425 TOO_EARLY`` status codes.
139
140 .. versionchanged:: 3.13
141 Implemented RFC9110 naming for status constants. Old constant names are preserved for
142 backwards compatibility: ``413 REQUEST_ENTITY_TOO_LARGE``, ``414 REQUEST_URI_TOO_LONG``,
143 ``416 REQUESTED_RANGE_NOT_SATISFIABLE`` and ``422 UNPROCESSABLE_ENTITY``.
144
145 HTTP status category
146 --------------------
147
148 .. versionadded:: 3.12
149
150 The enum values have several properties to indicate the HTTP status category:
151
152 ==================== ======================== ======================================
153 Property Indicates that Details
154 ==================== ======================== ======================================
155 ``is_informational`` ``100 <= status <= 199`` HTTP Semantics :rfc:`9110`, Section 15
156 ``is_success`` ``200 <= status <= 299`` HTTP Semantics :rfc:`9110`, Section 15
157 ``is_redirection`` ``300 <= status <= 399`` HTTP Semantics :rfc:`9110`, Section 15
158 ``is_client_error`` ``400 <= status <= 499`` HTTP Semantics :rfc:`9110`, Section 15
159 ``is_server_error`` ``500 <= status <= 599`` HTTP Semantics :rfc:`9110`, Section 15
160 ==================== ======================== ======================================
161
162 Usage::
163
164 >>> from http import HTTPStatus
165 >>> HTTPStatus.OK.is_success
166 True
167 >>> HTTPStatus.OK.is_client_error
168 False
169
170 .. class:: HTTPMethod
171
172 .. versionadded:: 3.11
173
174 A subclass of :class:`enum.StrEnum` that defines a set of HTTP methods and descriptions written in English.
175
176 Usage::
177
178 >>> from http import HTTPMethod
179 >>>
180 >>> HTTPMethod.GET
181 <HTTPMethod.GET>
182 >>> HTTPMethod.GET == 'GET'
183 True
184 >>> HTTPMethod.GET.value
185 'GET'
186 >>> HTTPMethod.GET.description
187 'Retrieve the target.'
188 >>> list(HTTPMethod)
189 [<HTTPMethod.CONNECT>,
190 <HTTPMethod.DELETE>,
191 <HTTPMethod.GET>,
192 <HTTPMethod.HEAD>,
193 <HTTPMethod.OPTIONS>,
194 <HTTPMethod.PATCH>,
195 <HTTPMethod.POST>,
196 <HTTPMethod.PUT>,
197 <HTTPMethod.TRACE>]
198
199 .. _http-methods:
200
201 HTTP methods
202 -----------------
203
204 Supported,
205 `IANA-registered methods <https://www.iana.org/assignments/http-methods/http-methods.xhtml>`_
206 available in :class:`http.HTTPMethod` are:
207
208 =========== =================================== ==================================================================
209 Method Enum Name Details
210 =========== =================================== ==================================================================
211 ``GET`` ``GET`` HTTP Semantics :rfc:`9110`, Section 9.3.1
212 ``HEAD`` ``HEAD`` HTTP Semantics :rfc:`9110`, Section 9.3.2
213 ``POST`` ``POST`` HTTP Semantics :rfc:`9110`, Section 9.3.3
214 ``PUT`` ``PUT`` HTTP Semantics :rfc:`9110`, Section 9.3.4
215 ``DELETE`` ``DELETE`` HTTP Semantics :rfc:`9110`, Section 9.3.5
216 ``CONNECT`` ``CONNECT`` HTTP Semantics :rfc:`9110`, Section 9.3.6
217 ``OPTIONS`` ``OPTIONS`` HTTP Semantics :rfc:`9110`, Section 9.3.7
218 ``TRACE`` ``TRACE`` HTTP Semantics :rfc:`9110`, Section 9.3.8
219 ``PATCH`` ``PATCH`` HTTP/1.1 :rfc:`5789`
220 =========== =================================== ==================================================================