21.12. `http.client` — HTTP 协议客户端¶

这个模块定义了实现 HTTP 和 HTTPS 协议客户端的类。它通常不直接使用 — 模块 urllib.request 用它来处理使用 HTTP 和 HTTPS 的 URL。

也參考

The Requests package is recommended for a higher-level HTTP client interface.

備註

HTTPS 支持仅在编译 Python 时启用了 SSL 支持的情况下（通过 ssl 模块）可用。

该模块支持以下类：

class http.client.HTTPConnection(host, port=None, [timeout, ]source_address=None)¶

An HTTPConnection instance represents one transaction with an HTTP server. It should be instantiated passing it a host and optional port number. If no port number is passed, the port is extracted from the host string if it has the form host:port, else the default HTTP port (80) is used. If the optional timeout parameter is given, blocking operations (like connection attempts) will timeout after that many seconds (if it is not given, the global default timeout setting is used). The optional source_address parameter may be a tuple of a (host, port) to use as the source address the HTTP connection is made from.

举个例子，以下调用都是创建连接到同一主机和端口的服务器的实例：

>>> h1 = http.client.HTTPConnection('www.python.org')
>>> h2 = http.client.HTTPConnection('www.python.org:80')
>>> h3 = http.client.HTTPConnection('www.python.org', 80)
>>> h4 = http.client.HTTPConnection('www.python.org', 80, timeout=10)

3.2 版更變: 添加了*source_address* 参数

3.4 版更變: 删除了 strict 参数，不再支持 HTTP 0.9 风格的“简单响应”。

class http.client.HTTPSConnection(host, port=None, key_file=None, cert_file=None, [timeout, ]source_address=None, *, context=None, check_hostname=None)¶

HTTPConnection 的子类，使用 SSL 与安全服务器进行通信。默认端口为 443。如果指定了 context，它必须为一个描述 SSL 各选项的 ssl.SSLContext 实例。

key_file and cert_file are deprecated, please use ssl.SSLContext.load_cert_chain() instead, or let ssl.create_default_context() select the system’s trusted CA certificates for you. The check_hostname parameter is also deprecated; the ssl.SSLContext.check_hostname attribute of context should be used instead.

请参阅安全考量了解有关最佳实践的更多信息。

3.2 版更變: 添加了 source_address, context 和 check_hostname。

3.2 版更變: 这个类目前会在可能的情况下（即如果 ssl.HAS_SNI 为真值）支持 HTTPS 虚拟主机。

3.4 版更變: 删除了 strict 参数，不再支持 HTTP 0.9 风格的“简单响应”。

3.4.3 版更變: 目前这个类在默认情况下会执行所有必要的证书和主机检查。要回复到先前的非验证行为，可以将 ssl._create_unverified_context() 传递给 context 参数。

class http.client.HTTPResponse(sock, debuglevel=0, method=None, url=None)¶: 在成功连接后返回类的实例，而不是由用户直接实例化。

3.4 版更變: 删除了 strict 参数，不再支持HTTP 0.9 风格的“简单响应”。

下列异常可以适当地被引发:

exception http.client.HTTPException¶: 此模块中其他异常的基类。它是 Exception 的一个子类。

exception http.client.NotConnected¶: HTTPException 的一个子类。

exception http.client.InvalidURL¶: HTTPException 的一个子类，如果给出了一个非数字或为空值的端口就会被引发。

exception http.client.UnknownProtocol¶: HTTPException 的一个子类。

exception http.client.UnknownTransferEncoding¶: HTTPException 的一个子类。

exception http.client.UnimplementedFileMode¶: HTTPException 的一个子类。

exception http.client.IncompleteRead¶: HTTPException 的一个子类。

exception http.client.ImproperConnectionState¶: HTTPException 的一个子类。

exception http.client.CannotSendRequest¶: ImproperConnectionState 的一个子类。

exception http.client.CannotSendHeader¶: ImproperConnectionState 的一个子类。

exception http.client.ResponseNotReady¶: ImproperConnectionState 的一个子类。

exception http.client.BadStatusLine¶: HTTPException 的一个子类。如果服务器反馈了一个我们不理解的 HTTP 状态码就会被引发。

exception http.client.LineTooLong¶: HTTPException 的一个子类。如果在 HTTP 协议中从服务器接收到过长的行就会被引发。

exception http.client.RemoteDisconnected¶: ConnectionResetError 和 BadStatusLine 的一个子类。当尝试读取响应时的结果是未从连接读取到数据时由 HTTPConnection.getresponse() 引发，表明远端已关闭连接。

