20.7. httplib — HTTP 协议客户端 — Python 文档
20.7. httplib — HTTP 协议客户端
该模块定义了实现 HTTP 和 HTTPS 协议客户端的类。 它通常不直接使用——模块 urllib 使用它来处理使用 HTTP 和 HTTPS 的 URL。
笔记
此模块的公共接口在 Python 2.0 中发生了重大变化。 保留 HTTP 类只是为了向后兼容 1.5.2。 不应在新代码中使用它。 有关用法，请参阅在线文档字符串。
该模块提供以下类：
- class httplib.HTTPConnection(host[, port[, strict[, timeout[, source_address]]]])
HTTPConnection 实例表示与 HTTP 服务器的一个事务。 它应该被实例化并传递一个主机和可选的端口号。 如果未传递端口号，则从主机字符串中提取端口（如果其格式为
host:port），否则使用默认 HTTP 端口 (80)。 当为 true 时，如果状态行无法解析为有效的 HTTP/1.0 或 1.1 状态行，则可选参数 strict（默认为 false 值）会导致引发BadStatusLine. 如果给出了可选的 timeout 参数，阻塞操作（如连接尝试）将在该秒后超时（如果未给出，则使用全局默认超时设置）。 可选的 source_address 参数可以是（主机，端口）的元组，用作建立 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 版中的新功能。
2.6 版更改：添加了 timeout。
2.7 版更改：添加了 source_address。
- class httplib.HTTPSConnection(host[, port[, key_file[, cert_file[, strict[, timeout[, source_address[, context]]]]]]])
HTTPConnection 的子类，它使用 SSL 与安全服务器进行通信。 默认端口为
443。 如果指定了 context，它必须是一个描述各种 SSL 选项的 ssl.SSLContext 实例。key_file 和 cert_file 已弃用，请改用 ssl.SSLContext.load_cert_chain()，或让 ssl.create_default_context() 选择系统的可信 CA 证书。
有关最佳实践的更多信息，请阅读 安全注意事项 。
2.0 版中的新功能。
2.6 版更改：添加了 timeout。
2.7 版更改：添加了 source_address。
在 2.7.9 版更改：添加了 上下文 。
此类现在默认执行所有必要的证书和主机名检查。 要恢复到之前未验证的行为
ssl._create_unverified_context()，可以将其传递给 context 参数。
- class httplib.HTTPResponse(sock, debuglevel=0, strict=0)
成功连接后返回其实例的类。 不是由用户直接实例化。
2.0 版中的新功能。
- class httplib.HTTPMessage
- HTTPMessage 实例用于保存来自 HTTP 响应的标头。 它是使用 mimetools.Message 类实现的，并提供实用函数来处理 HTTP 标头。 它不是由用户直接实例化的。
会酌情引发以下异常：
- exception httplib.HTTPException
此模块中其他异常的基类。 它是
Exception的子类。2.0 版中的新功能。
- exception httplib.NotConnected
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.InvalidURL
HTTPException 的子类，如果给定端口并且为非数字或空则引发。
2.3 版中的新功能。
- exception httplib.UnknownProtocol
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.UnknownTransferEncoding
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.UnimplementedFileMode
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.IncompleteRead
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.ImproperConnectionState
HTTPException 的子类。
2.0 版中的新功能。
- exception httplib.CannotSendRequest
-
2.0 版中的新功能。
- exception httplib.CannotSendHeader
-
2.0 版中的新功能。
- exception httplib.ResponseNotReady
-
2.0 版中的新功能。
- exception httplib.BadStatusLine
HTTPException 的子类。 如果服务器以我们不理解的 HTTP 状态代码响应，则引发。
2.0 版中的新功能。
该模块中定义的常量是：
- httplib.HTTP_PORT
- HTTP 协议的默认端口（始终为
80）。
- httplib.HTTPS_PORT
- HTTPS 协议的默认端口（始终为
443）。
以及整数状态代码的以下常量：
| 持续的 | 价值 | 定义 |
|---|---|---|
CONTINUE
|
100
|
HTTP/1.1, RFC 2616, Section 10.1.1 |
SWITCHING_PROTOCOLS
|
101
|
HTTP/1.1, RFC 2616, Section 10.1.2 |
PROCESSING
|
102
|
WEBDAV，RFC 2518，第 10.1 节 |
OK
|
200
|
HTTP/1.1, RFC 2616, Section 10.2.1 |
CREATED
|
201
|
HTTP/1.1, RFC 2616, Section 10.2.2 |
ACCEPTED
|
202
|
HTTP/1.1, RFC 2616, Section 10.2.3 |
NON_AUTHORITATIVE_INFORMATION
|
203
|
HTTP/1.1, RFC 2616, Section 10.2.4 |
NO_CONTENT
|
204
|
HTTP/1.1, RFC 2616, Section 10.2.5 |
RESET_CONTENT
|
205
|
HTTP/1.1, RFC 2616, Section 10.2.6 |
PARTIAL_CONTENT
|
206
|
HTTP/1.1, RFC 2616, Section 10.2.7 |
MULTI_STATUS
|
207
|
WEBDAV RFC 2518，第 10.2 节 |
IM_USED
|
226
|
HTTP 中的增量编码，RFC 3229，第 10.4.1 节 |
MULTIPLE_CHOICES
|
300
|
HTTP/1.1, RFC 2616, Section 10.3.1 |
MOVED_PERMANENTLY
|
301
|
HTTP/1.1, RFC 2616, Section 10.3.2 |
FOUND
|
302
|
HTTP/1.1, RFC 2616, Section 10.3.3 |
SEE_OTHER
|
303
|
HTTP/1.1, RFC 2616, Section 10.3.4 |
NOT_MODIFIED
|
304
|
HTTP/1.1, RFC 2616, Section 10.3.5 |
USE_PROXY
|
305
|
HTTP/1.1, RFC 2616, Section 10.3.6 |
TEMPORARY_REDIRECT
|
307
|
HTTP/1.1, RFC 2616, Section 10.3.8 |
BAD_REQUEST
|
400
|
HTTP/1.1, RFC 2616, Section 10.4.1 |
UNAUTHORIZED
|
401
|
HTTP/1.1, RFC 2616, Section 10.4.2 |
PAYMENT_REQUIRED
|
402
|
HTTP/1.1, RFC 2616, Section 10.4.3 |
FORBIDDEN
|
403
|
HTTP/1.1, RFC 2616, Section 10.4.4 |
NOT_FOUND
|
404
|
HTTP/1.1, RFC 2616, Section 10.4.5 |
METHOD_NOT_ALLOWED
|
405
|
HTTP/1.1, RFC 2616, Section 10.4.6 |
NOT_ACCEPTABLE
|
406
|
HTTP/1.1, RFC 2616, Section 10.4.7 |
PROXY_AUTHENTICATION_REQUIRED
|
407
|
HTTP/1.1, RFC 2616, Section 10.4.8 |
REQUEST_TIMEOUT
|
408
|
HTTP/1.1, RFC 2616, Section 10.4.9 |
CONFLICT
|
409
|
HTTP/1.1, RFC 2616, Section 10.4.10 |
GONE
|
410
|
HTTP/1.1, RFC 2616, Section 10.4.11 |
LENGTH_REQUIRED
|
411
|
HTTP/1.1, RFC 2616, Section 10.4.12 |
PRECONDITION_FAILED
|
412
|
HTTP/1.1, RFC 2616, Section 10.4.13 |
REQUEST_ENTITY_TOO_LARGE
|
413
|
HTTP/1.1, RFC 2616, Section 10.4.14 |
REQUEST_URI_TOO_LONG
|
414
|
HTTP/1.1, RFC 2616, Section 10.4.15 |
UNSUPPORTED_MEDIA_TYPE
|
415
|
HTTP/1.1, RFC 2616, Section 10.4.16 |
REQUESTED_RANGE_NOT_SATISFIABLE
|
416
|
HTTP/1.1, RFC 2616, Section 10.4.17 |
EXPECTATION_FAILED
|
417
|
HTTP/1.1, RFC 2616, Section 10.4.18 |
UNPROCESSABLE_ENTITY
|
422
|
WEBDAV，RFC 2518，第 10.3 节 |
LOCKED
|
423
|
WEBDAV RFC 2518，第 10.4 节 |
FAILED_DEPENDENCY
|
424
|
WEBDAV，RFC 2518，第 10.5 节 |
UPGRADE_REQUIRED
|
426
|
HTTP 升级到 TLS，RFC 2817，第 6 节 |
INTERNAL_SERVER_ERROR
|
500
|
HTTP/1.1, RFC 2616, Section 10.5.1 |
NOT_IMPLEMENTED
|
501
|
HTTP/1.1, RFC 2616, Section 10.5.2 |
BAD_GATEWAY
|
502
|
HTTP/1.1 RFC 2616, Section 10.5.3 |
SERVICE_UNAVAILABLE
|
503
|
HTTP/1.1, RFC 2616, Section 10.5.4 |
GATEWAY_TIMEOUT
|
504
|
HTTP/1.1 RFC 2616, Section 10.5.5 |
HTTP_VERSION_NOT_SUPPORTED
|
505
|
HTTP/1.1, RFC 2616, Section 10.5.6 |
INSUFFICIENT_STORAGE
|
507
|
WEBDAV，RFC 2518，第 10.6 节 |
NOT_EXTENDED
|
510
|
HTTP 扩展框架，RFC 2774，第 7 节 |
- httplib.responses
该字典将 HTTP 1.1 状态代码映射到 W3C 名称。
示例：
httplib.responses[httplib.NOT_FOUND]为'Not Found'。2.5 版中的新功能。
20.7.1. HTTPConnection 对象
HTTPConnection 实例有以下方法：
- HTTPConnection.request(method, url[, body[, headers]])
这将使用 HTTP 请求方法 method 和选择器 url 向服务器发送请求。 如果存在 body 参数，则它应该是标头完成后要发送的数据字符串。 或者，它可能是一个打开的文件对象，在这种情况下，文件的内容被发送； 这个文件对象应该支持
fileno()和read()方法。 headers 参数应该是与请求一起发送的额外 HTTP 标头的映射。如果在 headers 中没有提供一个
Content-Length头，无论是从str的长度表示形式，或根据报告的磁盘文件大小。 如果 body 是None，则除了需要主体的方法（PUT、POST和PATCH）之外，不会设置标头在这种情况下，它被设置为0。2.6 版更改： body 可以是文件对象。
- HTTPConnection.getresponse()
应在发送请求以从服务器获取响应后调用。 返回一个 HTTPResponse 实例。
笔记
请注意，您必须先阅读整个响应，然后才能向服务器发送新请求。
- HTTPConnection.set_debuglevel(level)
- 设置调试级别（打印的调试输出量）。 默认调试级别为
0，表示不打印调试输出。
- HTTPConnection.set_tunnel(host, port=None, headers=None)
设置 HTTP 连接隧道的主机和端口。 通常在需要通过代理服务器进行 HTTPS 连接时使用。
headers 参数应该是与 CONNECT 请求一起发送的额外 HTTP 标头的映射。
2.7 版中的新功能。
- HTTPConnection.connect()
- 连接到创建对象时指定的服务器。
- HTTPConnection.close()
- 关闭与服务器的连接。
作为使用上述 request() 方法的替代方法，您还可以使用以下四个功能逐步发送您的请求。
- HTTPConnection.putrequest(request, selector[, skip_host[, skip_accept_encoding]])
这应该是连接到服务器后的第一次调用。 它向服务器发送一行由 request 字符串、selector 字符串和 HTTP 版本（
HTTP/1.1）组成的行。 要禁用Host:或Accept-Encoding:标头的自动发送（例如接受其他内容编码），请使用非 False 值指定 skip_host 或 skip_accept_encoding .2.4 版更改：添加了 skip_accept_encoding 参数。
- HTTPConnection.putheader(header, argument[, ...])
- 向服务器发送 RFC 822 样式的标头。 它向服务器发送一行，由标题、冒号和空格以及第一个参数组成。 如果给出更多参数，则发送续行行，每个行由一个制表符和一个参数组成。
- HTTPConnection.endheaders(message_body=None)
向服务器发送一个空行，表示标头结束。 可选的 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()
返回 (header, value) 元组的列表。
2.4 版中的新功能。
- HTTPResponse.fileno()
- 返回底层套接字的
fileno。
- HTTPResponse.msg
- 包含响应头的 mimetools.Message 实例。
- HTTPResponse.version
- 服务器使用的 HTTP 协议版本。 HTTP/1.0 为 10，HTTP/1.1 为 11。
- HTTPResponse.status
- 服务器返回的状态码。
- HTTPResponse.reason
- 服务器返回的原因短语。
20.7.3. 例子
以下是使用 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()客户端 HTTP PUT 请求与 POST 请求非常相似。 区别仅在于服务器端，HTTP 服务器允许通过 PUT 请求创建资源。 这是一个示例会话，显示了如何使用 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
