mirror of https://github.com/python/cpython
220 lines
11 KiB
ReStructuredText
220 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`
|
|
=========== =================================== ==================================================================
|