3.5 版新加入: 在此之前引发的异常为 BadStatusLine('')。

此模块中定义的常量为：

http.client.HTTP_PORT¶: HTTP 协议默认的端口号 (总是 80)。

http.client.HTTPS_PORT¶: HTTPS 协议默认的端口号 (总是 443)。

http.client.responses¶

这个字典把 HTTP 1.1 状态码映射到 W3C 名称。

例如：http.client.responses[http.client.NOT_FOUND] 是 'NOT FOUND （未发现）。

本模块中可用的 HTTP 状态码常量可以参见 HTTP 状态码。

21.12.1. HTTPConnection 对象¶

HTTPConnection 实例拥有以下方法：

HTTPConnection.request(method, url, body=None, headers={})¶

这会使用 HTTP 请求方法 method 和选择器 url 向服务器发送请求。

If body is specified, the specified data is sent after the headers are finished. It may be a string, a bytes-like object, an open file object, or an iterable of bytes-like objects. If body is a string, it is encoded as ISO-8859-1, the default for HTTP. If it is a bytes-like object the bytes are sent as is. If it is a file object, the contents of the file is sent; this file object should support at least the read() method. If the file object has a mode attribute, the data returned by the read() method will be encoded as ISO-8859-1 unless the mode attribute contains the substring b, otherwise the data returned by read() is sent as is. If body is an iterable, the elements of the iterable are sent as is until the iterable is exhausted.

headers 参数应是额外的随请求发送的 HTTP 信息头的字典。

If headers does not contain a Content-Length item, one is added automatically if possible. If body is None, the Content-Length header is set to 0 for methods that expect a body (PUT, POST, and PATCH). If body is a string or bytes object, the Content-Length header is set to its length. If body is a file object and it works to call fstat() on the result of its fileno() method, then the Content-Length header is set to the st_size reported by the fstat call. Otherwise no Content-Length header is added.

3.2 版新加入: body 现在可以是可迭代对象了。

HTTPConnection.getresponse()¶: 应当在发送一个请求从服务器获取响应时被调用。返回一个 HTTPResponse 的实例。

備註

请注意你必须在读取了整个响应之后才能向服务器发送新的请求。

3.5 版更變: 如果引发了 ConnectionError 或其子类， HTTPConnection 对象将在发送新的请求时准备好重新连接。

HTTPConnection.set_debuglevel(level)¶: 设置调试等级。默认的调试等级为 0，意味着不会打印调试输出。任何大于 0 的值将使得所有当前定义的调试输出被打印到 stdout。 debuglevel 会被传给任何新创建的 HTTPResponse 对象。

3.1 版新加入.

HTTPConnection.set_tunnel(host, port=None, headers=None)¶

为 HTTP 连接隧道设置主机和端口。这将允许通过代理服务器运行连接。

host 和 port 参数指明隧道连接的位置（即 CONNECT 请求所包含的地址，而不是代理服务器的地址）。

headers 参数应为一个随 CONNECT 请求发送的额外 HTTP 标头的映射。

例如，要通过一个运行于本机 8080 端口的 HTTPS 代理服务器隧道，我们应当向 HTTPSConnection 构造器传入代理的地址，并将我们最终想要访问的主机地址传给 set_tunnel() 方法:

>>> import http.client
>>> conn = http.client.HTTPSConnection("localhost", 8080)
>>> conn.set_tunnel("www.python.org")
>>> conn.request("HEAD","/index.html")

3.2 版新加入.

HTTPConnection.connect()¶: 当对象被创建后连接到指定的服务器。默认情况下，如果客户端还未建立连接，此函数会在发送请求时自动被调用。

HTTPConnection.close()¶: 关闭到服务器的连接。

作为对使用上述 request() 方法的替代同，你也可以通过使用下面的四个函数，分步骤发送请的请求。

HTTPConnection.putrequest(method, url, skip_host=False, skip_accept_encoding=False)¶: This should be the first call after the connection to the server has been made. It sends a line to the server consisting of the method string, the url string, and the HTTP version (HTTP/1.1). To disable automatic sending of Host: or Accept-Encoding: headers (for example to accept additional content encodings), specify skip_host or skip_accept_encoding with non-False values.

HTTPConnection.putheader(header, argument[, ...])¶: Send an RFC 822-style header to the server. It sends a line to the server consisting of the header, a colon and a space, and the first argument. If more arguments are given, continuation lines are sent, each consisting of a tab and an argument.

HTTPConnection.endheaders(message_body=None)¶: Send a blank line to the server, signalling the end of the headers. The optional message_body argument can be used to pass a message body associated with the request. The message body will be sent in the same packet as the message headers if it is string, otherwise it is sent in a separate packet.

