http.client --- HTTP协议客户端

注解HTTPS 支持仅在 Python 启动了 SSL 支持进行编译时（通过 ssl 模块）可用。

该模块支持以下类：

class http.client.HTTPConnection（host，port = None，[ timeout，] source_address = None，blocksize = 8192 ）

HTTPConnection 的实例代表与 HTTP 的一个连接事务。 它的实例化应当传入一个主机和可选的端口号。 如果没有传入端口号，如果主机字符串的形式为 主机:端口 则会从中提取端口，否则将使用默认的 HTTP 端口（80）。 如果给出了可选的 timeout 参数，则阻塞操作（例如连接尝试）将在指定的秒数之后超时（如果未给出，则使用全局默认超时设置）。 可选的 source_address 参数可以为一个 (主机, 端口) 元组，用作进行 HTTP 连接的源地址。 可选的 blocksize 参数可以字节为单位设置缓冲区的大小，用来发送文件类消息体。

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

>>>

>>> 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 风格的“简单响应”。

在 3.7 版更改: 添加了 blocksize 参数。

class http.client.HTTPSConnection（host，port = None，key_file = None，cert_file = None，[ timeout，] source_address = None，*，context = None，check_hostname = None，blocksize = 8192 ）

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

请参阅 Security considerations 了解有关最佳实践的更多信息。

在 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 参数。

3.6 版后已移除: key_file 和 cert_file 已弃用并转而推荐 context。 请改用 ssl.SSLContext.load_cert_chain()或让 ssl.create_default_context() 为你选择系统所信任的 CA 证书。

check_hostname 参数也已弃用；应当改用 context 的 ssl.SSLContext.check_hostname 属性。

class http.client.HTTPResponse（sock，debuglevel = 0，method = None，url = None ）

在成功连接后返回类的实例，而不是由用户直接实例化。

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

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

异常http.client.HTTPException

此模块中其他异常的基类。 它是 Exception 的一个子类。

异常http.client.NotConnected

HTTPException 的一个子类。

异常http.client.InvalidURL

HTTPException 的一个子类，如果给出了一个非数字或为空值的端口就会被引发。

异常http.client.UnknownProtocol

HTTPException 的一个子类。

异常http.client.UnknownTransferEncoding

HTTPException 的一个子类。

异常http.client.UnimplementedFileMode

HTTPException 的一个子类。

异常http.client.IncompleteRead

HTTPException 的一个子类。

异常http.client.ImproperConnectionState

HTTPException 的一个子类。

异常http.client.CannotSendRequest

ImproperConnectionState 的一个子类。

异常http.client.CannotSendHeader

ImproperConnectionState 的一个子类。

异常http.client.ResponseNotReady

ImproperConnectionState 的一个子类。

异常http.client.BadStatusLine

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

异常http.client.LineTooLong

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

异常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状态码。

HTTP连接对象

HTTPConnection 实例有以下方法：

HTTPConnection.request（method，url，body = None，headers = {}，*，encode_chunked = False ）

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

如果指定了body，则在标题完成后发送指定的数据。它可以是str，一个类字节对象，一个开放的文件对象，或一个可迭代bytes。如果body 是字符串，则编码为ISO-8859-1，HTTP的默认值。如果它是类似字节的对象，则按原样发送字节。如果是文件对象，则发送文件内容; 此文件对象应至少支持该read()方法。如果文件对象是实例io.TextIOBase，则该read() 方法返回的数据将被编码为ISO-8859-1，否则返回的数据 read()将按原样发送。如果身体 是可迭代的，迭代的元素按原样发送，直到迭代耗尽为止。

该头参数应该是额外的HTTP标头的映射与发送请求。

如果标题既不包含Content-Length也不包含Transfer-Encoding，但是有一个请求正文，则会自动添加其中一个标题字段。如果 体是None，在Content-Length头被设置为0对于期望的本体方法（PUT，POST，和PATCH）。如果 body是字符串或类似字节的对象（也不是 文件），则Content-Length标头设置为其长度。任何其他类型的主体（通常是文件和可迭代）将进行块编码，并且将自动设置Transfer-Encoding标头而不是Content-Length。

只有在头中指定了Transfer-Encoding时，encode_chunked参数才有意义。如果encode_chunked就是，在HttpConnection的对象假定所有编码通过调用代码来处理。如果是，则正文将进行块编码。FalseTrue

注解

 

已将分块传输编码添加到HTTP协议版本1.1中。除非已知HTTP服务器处理HTTP 1.1，否则调用者必须指定Content-Length，或者必须传递一个 str或类似字节的对象，该对象也不是文件作为正文表示。

3.2 新版功能: body can now be an iterable.

在3.6版更改：如果在标题中既未设置Content-Length也未设置Transfer-Encoding ，则文件和可迭代正文对象现在都是块编码的。该encode_chunked加入争论。不尝试确定文件对象的Content-Length。

HTTPConnection.getresponse()

应在发送请求以从服务器获取响应后调用。返回一个HTTPResponse实例。

注解

 

请注意，您必须先读取整个响应，然后才能向服务器发送新请求。

