20.7. httplib-HTTP 协议 Client 端

源代码： Lib/httplib.py

---

该模块定义了实现 HTTP 和 HTTPS 协议 Client 端的类。通常不直接使用它-模块urllib使用它来处理使用 HTTP 和 HTTPS 的 URL。

该模块提供以下类：

• • class * httplib. HTTPConnection(* host * [，* port * [，* strict * [，* timeout * [，* source_address *]]]])
  • HTTPConnection实例代表与 HTTP 服务器的一笔 Transaction。应该实例化它，并为其传递主机和可选端口号。如果未传递任何端口号，则如果端口的格式为host:port，则将从主机字符串中提取该端口，否则将使用默认的 HTTP 端口(80)。为 true 时，如果无法将状态行解析为有效的 HTTP/1.0 或 1.1 状态行，则可选参数* strict (默认为 false 值)将引发BadStatusLine。如果给出了可选的 timeout 参数，则阻塞操作(如连接try)将在几秒钟后超时(如果未给出，则使用全局默认超时设置)。可选的 source_address *参数可以是(主机，端口)的 Tuples，用作构建 HTTP 连接的源地址。

例如，以下调用所有创建在相同主机和端口上连接到服务器的实例：

>>> h1 = httplib.HTTPConnection('www.cwi.nl')
>>> h2 = httplib.HTTPConnection('www.cwi.nl:80')
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80)
>>> h3 = httplib.HTTPConnection('www.cwi.nl', 80, timeout=10)

2.0 版中的新Function。

在 2.6 版中进行了更改：添加了“超时”。

在 2.7 版中进行了更改：添加了* source_address *。

• • class * httplib. HTTPSConnection(* host * [，* port * [，* key_file * [，* cert_file * [，* strict * [，* timeout * [，* source_address * [，* context *]]]]]]] ])
  • HTTPConnection的子类，它使用 SSL 与安全服务器进行通信。默认端口为443。如果指定了* context *，则它必须是ssl.SSLContext实例，用于描述各种 SSL 选项。

• key_file 和 cert_file *已过时，请改为使用ssl.SSLContext.load_cert_chain()，或让ssl.create_default_context()为您选择系统的受信任 CA 证书。

请阅读Security considerations以获取有关最佳做法的更多信息。

2.0 版中的新Function。

在 2.6 版中进行了更改：添加了“超时”。

在 2.7 版中进行了更改：添加了* source_address *。

在版本 2.7.9 中更改：添加了* context *。

现在，此类默认情况下执行所有必要的证书和主机名检查。要恢复为先前未验证的行为ssl._create_unverified_context()，可以将其传递给* context *参数。

• • class * httplib. HTTPResponse(* sock ， debuglevel = 0 ， strict = 0 *)
  • 成功连接后返回其实例的类。不能直接由用户实例化。

2.0 版中的新Function。

• 类别 httplib. HTTPMessage
  • HTTPMessage实例用于保存 HTTP 响应中的 Headers。它使用mimetools.Message类实现，并提供 Util Function来处理 HTTPHeaders。它不是由用户直接实例化的。

适当地提出了以下异常：

• exception httplib. HTTPException
  • 此模块中其他异常的 Base Class。它是Exception的子类。

2.0 版中的新Function。

• exception httplib. NotConnected
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. InvalidURL
  • HTTPException的子类，如果提供了端口，则为非数字或为空，则引发。

2.3 版的新Function。

• exception httplib. UnknownProtocol
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. UnknownTransferEncoding
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. UnimplementedFileMode
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. IncompleteRead
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. ImproperConnectionState
  • HTTPException的子类。

2.0 版中的新Function。

• exception httplib. CannotSendRequest
  • ImproperConnectionState的子类。

2.0 版中的新Function。

• exception httplib. CannotSendHeader
  • ImproperConnectionState的子类。

2.0 版中的新Function。

• exception httplib. ResponseNotReady
  • ImproperConnectionState的子类。

2.0 版中的新Function。

• exception httplib. BadStatusLine
  • HTTPException的子类。如果服务器使用我们不理解的 HTTP 状态代码响应，则引发。

2.0 版中的新Function。

此模块中定义的常量为：

• httplib. HTTP_PORT

  • HTTP 协议的默认端口(始终为80)。

• httplib. HTTPS_PORT

  • HTTPS 协议的默认端口(始终为443)。

以及整数状态码的以下常量：

• httplib. responses
  • 该词典将 HTTP 1.1 状态代码 Map 到 W3C 名称。

示例：httplib.responses[httplib.NOT_FOUND]是'Not Found'。