HTTPConnection.send(data)¶: Send data to the server. This should be used directly only after the endheaders() method has been called and before getresponse() is called.

21.12.2. HTTPResponse 对象¶

An HTTPResponse instance wraps the HTTP response from the server. It provides access to the request headers and the entity body. The response is an iterable object and can be used in a with statement.

3.5 版更變: The io.BufferedIOBase interface is now implemented and all of its reader operations are supported.

HTTPResponse.read([amt])¶: Reads and returns the response body, or up to the next amt bytes.

HTTPResponse.readinto(b)¶: Reads up to the next len(b) bytes of the response body into the buffer b. Returns the number of bytes read.

3.3 版新加入.

HTTPResponse.getheader(name, default=None)¶: Return the value of the header name, or default if there is no header matching name. If there is more than one header with the name name, return all of the values joined by 『, 『. If 『default』 is any iterable other than a single string, its elements are similarly returned joined by commas.

HTTPResponse.getheaders()¶: Return a list of (header, value) tuples.

HTTPResponse.fileno()¶: Return the fileno of the underlying socket.

HTTPResponse.msg¶: A http.client.HTTPMessage instance containing the response headers. http.client.HTTPMessage is a subclass of email.message.Message.

HTTPResponse.version¶: HTTP protocol version used by server. 10 for HTTP/1.0, 11 for HTTP/1.1.

HTTPResponse.status¶: 由服务器返回的状态码。

HTTPResponse.reason¶: Reason phrase returned by server.

HTTPResponse.debuglevel¶: A debugging hook. If debuglevel is greater than zero, messages will be printed to stdout as the response is read and parsed.

HTTPResponse.closed¶: Is True if the stream is closed.

21.12.3. 例子¶

Here is an example session that uses the GET method:

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print(r1.status, r1.reason)
200 OK
>>> data1 = r1.read()  # This will return entire content.
>>> # The following example demonstrates reading data in chunks.
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> while not r1.closed:
...     print(r1.read(200))  # 200 bytes
b'<!doctype html>\n<!--[if"...
...
>>> # Example of an invalid request
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

Here is an example session that uses the HEAD method. Note that the HEAD method never returns any data.

>>> import http.client
>>> conn = http.client.HTTPSConnection("www.python.org")
>>> conn.request("HEAD", "/")
>>> res = conn.getresponse()
>>> print(res.status, res.reason)
200 OK
>>> data = res.read()
>>> print(len(data))
0
>>> data == b''
True

Here is an example session that shows how to POST requests:

>>> import http.client, urllib.parse
>>> params = urllib.parse.urlencode({'@number': 12524, '@type': 'issue', '@action': 'show'})
>>> headers = {"Content-type": "application/x-www-form-urlencoded",
...            "Accept": "text/plain"}
>>> conn = http.client.HTTPConnection("bugs.python.org")
>>> conn.request("POST", "", params, headers)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
302 Found
>>> data = response.read()
>>> data
b'Redirecting to <a href="http://bugs.python.org/issue12524">http://bugs.python.org/issue12524</a>'
>>> conn.close()

Client side HTTP PUT requests are very similar to POST requests. The difference lies only the server side where HTTP server will allow resources to be created via PUT request. It should be noted that custom HTTP methods +are also handled in urllib.request.Request by sending the appropriate +method attribute.Here is an example session that shows how to do PUT request using http.client:

>>> # This creates an HTTP message
>>> # with the content of BODY as the enclosed representation
>>> # for the resource http://localhost:8080/file
...
>>> import http.client
>>> BODY = "***filecontents***"
>>> conn = http.client.HTTPConnection("localhost", 8080)
>>> conn.request("PUT", "/file", BODY)
>>> response = conn.getresponse()
>>> print(response.status, response.reason)
200, OK

21.12.4. HTTPMessage Objects¶

An http.client.HTTPMessage instance holds the headers from an HTTP response. It is implemented using the email.message.Message class.

21.12. `http.client` — HTTP 协议客户端¶

21.12.1. HTTPConnection 对象¶

21.12.2. HTTPResponse 对象¶

21.12.3. 例子¶

21.12.4. HTTPMessage Objects¶

Table of Contents

上個主題

下個主題

本頁

21.12. http.client — HTTP 协议客户端¶

21.12.1. HTTPConnection 对象¶

21.12.2. HTTPResponse 对象¶

21.12.3. 例子¶

21.12.4. HTTPMessage Objects¶

21.12. `http.client` — HTTP 协议客户端¶