# `http` --- HTTP 模組

原始碼：Lib/http/__init__.py

`http` 是一個收集了多個用於處理超文本傳輸協定 (HyperText Transfer Protocol) 之模組 (module) 的套件：

- `http.client` 是一個低階的 HTTP 協定客戶端；對於高階的 URL 訪問請使用 `urllib.request`

- `http.server` 包含基於 `socketserver` 的基本 HTTP 伺服器類別

- `http.cookies` 包含通過 cookies 實作狀態管理的工具程式 (utilities)

- `http.cookiejar` 提供了 cookies 的持續留存 (persistence)

The `http` module also defines the following enums that help you work with http related code:

class http.HTTPStatus

  在 3.5 版被加入.

  `enum.IntEnum` 的子類別，它定義了一組 HTTP 狀態碼、原理短語 (reason phrase) 以及英文長描述。

  用法：

      >>> 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 狀態碼

`http.HTTPStatus` 當中，已支援並且有於 IANA 註冊的狀態碼有：

狀態碼 | 列舉名稱 | 詳情
--- | --- | ---
`100` | `CONTINUE` | HTTP/1.1 RFC 7231，6.2.1 節
`101` | `SWITCHING_PROTOCOLS` | HTTP/1.1 RFC 7231，6.2.2 節
`102` | `PROCESSING` | WebDAV RFC 2518，10.1 節
`103` | `EARLY_HINTS` | 用於指定提示 (Indicating Hints) RFC 8297 的 HTTP 狀態碼
`200` | `OK` | HTTP/1.1 RFC 7231，6.3.1 節
`201` | `CREATED` | HTTP/1.1 RFC 7231，6.3.2 節
`202` | `ACCEPTED` | HTTP/1.1 RFC 7231，6.3.3 節
`203` | `NON_AUTHORITATIVE_INFORMATION` | HTTP/1.1 RFC 7231，6.3.4 節
`204` | `NO_CONTENT` | HTTP/1.1 RFC 7231，6.3.5 節
`205` | `RESET_CONTENT` | HTTP/1.1 RFC 7231，6.3.6 節
`206` | `PARTIAL_CONTENT` | HTTP/1.1 RFC 7233，4.1 節
`207` | `MULTI_STATUS` | WebDAV RFC 4918，11.1 節
`208` | `ALREADY_REPORTED` | WebDAV 繫結擴充 (Binding Extensions) RFC 5842，7.1 節（實驗性）
`226` | `IM_USED` | HTTP 中的差分編碼 RFC 3229，10.4.1 節
`300` | `MULTIPLE_CHOICES` | HTTP/1.1 RFC 7231，6.4.1 節
`301` | `MOVED_PERMANENTLY` | HTTP/1.1 RFC 7231，6.4.2 節
`302` | `FOUND` | HTTP/1.1 RFC 7231，6.4.3 節
`303` | `SEE_OTHER` | HTTP/1.1 RFC 7231，6.4.4 節
`304` | `NOT_MODIFIED` | HTTP/1.1 RFC 7232，4.1 節
`305` | `USE_PROXY` | HTTP/1.1 RFC 7231，6.4.5 節
`307` | `TEMPORARY_REDIRECT` | HTTP/1.1 RFC 7231，6.4.7 節
`308` | `PERMANENT_REDIRECT` | 永久重定向 RFC 7238，3 節（實驗性）
`400` | `BAD_REQUEST` | HTTP/1.1 RFC 7231，6.5.1 節
`401` | `UNAUTHORIZED` | HTTP/1.1 身分驗證 (Authentication) RFC 7235，3.1 節
`402` | `PAYMENT_REQUIRED` | HTTP/1.1 RFC 7231，6.5.2 節
`403` | `FORBIDDEN` | HTTP/1.1 RFC 7231，6.5.3 節
`404` | `NOT_FOUND` | HTTP/1.1 RFC 7231，6.5.4 節
`405` | `METHOD_NOT_ALLOWED` | HTTP/1.1 RFC 7231，6.5.5 節
`406` | `NOT_ACCEPTABLE` | HTTP/1.1 RFC 7231，6.5.6 節
`407` | `PROXY_AUTHENTICATION_REQUIRED` | HTTP/1.1 身分驗證 RFC 7235，3.2 節
`408` | `REQUEST_TIMEOUT` | HTTP/1.1 RFC 7231，6.5.7 節
`409` | `CONFLICT` | HTTP/1.1 RFC 7231，6.5.8 節
`410` | `GONE` | HTTP/1.1 RFC 7231，6.5.9 節
`411` | `LENGTH_REQUIRED` | HTTP/1.1 RFC 7231，6.5.10 節
`412` | `PRECONDITION_FAILED` | HTTP/1.1 RFC 7232，4.2 節
`413` | `REQUEST_ENTITY_TOO_LARGE` | HTTP/1.1 RFC 7231，6.5.11 節
`414` | `REQUEST_URI_TOO_LONG` | HTTP/1.1 RFC 7231，6.5.12 節
`415` | `UNSUPPORTED_MEDIA_TYPE` | HTTP/1.1 RFC 7231，6.5.13 節
`416` | `REQUESTED_RANGE_NOT_SATISFIABLE` | HTTP/1.1 範圍請求 (Range Requests) RFC 7233，4.4 節
`417` | `EXPECTATION_FAILED` | HTTP/1.1 RFC 7231，6.5.14 節
`418` | `IM_A_TEAPOT` | HTCPCP/1.0 RFC 2324，Section 2.3.2
`421` | `MISDIRECTED_REQUEST` | HTTP/2 RFC 7540，9.1.2 節
`422` | `UNPROCESSABLE_ENTITY` | WebDAV RFC 4918，11.2 節
`423` | `LOCKED` | WebDAV RFC 4918，11.3 節
`424` | `FAILED_DEPENDENCY` | WebDAV RFC 4918，11.4 節
`425` | `TOO_EARLY` | 使用 HTTP 中的早期資料 RFC 8470
`426` | `UPGRADE_REQUIRED` | HTTP/1.1 RFC 7231，6.5.15 節
`428` | `PRECONDITION_REQUIRED` | 額外的 HTTP 狀態碼 RFC 6585
`429` | `TOO_MANY_REQUESTS` | 額外的 HTTP 狀態碼 RFC 6585
`431` | `REQUEST_HEADER_FIELDS_TOO_LARGE` | 額外的 HTTP 狀態碼 RFC 6585
`451` | `UNAVAILABLE_FOR_LEGAL_REASONS` | 一個用來回報合法性障礙 (Legal Obstacles) 的 HTTP 狀態碼 RFC 7725
`500` | `INTERNAL_SERVER_ERROR` | HTTP/1.1 RFC 7231，6.6.1 節
`501` | `NOT_IMPLEMENTED` | HTTP/1.1 RFC 7231，6.6.2 節
`502` | `BAD_GATEWAY` | HTTP/1.1 RFC 7231，6.6.3 節
`503` | `SERVICE_UNAVAILABLE` | HTTP/1.1 RFC 7231，6.6.4 節
`504` | `GATEWAY_TIMEOUT` | HTTP/1.1 RFC 7231，6.6.5 節
`505` | `HTTP_VERSION_NOT_SUPPORTED` | HTTP/1.1 RFC 7231，6.6.6 節
`506` | `VARIANT_ALSO_NEGOTIATES` | HTTP 中的透明內容協商 (Transparent Content Negotiation) RFC 2295，8.1 節（實驗性）
`507` | `INSUFFICIENT_STORAGE` | WebDAV RFC 4918，11.5 節
`508` | `LOOP_DETECTED` | WebDAV 繫結擴充 RFC 5842，7.2 節（實驗性）
`510` | `NOT_EXTENDED` | 一個 HTTP 擴充框架 RFC 2774，7 節（實驗性）
`511` | `NETWORK_AUTHENTICATION_REQUIRED` | 額外的 HTTP 狀態碼 RFC 6585，6 節

