| 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 |
=========== =================================== ================================================================== |