mirror of
https://github.com/python/cpython.git
synced 2025-11-19 02:39:15 +00:00
022ba6d161
rfc9110 obsoletes the earlier rfc 7231. This document also includes some status codes that were previously only used for WebDAV and assigns more generic names to these status codes. ref: https://www.rfc-editor.org/rfc/rfc9110.html#name-changes-from-rfc-7231 - http.HTTPStatus.CONTENT_TOO_LARGE (413, previously REQUEST_ENTITY_TOO_LARGE) - http.HTTPStatus.URI_TOO_LONG (414, previously REQUEST_URI_TOO_LONG) - http.HTTPStatus.RANGE_NOT_SATISFYABLE (416, previously REQUEST_RANGE_NOT_SATISFYABLE) - http.HTTPStatus.UNPROCESSABLE_CONTENT (422, previously UNPROCESSABLE_ENTITY) The new constants are added to http.HTTPStatus and the old constant names are preserved for backwards compatibility. References in documentation to the obsoleted rfc 7231 are updated
219 lines
11 KiB
ReStructuredText
219 lines
11 KiB
ReStructuredText
: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.
|
|
|
|
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`
|
|
=========== =================================== ==================================================================
|