20.7. httplib-HTTP 协议 Client 端

Note

httplib模块在 Python 3 中已重命名为http.client2to3工具在将源转换为 Python 3 时将自动适应导入。

源代码: Lib/httplib.py


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

See also

推荐使用Requests package作为更高级别的 HTTPClient 端界面。

Note

仅当socket模块使用 SSL 支持编译时,HTTPS 支持才可用。

Note

该模块的公共接口在 Python 2.0 中发生了很大变化。保留HTTP类仅是为了与 1.5.2 向下兼容。不应在新代码中使用它。请参考在线文档字符串以了解用法。

该模块提供以下类:

    • 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 选项。

请阅读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。

2.0 版中的新Function。

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

2.3 版的新Function。

2.0 版中的新Function。

  • exception httplib. UnknownTransferEncoding

2.0 版中的新Function。

  • exception httplib. UnimplementedFileMode

2.0 版中的新Function。

2.0 版中的新Function。

  • exception httplib. ImproperConnectionState

2.0 版中的新Function。

2.0 版中的新Function。

2.0 版中的新Function。

2.0 版中的新Function。

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

2.0 版中的新Function。

此模块中定义的常量为:

  • httplib. HTTP_PORT

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

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

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

ConstantValueDefinition
CONTINUE100HTTP/1.1, RFC 2616 第 10.1.1 节
SWITCHING_PROTOCOLS101HTTP/1.1, RFC 2616,第 10.1.2 节
PROCESSING102WEBDAV, RFC 2518 第 10.1 节
OK200HTTP/1.1, RFC 2616 第 10.2.1 节
CREATED201HTTP/1.1, RFC 2616,第 10.2.2 节
ACCEPTED202HTTP/1.1, RFC 2616 第 10.2.3 节
NON_AUTHORITATIVE_INFORMATION203HTTP/1.1, RFC 2616 第 10.2.4 节
NO_CONTENT204HTTP/1.1, RFC 2616 第 10.2.5 节
RESET_CONTENT205HTTP/1.1, RFC 2616,第 10.2.6 节
PARTIAL_CONTENT206HTTP/1.1, RFC 2616,第 10.2.7 节
MULTI_STATUS207WEBDAV RFC 2518,第 10.2 节
IM_USED226HTTP RFC 3229中的增量编码,第 10.4.1 节
MULTIPLE_CHOICES300HTTP/1.1, RFC 2616 第 10.3.1 节
MOVED_PERMANENTLY301HTTP/1.1, RFC 2616 第 10.3.2 节
FOUND302HTTP/1.1, RFC 2616 第 10.3.3 节
SEE_OTHER303HTTP/1.1, RFC 2616 第 10.3.4 节
NOT_MODIFIED304HTTP/1.1, RFC 2616 第 10.3.5 节
USE_PROXY305HTTP/1.1, RFC 2616 第 10.3.6 节
TEMPORARY_REDIRECT307HTTP/1.1, RFC 2616 第 10.3.8 节
BAD_REQUEST400HTTP/1.1, RFC 2616 第 10.4.1 节
UNAUTHORIZED401HTTP/1.1, RFC 2616 第 10.4.2 节
PAYMENT_REQUIRED402HTTP/1.1, RFC 2616 第 10.4.3 节
FORBIDDEN403HTTP/1.1, RFC 2616 第 10.4.4 节
NOT_FOUND404HTTP/1.1, RFC 2616 第 10.4.5 节
METHOD_NOT_ALLOWED405HTTP/1.1, RFC 2616 第 10.4.6 节
NOT_ACCEPTABLE406HTTP/1.1, RFC 2616 第 10.4.7 节
PROXY_AUTHENTICATION_REQUIRED407HTTP/1.1, RFC 2616 第 10.4.8 节
REQUEST_TIMEOUT408HTTP/1.1, RFC 2616 第 10.4.9 节
CONFLICT409HTTP/1.1, RFC 2616,第 10.4.10 节
GONE410HTTP/1.1, RFC 2616,第 10.4.11 节
LENGTH_REQUIRED411HTTP/1.1, RFC 2616,第 10.4.12 节
PRECONDITION_FAILED412HTTP/1.1, RFC 2616 第 10.4.13 节
REQUEST_ENTITY_TOO_LARGE413HTTP/1.1, RFC 2616 第 10.4.14 节
REQUEST_URI_TOO_LONG414HTTP/1.1, RFC 2616 第 10.4.15 节
UNSUPPORTED_MEDIA_TYPE415HTTP/1.1, RFC 2616,第 10.4.16 节
REQUESTED_RANGE_NOT_SATISFIABLE416HTTP/1.1, RFC 2616,第 10.4.17 节
EXPECTATION_FAILED417HTTP/1.1, RFC 2616,第 10.4.18 节
UNPROCESSABLE_ENTITY422WEBDAV, RFC 2518 第 10.3 节
LOCKED423WEBDAV RFC 2518 第 10.4 节
FAILED_DEPENDENCY424WEBDAV, RFC 2518 第 10.5 节
UPGRADE_REQUIRED426HTTP 升级至 TLS, RFC 2817,第 6 节
INTERNAL_SERVER_ERROR500HTTP/1.1, RFC 2616 第 10.5.1 节
NOT_IMPLEMENTED501HTTP/1.1, RFC 2616,第 10.5.2 节
BAD_GATEWAY502HTTP/1.1 RFC 2616,第 10.5.3 节
SERVICE_UNAVAILABLE503HTTP/1.1, RFC 2616 第 10.5.4 节
GATEWAY_TIMEOUT504HTTP/1.1 RFC 2616 第 10.5.5 节
HTTP_VERSION_NOT_SUPPORTED505HTTP/1.1, RFC 2616 第 10.5.6 节
INSUFFICIENT_STORAGE507WEBDAV, RFC 2518 第 10.6 节
NOT_EXTENDED510HTTP 扩展框架 RFC 2774,第 7 节
  • 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,但期望使用主体(PUTPOSTPATCH)的方法除外,在这种情况下,将其设置为0

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

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

Note

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

  • 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 *)

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

  • 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