| :mod:`!http` --- HTTP modules | |
| ============================= | |
| .. module:: http | |
| :synopsis: HTTP status codes and messages | |
| **Source code:** :source:`Lib/http/__init__.py` | |
| .. index:: | |
| pair: HTTP; protocol | |
| single: HTTP; http (standard module) | |
| -------------- | |
| :mod:`!http` is a package that collects several modules for working with the | |
| HyperText Transfer Protocol: | |
| * :mod:`http.client` is a low-level HTTP protocol client; for high-level URL | |
| opening use :mod:`urllib.request` | |
| * :mod:`http.server` contains basic HTTP server classes based on :mod:`socketserver` | |
| * :mod:`http.cookies` has utilities for implementing state management with cookies | |
| * :mod:`http.cookiejar` provides persistence of cookies | |
| The :mod:`!http` module also defines the following enums that help you work with http related code: | |
| .. class:: HTTPStatus | |
| .. versionadded:: 3.5 | |
| A subclass of :class:`enum.IntEnum` that defines a set of HTTP status codes, | |
| reason phrases and long descriptions written in English. | |
| Usage:: | |
| >>> from http import HTTPStatus | |
| >>> HTTPStatus.OK | |
| HTTPStatus.OK | |
| >>> HTTPStatus.OK == 200 | |
| True | |
| >>> HTTPStatus.OK.value | |
| 200 | |
| >>> HTTPStatus.OK.phrase | |
| 'OK' | |
| >>> HTTPStatus.OK.description | |
| 'Request fulfilled, document follows' | |
| >>> list(HTTPStatus) | |
| [HTTPStatus.CONTINUE, HTTPStatus.SWITCHING_PROTOCOLS, ...] | |
| .. _http-status-codes: | |
| HTTP status codes | |
| ----------------- | |
| Supported, | |
| `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 | |
| ======= =================================== ================================================================== | |
| ``100`` ``CONTINUE`` HTTP Semantics :rfc:`9110`, Section 15.2.1 | |
| ``101`` ``SWITCHING_PROTOCOLS`` HTTP Semantics :rfc:`9110`, Section 15.2.2 | |
| ``102`` ``PROCESSING`` WebDAV :rfc:`2518`, Section 10.1 | |
| ``103`` ``EARLY_HINTS`` An HTTP Status Code for Indicating Hints :rfc:`8297` | |
| ``200`` ``OK`` HTTP Semantics :rfc:`9110`, Section 15.3.1 | |
| ``201`` ``CREATED`` HTTP Semantics :rfc:`9110`, Section 15.3.2 | |
| ``202`` ``ACCEPTED`` HTTP Semantics :rfc:`9110`, Section 15.3.3 | |
| ``203`` ``NON_AUTHORITATIVE_INFORMATION`` HTTP Semantics :rfc:`9110`, Section 15.3.4 | |
| ``204`` ``NO_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.5 | |
| ``205`` ``RESET_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.6 | |
| ``206`` ``PARTIAL_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.3.7 | |
| ``207`` ``MULTI_STATUS`` WebDAV :rfc:`4918`, Section 11.1 | |
| ``208`` ``ALREADY_REPORTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.1 (Experimental) | |
| ``226`` ``IM_USED`` Delta Encoding in HTTP :rfc:`3229`, Section 10.4.1 | |
| ``300`` ``MULTIPLE_CHOICES`` HTTP Semantics :rfc:`9110`, Section 15.4.1 | |
| ``301`` ``MOVED_PERMANENTLY`` HTTP Semantics :rfc:`9110`, Section 15.4.2 | |
| ``302`` ``FOUND`` HTTP Semantics :rfc:`9110`, Section 15.4.3 | |
| ``303`` ``SEE_OTHER`` HTTP Semantics :rfc:`9110`, Section 15.4.4 | |
| ``304`` ``NOT_MODIFIED`` HTTP Semantics :rfc:`9110`, Section 15.4.5 | |
| ``305`` ``USE_PROXY`` HTTP Semantics :rfc:`9110`, Section 15.4.6 | |
| ``307`` ``TEMPORARY_REDIRECT`` HTTP Semantics :rfc:`9110`, Section 15.4.8 | |
| ``308`` ``PERMANENT_REDIRECT`` HTTP Semantics :rfc:`9110`, Section 15.4.9 | |
| ``400`` ``BAD_REQUEST`` HTTP Semantics :rfc:`9110`, Section 15.5.1 | |
| ``401`` ``UNAUTHORIZED`` HTTP Semantics :rfc:`9110`, Section 15.5.2 | |
| ``402`` ``PAYMENT_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.3 | |
| ``403`` ``FORBIDDEN`` HTTP Semantics :rfc:`9110`, Section 15.5.4 | |
| ``404`` ``NOT_FOUND`` HTTP Semantics :rfc:`9110`, Section 15.5.5 | |
| ``405`` ``METHOD_NOT_ALLOWED`` HTTP Semantics :rfc:`9110`, Section 15.5.6 | |
| ``406`` ``NOT_ACCEPTABLE`` HTTP Semantics :rfc:`9110`, Section 15.5.7 | |
| ``407`` ``PROXY_AUTHENTICATION_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.8 | |
| ``408`` ``REQUEST_TIMEOUT`` HTTP Semantics :rfc:`9110`, Section 15.5.9 | |
| ``409`` ``CONFLICT`` HTTP Semantics :rfc:`9110`, Section 15.5.10 | |
| ``410`` ``GONE`` HTTP Semantics :rfc:`9110`, Section 15.5.11 | |
| ``411`` ``LENGTH_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.12 | |
| ``412`` ``PRECONDITION_FAILED`` HTTP Semantics :rfc:`9110`, Section 15.5.13 | |
| ``413`` ``CONTENT_TOO_LARGE`` HTTP Semantics :rfc:`9110`, Section 15.5.14 | |
| ``414`` ``URI_TOO_LONG`` HTTP Semantics :rfc:`9110`, Section 15.5.15 | |
| ``415`` ``UNSUPPORTED_MEDIA_TYPE`` HTTP Semantics :rfc:`9110`, Section 15.5.16 | |
| ``416`` ``RANGE_NOT_SATISFIABLE`` HTTP Semantics :rfc:`9110`, Section 15.5.17 | |
| ``417`` ``EXPECTATION_FAILED`` HTTP Semantics :rfc:`9110`, Section 15.5.18 | |
| ``418`` ``IM_A_TEAPOT`` HTCPCP/1.0 :rfc:`2324`, Section 2.3.2 | |
| ``421`` ``MISDIRECTED_REQUEST`` HTTP Semantics :rfc:`9110`, Section 15.5.20 | |
| ``422`` ``UNPROCESSABLE_CONTENT`` HTTP Semantics :rfc:`9110`, Section 15.5.21 | |
| ``423`` ``LOCKED`` WebDAV :rfc:`4918`, Section 11.3 | |
| ``424`` ``FAILED_DEPENDENCY`` WebDAV :rfc:`4918`, Section 11.4 | |
| ``425`` ``TOO_EARLY`` Using Early Data in HTTP :rfc:`8470` | |
| ``426`` ``UPGRADE_REQUIRED`` HTTP Semantics :rfc:`9110`, Section 15.5.22 | |
| ``428`` ``PRECONDITION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585` | |
| ``429`` ``TOO_MANY_REQUESTS`` Additional HTTP Status Codes :rfc:`6585` | |
| ``431`` ``REQUEST_HEADER_FIELDS_TOO_LARGE`` Additional HTTP Status Codes :rfc:`6585` | |
| ``451`` ``UNAVAILABLE_FOR_LEGAL_REASONS`` An HTTP Status Code to Report Legal Obstacles :rfc:`7725` | |
| ``500`` ``INTERNAL_SERVER_ERROR`` HTTP Semantics :rfc:`9110`, Section 15.6.1 | |
| ``501`` ``NOT_IMPLEMENTED`` HTTP Semantics :rfc:`9110`, Section 15.6.2 | |
| ``502`` ``BAD_GATEWAY`` HTTP Semantics :rfc:`9110`, Section 15.6.3 | |
| ``503`` ``SERVICE_UNAVAILABLE`` HTTP Semantics :rfc:`9110`, Section 15.6.4 | |
| ``504`` ``GATEWAY_TIMEOUT`` HTTP Semantics :rfc:`9110`, Section 15.6.5 | |
| ``505`` ``HTTP_VERSION_NOT_SUPPORTED`` HTTP Semantics :rfc:`9110`, Section 15.6.6 | |
| ``506`` ``VARIANT_ALSO_NEGOTIATES`` Transparent Content Negotiation in HTTP :rfc:`2295`, Section 8.1 (Experimental) | |
| ``507`` ``INSUFFICIENT_STORAGE`` WebDAV :rfc:`4918`, Section 11.5 | |
| ``508`` ``LOOP_DETECTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.2 (Experimental) | |
| ``510`` ``NOT_EXTENDED`` An HTTP Extension Framework :rfc:`2774`, Section 7 (Experimental) | |
| ``511`` ``NETWORK_AUTHENTICATION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`, Section 6 | |
| ======= =================================== ================================================================== | |
| In order to preserve backwards compatibility, enum values are also present | |
| in the :mod:`http.client` module in the form of constants. The enum name is | |
| equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as | |
| ``http.client.OK``). | |
| .. versionchanged:: 3.7 | |
| Added ``421 MISDIRECTED_REQUEST`` status code. | |
| .. versionadded:: 3.8 | |
| Added ``451 UNAVAILABLE_FOR_LEGAL_REASONS`` status code. | |
| .. versionadded:: 3.9 | |
| Added ``103 EARLY_HINTS``, ``418 IM_A_TEAPOT`` and ``425 TOO_EARLY`` status codes. | |
| .. versionchanged:: 3.13 | |
| Implemented RFC9110 naming for status constants. Old constant names are preserved for | |
| backwards compatibility: ``413 REQUEST_ENTITY_TOO_LARGE``, ``414 REQUEST_URI_TOO_LONG``, | |
| ``416 REQUESTED_RANGE_NOT_SATISFIABLE`` and ``422 UNPROCESSABLE_ENTITY``. | |
| HTTP status category | |
| -------------------- | |
| .. versionadded:: 3.12 | |
| The enum values have several properties to indicate the HTTP status category: | |
| ==================== ======================== ====================================== | |
| Property Indicates that Details | |
| ==================== ======================== ====================================== | |
| ``is_informational`` ``100 <= status <= 199`` HTTP Semantics :rfc:`9110`, Section 15 | |
| ``is_success`` ``200 <= status <= 299`` HTTP Semantics :rfc:`9110`, Section 15 | |
| ``is_redirection`` ``300 <= status <= 399`` HTTP Semantics :rfc:`9110`, Section 15 | |
| ``is_client_error`` ``400 <= status <= 499`` HTTP Semantics :rfc:`9110`, Section 15 | |
| ``is_server_error`` ``500 <= status <= 599`` HTTP Semantics :rfc:`9110`, Section 15 | |
| ==================== ======================== ====================================== | |
| Usage:: | |
| >>> from http import HTTPStatus | |
| >>> HTTPStatus.OK.is_success | |
| True | |
| >>> HTTPStatus.OK.is_client_error | |
| False | |
| .. 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 | |
| >>> | |
| >>> HTTPMethod.GET | |
| <HTTPMethod.GET> | |
| >>> HTTPMethod.GET == 'GET' | |
| True | |
| >>> HTTPMethod.GET.value | |
| 'GET' | |
| >>> HTTPMethod.GET.description | |
| 'Retrieve the target.' | |
| >>> list(HTTPMethod) | |
| [<HTTPMethod.CONNECT>, | |
| <HTTPMethod.DELETE>, | |
| <HTTPMethod.GET>, | |
| <HTTPMethod.HEAD>, | |
| <HTTPMethod.OPTIONS>, | |
| <HTTPMethod.PATCH>, | |
| <HTTPMethod.POST>, | |
| <HTTPMethod.PUT>, | |
| <HTTPMethod.TRACE>] | |
| .. _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 Semantics :rfc:`9110`, Section 9.3.1 | |
| ``HEAD`` ``HEAD`` HTTP Semantics :rfc:`9110`, Section 9.3.2 | |
| ``POST`` ``POST`` HTTP Semantics :rfc:`9110`, Section 9.3.3 | |
| ``PUT`` ``PUT`` HTTP Semantics :rfc:`9110`, Section 9.3.4 | |
| ``DELETE`` ``DELETE`` HTTP Semantics :rfc:`9110`, Section 9.3.5 | |
| ``CONNECT`` ``CONNECT`` HTTP Semantics :rfc:`9110`, Section 9.3.6 | |
| ``OPTIONS`` ``OPTIONS`` HTTP Semantics :rfc:`9110`, Section 9.3.7 | |
| ``TRACE`` ``TRACE`` HTTP Semantics :rfc:`9110`, Section 9.3.8 | |
| ``PATCH`` ``PATCH`` HTTP/1.1 :rfc:`5789` | |
| =========== =================================== ================================================================== |