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