21.12. http.client
— HTTP 协议客户端¶
源代码: Lib/http/client.py
这个模块定义了实现 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 formhost: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 letssl.create_default_context()
select the system’s trusted CA certificates for you. The check_hostname parameter is also deprecated; thessl.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.
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 amode
attribute, the data returned by theread()
method will be encoded as ISO-8859-1 unless themode
attribute contains the substringb
, otherwise the data returned byread()
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 to0
for methods that expect a body (PUT
,POST
, andPATCH
). 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 callfstat()
on the result of itsfileno()
method, then the Content-Length header is set to thest_size
reported by thefstat
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 ofHost:
orAccept-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 beforegetresponse()
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 ofemail.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.