為了向後相容性，列舉值也以常數形式出現在 `http.client` 模組中。列舉名稱等於常數名稱（例如 `http.HTTPStatus.OK` 也可以是 `http.client.OK`）。

在 3.7 版的變更: 新增 `421 MISDIRECTED_REQUEST` 狀態碼。

在 3.8 版被加入: 新增 `451 UNAVAILABLE_FOR_LEGAL_REASONS` 狀態碼。

在 3.9 版被加入: 新增 `103 EARLY_HINTS`、`418 IM_A_TEAPOT` 與 `425 TOO_EARLY` 狀態碼。

## HTTP 狀態分類

在 3.12 版被加入.

The enum values have several properties to indicate the HTTP status category:

Property | Indicates that | 詳情
--- | --- | ---
`is_informational` | `100 <= status <= 199` | HTTP/1.1 RFC 7231，6 節
`is_success` | `200 <= status <= 299` | HTTP/1.1 RFC 7231，6 節
`is_redirection` | `300 <= status <= 399` | HTTP/1.1 RFC 7231，6 節
`is_client_error` | `400 <= status <= 499` | HTTP/1.1 RFC 7231，6 節
`is_server_error` | `500 <= status <= 599` | HTTP/1.1 RFC 7231，6 節

> 用法：

>     >>> from http import HTTPStatus
>     >>> HTTPStatus.OK.is_success
>     True
>     >>> HTTPStatus.OK.is_client_error
>     False

class http.HTTPMethod

  在 3.11 版被加入.

  `enum.StrEnum` 的子類別，它定義了一組 HTTP 方法以及英文描述。

  用法：

      >>> 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 方法

`http.HTTPStatus` 當中，已支援並且有於 IANA 註冊的狀態碼有：

方法 | 列舉名稱 | 詳情
--- | --- | ---
`GET` | `GET` | HTTP/1.1 RFC 7231，4.3.1 節
`HEAD` | `HEAD` | HTTP/1.1 RFC 7231，4.3.2 節
`POST` | `POST` | HTTP/1.1 RFC 7231，4.3.3 節
`PUT` | `PUT` | HTTP/1.1 RFC 7231，4.3.4 節
`DELETE` | `DELETE` | HTTP/1.1 RFC 7231，6.3.5 節
`CONNECT` | `CONNECT` | HTTP/1.1 RFC 7231，4.3.6 節
`OPTIONS` | `OPTIONS` | HTTP/1.1 RFC 7231，4.3.7 節
`TRACE` | `TRACE` | HTTP/1.1 RFC 7231，4.3.8 節
`PATCH` | `PATCH` | HTTP/1.1 RFC 5789