在3.5版更改：如果ConnectionError引发了一个或一个子类，则在HTTPConnection发送新请求时，该 对象将准备好重新连接。

HTTPConnection.set_debuglevel（级别）

设置调试级别。默认调试级别是0，表示不打印任何调试输出。任何大于的值0都会导致所有当前定义的调试输出打印到stdout。将debuglevel 被传递到任何新HTTPResponse创建的对象。

3.1 新版功能.

HTTPConnection.set_tunnel（主机，端口=无，标头=无）

设置HTTP Connect Tunneling的主机和端口。这允许通过代理服务器运行连接。

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()

关闭与服务器的连接。

HTTPConnection.blocksize

用于发送类文件消息体的缓冲区大小（以字节为单位）。

3.7 新版功能.

作为使用上述request()方法的替代方法，您还可以使用以下四个功能逐步发送请求。

HTTPConnection.putrequest（方法，url，skip_host = False，skip_accept_encoding = False ）

这应该是与服务器建立连接后的第一次调用。它向服务器发送一行，包括方法字符串，url字符串和HTTP版本（HTTP/1.1）。要禁用自动发送Host:或Accept-Encoding:标头（例如接受其他内容编码），请 使用非假值指定skip_host或skip_accept_encoding。

HTTPConnection.putheader（标题，参数[，... ] ）

发送一个 RFC 822样式的服务器头。它向服务器发送一行，包括标题，冒号和空格，以及第一个参数。如果给出更多参数，则发送连续行，每个连续行由制表符和参数组成。

HTTPConnection.endheaders（message_body = None，*，encode_chunked = False ）

向服务器发送一个空行，表示标题的结尾。可选的message_body参数可用于传递与请求关联的消息体。

如果encode_chunked是True，每次迭代的结果 MESSAGE_BODY将块编码为在规定RFC 7230，第3.3.1节。数据的编码方式取决于 message_body的类型 。如果 message_body实现缓冲区接口，则编码将导致单个块。如果 MESSAGE_BODY是collections.abc.Iterable，每次迭代 MESSAGE_BODY将导致一大块。如果message_body是 文件对象，则每次调用都.read()将产生一个块。该方法在 message_body之后立即自动发信号通知块编码数据的结束。

注解

 

由于分块编码规范，块编码器将忽略由迭代器主体产生的空块。这是为了避免由于编码格式错误而导致目标服务器提前读取请求。

3.6新版功能：分块编码支持。该encode_chunked加入参数。

HTTPConnection.send（数据）

将数据发送到服务器。只有在endheaders()调用方法之后且调用之前，才应该直接使用 getresponse()它。

HTTPResponse对象

一个HTTPResponse实例包含从服务器的HTTP响应。它提供对请求标头和实体主体的访问。响应是一个可迭代的对象，可以在with语句中使用。

在3.5版更改：该io.BufferedIOBase接口现在已经实现和所有的读者操作的支持。

HTTPResponse.read（[ amt ] ）

读取并返回响应正文，或者返回下一个amt字节。

HTTPResponse.readinto（b ）

将响应主体的下一个len（b）字节读入缓冲区b。返回读取的字节数。

3.3 新版功能.

HTTPResponse.getheader（名称，默认=无）

返回标头名称的值，如果没有标头匹配名称，则返回默认值。如果有多个带名称name的标头，则返回由'，'连接的所有值。如果'default'是除单个字符串以外的任何可迭代，则其元素类似地以逗号连接返回。

HTTPResponse.getheaders()

返回（标题，值）元组的列表。

HTTPResponse.fileno()

返回fileno底层套接字。

HTTPResponse.msg

甲http.client.HTTPMessage包含响应标头实例。 http.client.HTTPMessage是。的子类email.message.Message。

HTTPResponse.version

服务器使用的HTTP协议版本。10表示HTTP / 1.0,11表示HTTP / 1.1。

HTTPResponse.status

服务器返回的状态代码。

HTTPResponse.reason

服务器返回的原因短语。

HTTPResponse.debuglevel

一个调试钩子。如果debuglevel大于零，则在读取和解析响应时将消息打印到stdout。

HTTPResponse.closed

是True，如果流被关闭。

示例

以下是使用该GET方法的示例会话：

>>>

>>> 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 = http.client.HTTPSConnection("docs.python.org")
>>> conn.request("GET", "/parrot.spam")
>>> r2 = conn.getresponse()
>>> print(r2.status, r2.reason)
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

这是一个使用该HEAD方法的示例会话。请注意，该 HEAD方法永远不会返回任何数据。

>>>

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

这是一个示例会话，显示如何POST请求：

>>>

>>> 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()

客户端请求与请求非常相似。不同之处仅在于服务器端，HTTP服务器将允许通过请求创建资源。应该注意的是，自定义HTTP方法+也通过发送适当的+方法属性来处理。这是一个示例会话，显示如何 使用http.client 执行请求：HTTP PUTPOSTPUTurllib.request.RequestPUT

>>>

>>> # 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

HTTPMessage对象

一个http.client.HTTPMessage实例包含从HTTP响应的报头。它是使用email.message.Message该类实现的。