Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / cpython3 / a2eefa67542c25617a58c03a27c17fd48e2a0856 / . / Doc / library / http.rst
blob: 7c34004a3ae0822992414de0e58236bdabfd1dc3 [file] [log] [blame]
Georg Brandlfe7b00f2012-10-06 13:49:34 +0200[diff] [blame]1:mod:`http` --- HTTP modules
2============================
3
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]4.. module:: http
5 :synopsis: HTTP status codes and messages
6
Terry Jan Reedyfa089b92016-06-11 15:02:54 -0400[diff] [blame]7**Source code:** :source:`Lib/http/__init__.py`
8
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]9.. index::
10 pair: HTTP; protocol
11 single: HTTP; http (standard module)
12
Terry Jan Reedyfa089b92016-06-11 15:02:54 -0400[diff] [blame]13--------------
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]14
Berker Peksagcb18b952015-01-20 06:30:46 +0200[diff] [blame]15:mod:`http` is a package that collects several modules for working with the
Georg Brandlfe7b00f2012-10-06 13:49:34 +0200[diff] [blame]16HyperText 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
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]23
24:mod:`http` is also a module that defines a number of HTTP status codes and
25associated messages through the :class:`http.HTTPStatus` enum:
26
27.. class:: HTTPStatus
28
Berker Peksagbe6a5da2014-12-25 14:14:09 +0200[diff] [blame]29 .. versionadded:: 3.5
30
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]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: 200>
39 >>> HTTPStatus.OK == 200
40 True
41 >>> http.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: 100>, <HTTPStatus.SWITCHING_PROTOCOLS: 101>, ...]
49
Berker Peksagcb18b952015-01-20 06:30:46 +0200[diff] [blame]50.. _http-status-codes:
Serhiy Storchakae4db7692014-12-23 16:28:28 +0200[diff] [blame]51
Berker Peksagcb18b952015-01-20 06:30:46 +0200[diff] [blame]52HTTP status codes
53-----------------
54
55Supported,
Serhiy Storchaka6dff0202016-05-07 10:49:07 +0300[diff] [blame]56`IANA-registered <https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml>`_
Berker Peksagcb18b952015-01-20 06:30:46 +0200[diff] [blame]57status codes available in :class:`http.HTTPStatus` are:
58
59======= =================================== ==================================================================
60Code Enum Name Details
61======= =================================== ==================================================================
62``100`` ``CONTINUE`` HTTP/1.1 :rfc:`7231`, Section 6.2.1
63``101`` ``SWITCHING_PROTOCOLS`` HTTP/1.1 :rfc:`7231`, Section 6.2.2
64``102`` ``PROCESSING`` WebDAV :rfc:`2518`, Section 10.1
65``200`` ``OK`` HTTP/1.1 :rfc:`7231`, Section 6.3.1
66``201`` ``CREATED`` HTTP/1.1 :rfc:`7231`, Section 6.3.2
67``202`` ``ACCEPTED`` HTTP/1.1 :rfc:`7231`, Section 6.3.3
68``203`` ``NON_AUTHORITATIVE_INFORMATION`` HTTP/1.1 :rfc:`7231`, Section 6.3.4
69``204`` ``NO_CONTENT`` HTTP/1.1 :rfc:`7231`, Section 6.3.5
70``205`` ``RESET_CONTENT`` HTTP/1.1 :rfc:`7231`, Section 6.3.6
71``206`` ``PARTIAL_CONTENT`` HTTP/1.1 :rfc:`7233`, Section 4.1
72``207`` ``MULTI_STATUS`` WebDAV :rfc:`4918`, Section 11.1
73``208`` ``ALREADY_REPORTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.1 (Experimental)
74``226`` ``IM_USED`` Delta Encoding in HTTP :rfc:`3229`, Section 10.4.1
75``300`` ``MULTIPLE_CHOICES`` HTTP/1.1 :rfc:`7231`, Section 6.4.1
76``301`` ``MOVED_PERMANENTLY`` HTTP/1.1 :rfc:`7231`, Section 6.4.2
77``302`` ``FOUND`` HTTP/1.1 :rfc:`7231`, Section 6.4.3
78``303`` ``SEE_OTHER`` HTTP/1.1 :rfc:`7231`, Section 6.4.4
79``304`` ``NOT_MODIFIED`` HTTP/1.1 :rfc:`7232`, Section 4.1
80``305`` ``USE_PROXY`` HTTP/1.1 :rfc:`7231`, Section 6.4.5
81``307`` ``TEMPORARY_REDIRECT`` HTTP/1.1 :rfc:`7231`, Section 6.4.7
82``308`` ``PERMANENT_REDIRECT`` Permanent Redirect :rfc:`7238`, Section 3 (Experimental)
83``400`` ``BAD_REQUEST`` HTTP/1.1 :rfc:`7231`, Section 6.5.1
84``401`` ``UNAUTHORIZED`` HTTP/1.1 Authentication :rfc:`7235`, Section 3.1
85``402`` ``PAYMENT_REQUIRED`` HTTP/1.1 :rfc:`7231`, Section 6.5.2
86``403`` ``FORBIDDEN`` HTTP/1.1 :rfc:`7231`, Section 6.5.3
87``404`` ``NOT_FOUND`` HTTP/1.1 :rfc:`7231`, Section 6.5.4
88``405`` ``METHOD_NOT_ALLOWED`` HTTP/1.1 :rfc:`7231`, Section 6.5.5
89``406`` ``NOT_ACCEPTABLE`` HTTP/1.1 :rfc:`7231`, Section 6.5.6
90``407`` ``PROXY_AUTHENTICATION_REQUIRED`` HTTP/1.1 Authentication :rfc:`7235`, Section 3.2
91``408`` ``REQUEST_TIMEOUT`` HTTP/1.1 :rfc:`7231`, Section 6.5.7
92``409`` ``CONFLICT`` HTTP/1.1 :rfc:`7231`, Section 6.5.8
93``410`` ``GONE`` HTTP/1.1 :rfc:`7231`, Section 6.5.9
94``411`` ``LENGTH_REQUIRED`` HTTP/1.1 :rfc:`7231`, Section 6.5.10
95``412`` ``PRECONDITION_FAILED`` HTTP/1.1 :rfc:`7232`, Section 4.2
96``413`` ``REQUEST_ENTITY_TOO_LARGE`` HTTP/1.1 :rfc:`7231`, Section 6.5.11
97``414`` ``REQUEST_URI_TOO_LONG`` HTTP/1.1 :rfc:`7231`, Section 6.5.12
98``415`` ``UNSUPPORTED_MEDIA_TYPE`` HTTP/1.1 :rfc:`7231`, Section 6.5.13
99``416`` ``REQUEST_RANGE_NOT_SATISFIABLE`` HTTP/1.1 Range Requests :rfc:`7233`, Section 4.4
100``417`` ``EXPECTATION_FAILED`` HTTP/1.1 :rfc:`7231`, Section 6.5.14
Vitor Pereira52ad72d2017-10-26 19:49:19 +0100[diff] [blame]101``421`` ``MISDIRECTED_REQUEST`` HTTP/2 :rfc:`7540`, Section 9.1.2
Berker Peksagcb18b952015-01-20 06:30:46 +0200[diff] [blame]102``422`` ``UNPROCESSABLE_ENTITY`` WebDAV :rfc:`4918`, Section 11.2
103``423`` ``LOCKED`` WebDAV :rfc:`4918`, Section 11.3
104``424`` ``FAILED_DEPENDENCY`` WebDAV :rfc:`4918`, Section 11.4
105``426`` ``UPGRADE_REQUIRED`` HTTP/1.1 :rfc:`7231`, Section 6.5.15
106``428`` ``PRECONDITION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`
107``429`` ``TOO_MANY_REQUESTS`` Additional HTTP Status Codes :rfc:`6585`
108``431`` ``REQUEST_HEADER_FIELDS_TOO_LARGE`` Additional HTTP Status Codes :rfc:`6585`
109``500`` ``INTERNAL_SERVER_ERROR`` HTTP/1.1 :rfc:`7231`, Section 6.6.1
110``501`` ``NOT_IMPLEMENTED`` HTTP/1.1 :rfc:`7231`, Section 6.6.2
111``502`` ``BAD_GATEWAY`` HTTP/1.1 :rfc:`7231`, Section 6.6.3
112``503`` ``SERVICE_UNAVAILABLE`` HTTP/1.1 :rfc:`7231`, Section 6.6.4
113``504`` ``GATEWAY_TIMEOUT`` HTTP/1.1 :rfc:`7231`, Section 6.6.5
114``505`` ``HTTP_VERSION_NOT_SUPPORTED`` HTTP/1.1 :rfc:`7231`, Section 6.6.6
115``506`` ``VARIANT_ALSO_NEGOTIATES`` Transparent Content Negotiation in HTTP :rfc:`2295`, Section 8.1 (Experimental)
116``507`` ``INSUFFICIENT_STORAGE`` WebDAV :rfc:`4918`, Section 11.5
117``508`` ``LOOP_DETECTED`` WebDAV Binding Extensions :rfc:`5842`, Section 7.2 (Experimental)
118``510`` ``NOT_EXTENDED`` An HTTP Extension Framework :rfc:`2774`, Section 7 (Experimental)
119``511`` ``NETWORK_AUTHENTICATION_REQUIRED`` Additional HTTP Status Codes :rfc:`6585`, Section 6
120======= =================================== ==================================================================
121
122In order to preserve backwards compatibility, enum values are also present
Berker Peksag08f31432015-01-20 08:02:28 +0200[diff] [blame]123in the :mod:`http.client` module in the form of constants. The enum name is
124equal to the constant name (i.e. ``http.HTTPStatus.OK`` is also available as
125``http.client.OK``).
Vitor Pereira52ad72d2017-10-26 19:49:19 +0100[diff] [blame]126
127.. versionchanged:: 3.7
128 Added ``421 MISDIRECTED_REQUEST`` status code.