2.5 版的新Function。

20.7.1. HTTPConnection 对象

HTTPConnection个实例具有以下方法：

• HTTPConnection. request(方法，* url * [，* body * [，* headers *]])
  • 这将使用 HTTP 请求方法* method 和 selectors url 向服务器发送请求。如果存在 body *参数，则应为 Headers 完成后要发送的数据字符串。或者，它可以是一个打开的文件对象，在这种情况下，文件的内容将被发送。此文件对象应支持fileno()和read()方法。 * headers *参数应该是与请求一起发送的额外 HTTPHeaders 的 Map。

如果* headers 中未提供一个，则可以根据str表示形式的长度或磁盘上报告的文件大小确定主体的长度，从而为所有方法自动添加Content-Length头。如果 body *为None，则不设置 Headers，但期望使用主体(PUT，POST和PATCH)的方法除外，在这种情况下，将其设置为0。

在 2.6 版中更改：* body *可以是文件对象。

• HTTPConnection. getresponse ( )
  • 发送请求以从服务器获取响应后应调用该方法。返回一个HTTPResponse实例。

• HTTPConnection. set_debuglevel(级别)

  • 设置调试级别(打印的调试输出量)。缺省调试级别是0，这意味着没有打印调试输出。

• HTTPConnection. set_tunnel(* host ， port = None ， headers = None *)

  • 设置 HTTP 连接隧道的主机和端口。通常在需要pass代理服务器进行 HTTPS 连接时使用。

headers 参数应该是要与 CONNECT 请求一起发送的额外 HTTPHeaders 的 Map。

2.7 版的新Function。

• HTTPConnection. connect ( )

  • 连接到创建对象时指定的服务器。

• HTTPConnection. close ( )

  • 关闭与服务器的连接。

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

• HTTPConnection. putrequest(* request ， selector * [，* skip_host * [，* skip_accept_encoding *]])
  • 这应该是与服务器构建连接后的第一个呼叫。它向服务器发送一条由* request 字符串， selector 字符串和 HTTP 版本(HTTP/1.1)组成的行。要禁用自动发送Host:或Accept-Encoding:Headers(例如，接受其他内容编码)，请使用非 False 值指定 skip_host 或 skip_accept_encoding *。

在版本 2.4 中更改：添加了* skip_accept_encoding *参数。

• HTTPConnection. putheader(* header ， argument * [，* ... *])

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

• HTTPConnection. endheaders(* message_body = None *)

  • 向服务器发送空白行，以指示 Headers 的末尾。可选的* message_body *参数可用于传递与请求关联的消息正文。如果是字符串，则消息正文将与消息头在同一包中发送，否则，将在单独的包中发送。

在 2.7 版中进行了更改：添加了* message_body *。

• HTTPConnection. send(* data *)
  • 将数据发送到服务器。仅应在调用endheaders()方法之后和调用getresponse()之前直接使用此方法。

20.7.2. HTTPResponse 对象

HTTPResponse个实例具有以下方法和属性：

• HTTPResponse. read([* amt *])

  • 读取并返回响应正文，或直至下一个* amt *字节。

• HTTPResponse. getheader(* name * [，* default *])

  • 获取标题* name 的内容，如果没有匹配的标题，则获取 default *。

• HTTPResponse. getheaders ( )

  • 返回(头，值)Tuples 的列表。

2.4 版的新Function。

• HTTPResponse. fileno ( )

  • 返回基础套接字的fileno。

• HTTPResponse. msg

  • 包含响应 Headers 的mimetools.Message实例。

• HTTPResponse. version

  • 服务器使用的 HTTP 协议版本。 HTTP/1.0 为 10，HTTP/1.1 为 11.

• HTTPResponse. status

  • 服务器返回的状态码。

• HTTPResponse. reason

  • 服务器返回的原因短语。

20.7.3. Examples

这是使用GET方法的示例会话：

>>> import httplib
>>> conn = httplib.HTTPSConnection("www.python.org")
>>> conn.request("GET", "/")
>>> r1 = conn.getresponse()
>>> print r1.status, r1.reason
200 OK
>>> data1 = r1.read()
>>> conn.request("GET", "/")
>>> r2 = conn.getresponse()
>>> print r2.status, r2.reason
404 Not Found
>>> data2 = r2.read()
>>> conn.close()

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

>>> import httplib
>>> conn = httplib.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 == ''
True

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

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

Client 端HTTP PUT请求与POST请求非常相似。区别仅在于服务器端，HTTP 服务器将允许passPUT请求创建资源。这是一个示例会话，显示了如何使用 httplib 执行PUT请求：

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