Skip to main content

tornado.httpclient —异步HTTP客户端

阻塞和非阻塞HTTP客户端接口。

该模块定义由两个实现 simple_httpclientcurl_httpclient 共享的公共接口。应用程序可以直接实例化它们所选择的实现类,或者使用来自该模块的 AsyncHTTPClient 类,其选择可以用 AsyncHTTPClient.configure 方法重写的实现。

默认实现是 simple_httpclient,这预计适合大多数用户的需求。但是,有些应用程序可能希望切换到 curl_httpclient,原因如下:

  • curl_httpclient 具有 simple_httpclient 中未找到的一些功能,包括对HTTP代理的支持和使用指定网络接口的能力。

  • curl_httpclient 更可能与不完全符合HTTP规范的网站兼容,或者使用很少运行的HTTP特性的网站兼容。

  • curl_httpclient 更快。

  • curl_httpclient 是Tornado 2.0之前的默认值。

请注意,如果您使用 curl_httpclient,强烈建议您使用最新版本的 libcurlpycurl。目前,libcurl的最低支持版本为7.21.1,pycurl的最低版本为7.18.2。强烈建议您的 libcurl 安装使用异步DNS解析器(线程或c-ares)构建,否则您可能会遇到请求超时的各种问题(有关更多信息,请参阅curl_httpclient.py中的 http://curl.haxx.se/libcurl/c/curl_easy_setopt.html#CURLOPTCONNECTTIMEOUTMS 和注释)。

要选择 curl_httpclient,在启动时调用 AsyncHTTPClient.configure:

AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")

HTTP客户端接口

class tornado.httpclient.HTTPClient(async_client_class=None, **kwargs)[源代码]

阻止HTTP客户端。

此接口提供方便和测试;大多数运行IOLoop的应用程序都希望使用 AsyncHTTPClient。典型用法如下:

http_client = httpclient.HTTPClient()
try:
    response = http_client.fetch("http://www.google.com/")
    print response.body
except httpclient.HTTPError as e:
    # HTTPError is raised for non-200 responses; the response
    # can be found in e.response.
    print("Error: " + str(e))
except Exception as e:
    # Other errors are possible, such as IOError.
    print("Error: " + str(e))
http_client.close()
close()[源代码]

关闭HTTPClient,释放所使用的任何资源。

fetch(request, **kwargs)[源代码]

执行请求,返回 HTTPResponse

请求可以是字符串URL或 HTTPRequest 对象。如果它是一个字符串,我们使用任何额外的kwargs:HTTPRequest(request, **kwargs) 构造一个 HTTPRequest

如果在提取期间发生错误,我们提出 HTTPError,除非 raise_error 关键字参数设置为False。

class tornado.httpclient.AsyncHTTPClient[源代码]

非阻塞HTTP客户端。

用法示例:

def handle_response(response):
    if response.error:
        print "Error:", response.error
    else:
        print response.body

http_client = AsyncHTTPClient()
http_client.fetch("http://www.google.com/", handle_response)

这个类的构造函数在几个方面是神奇的:它实际上创建了一个特定于实现的子类的实例,实例被重用为一种伪单例(每个 IOLoop 一个)。关键字参数 force_instance=True 可以用于抑制此单例行为。除非使用 force_instance=True,否则除 io_loop 之外的任何参数都不应传递给 AsyncHTTPClient 构造函数。实现子类以及其构造函数的参数可以使用静态方法 configure() 设置

所有 AsyncHTTPClient 实现支持 defaults 关键字参数,可用于设置 HTTPRequest 属性的默认值。例如:

AsyncHTTPClient.configure(
    None, defaults=dict(user_agent="MyUserAgent"))
# or with force_instance:
client = AsyncHTTPClient(force_instance=True,
    defaults=dict(user_agent="MyUserAgent"))

在 4.1 版更改: io_loop 参数已弃用。

close()[源代码]

销毁此HTTP客户端,释放所使用的任何文件描述符。

这种方法是 不需要在正常使用,因为 AsyncHTTPClient 对象被透明地重用。 close() 通常只有当 IOLoop 也被关闭时才需要,或者在创建 AsyncHTTPClient 时使用 force_instance=True 参数。

close() 之后,不能对 AsyncHTTPClient 调用其他方法。

fetch(request, callback=None, raise_error=True, **kwargs)[源代码]

执行请求,异步返回 HTTPResponse

请求可以是字符串URL或 HTTPRequest 对象。如果它是一个字符串,我们使用任何额外的kwargs:HTTPRequest(request, **kwargs) 构造一个 HTTPRequest

此方法返回结果为 HTTPResponseFuture。默认情况下,如果请求返回非200响应代码(如果无法联系服务器,也可能会出现其他错误),Future 将提出 HTTPError。相反,如果 raise_error 设置为False,则将始终返回响应,而不考虑响应代码。

如果给出 callback,它将被 HTTPResponse 调用。在回调接口中,HTTPError 不会自动提升。相反,您必须检查响应的 error 属性或调用其 rethrow 方法。

classmethod configure(impl, **kwargs)[源代码]

配置要使用的 AsyncHTTPClient 子类。

AsyncHTTPClient() 实际上创建了一个子类的实例。可以使用类对象或这种类的完全限定名(或 None 使用默认值 SimpleAsyncHTTPClient)来调用此方法,

如果给出了额外的关键字参数,它们将被传递给创建的每个子类实例的构造函数。关键字参数 max_clients 确定可以在每个 IOLoop 上并行执行的同时 fetch() 操作的最大数量。根据使用的实现类,可能支持其他参数。

例:

AsyncHTTPClient.configure("tornado.curl_httpclient.CurlAsyncHTTPClient")

请求对象

class tornado.httpclient.HTTPRequest(url, method='GET', headers=None, body=None, auth_username=None, auth_password=None, auth_mode=None, connect_timeout=None, request_timeout=None, if_modified_since=None, follow_redirects=None, max_redirects=None, user_agent=None, use_gzip=None, network_interface=None, streaming_callback=None, header_callback=None, prepare_curl_callback=None, proxy_host=None, proxy_port=None, proxy_username=None, proxy_password=None, allow_nonstandard_methods=None, validate_cert=None, ca_certs=None, allow_ipv6=None, client_key=None, client_cert=None, body_producer=None, expect_100_continue=False, decompress_response=None, ssl_options=None)[源代码]

HTTP客户端请求对象。

url 之外的所有参数都是可选的。

参数:
  • url (string) – 要抓取的网址
  • method (string) – HTTP方法,例如“GET”或“POST”
  • headers (HTTPHeaders or dict) – 要传递请求的其他HTTP标头
  • body – HTTP请求体作为字符串(字节或unicode;如果unicode utf-8编码将使用)
  • body_producer – Callable用于延迟/异步请求体。它使用一个参数,write 函数调用,并应返回 Future。它应该在新数据可用时调用写入函数。写函数返回可用于流控制的 Future。可以只指定 bodybody_producer 中的一个。 curl_httpclient 不支持 body_producer。当使用 body_producer 时,建议在标头中传递 Content-Length,否则将使用分块编码,并且许多服务器不支持请求的分块编码。Tornado 4.0中首次出现
  • auth_username (string) – HTTP身份验证的用户名
  • auth_password (string) – HTTP身份验证的密码
  • auth_mode (string) – 认证模式;默认为“基本”。允许值是实现定义的; curl_httpclient 支持“基本”和“摘要”; simple_httpclient 只支持“基本”
  • connect_timeout (float) – 初始连接超时(以秒为单位)
  • request_timeout (float) – 整个请求的超时(以秒为单位)
  • if_modified_since (datetime or float) – If-Modified-Since 头的时间戳
  • follow_redirects (bool) – 应该重定向是自动遵循还是返回3xx响应?
  • max_redirects (int) – follow_redirects 限制
  • user_agent (string) – 要作为 User-Agent 头发送的字符串
  • decompress_response (bool) – 从服务器请求压缩响应,并在下载后解压缩。默认值为True。Tornado 4.0的新功能。
  • use_gzip (bool) – decompress_response 自Tornado 4.0后已弃用的别名。
  • network_interface (string) – 用于请求的网络接口。 curl_httpclient 只;见下面的注释。
  • streaming_callback (callable) – 如果设置,streaming_callback 将在接收到每个数据块时运行,HTTPResponse.bodyHTTPResponse.buffer 在最终响应中将为空。
  • header_callback (callable) – 如果设置,header_callback 将在接收到每个标题行时运行(包括第一行,例如 HTTP/1.0 200 OK\r\n,最后一行只包含 \r\n,所有行都包含尾随的换行符)。 HTTPResponse.headers 将在最终响应中为空。这是与 streaming_callback 结合最有用的,因为它是在请求正在进行时访问标题数据的唯一方法。
  • prepare_curl_callback (callable) – 如果设置,将使用 pycurl.Curl 对象调用,以允许应用程序进行额外的 setopt 调用。
  • proxy_host (string) – HTTP代理主机名。要使用代理,必须设置 proxy_hostproxy_portproxy_usernameproxy_pass 是可选的。代理目前仅支持 curl_httpclient
  • proxy_port (int) – HTTP代理端口
  • proxy_username (string) – HTTP代理用户名
  • proxy_password (string) – HTTP代理密码
  • allow_nonstandard_methods (bool) – 允许 method 参数的未知值?
  • validate_cert (bool) – 对于HTTPS请求,验证服务器的证书?
  • ca_certs (string) – 以PEM格式的CA证书的文件名,或无使用默认值。当与 curl_httpclient 一起使用时,请参见下面的注释。
  • client_key (string) – 客户端SSL密钥的文件名(如果有)。当与 curl_httpclient 一起使用时,请参见下面的注释。
  • client_cert (string) – 客户端SSL证书的文件名(如果有)。当与 curl_httpclient 一起使用时,请参见下面的注释。
  • ssl_options (ssl.SSLContext) – ssl.SSLContext 对象用于 simple_httpclient (不受 curl_httpclient 支持)。覆盖 validate_certca_certsclient_keyclient_cert
  • allow_ipv6 (bool) – 在可用时使用IPv6?默认值为true。
  • expect_100_continue (bool) – 如果为true,则发送 Expect: 100-continue 头并等待继续响应,然后再发送请求主体。仅支持simple_httpclient。

注解

当使用 curl_httpclient 时,某些选项可能会被后续的提取继承,因为 pycurl 不允许它们被干净地重置。这适用于 ca_certsclient_keyclient_certnetwork_interface 参数。如果您使用这些选项,则应在每个请求中传递它们(您不必总是使用相同的值,但是不能将指定这些选项的请求与使用默认值的请求混合使用)。

3.1 新版功能: auth_mode 参数。

4.0 新版功能: body_producerexpect_100_continue 参数。

4.2 新版功能: ssl_options 参数。

响应对象

class tornado.httpclient.HTTPResponse(request, code, headers=None, buffer=None, effective_url=None, error=None, request_time=None, time_info=None, reason=None)[源代码]

HTTP响应对象。

属性:

  • request:HTTPRequest对象

  • code:numeric HTTP状态码,例如200或404

  • reason:描述状态代码的人可读的原因短语

  • headers:tornado.httputil.HTTPHeaders 对象

  • effective_url:跟随任何重定向之后资源的最终位置

  • buffer:响应体的 cStringIO 对象

  • body:响应主体为字符串(根据 self.buffer 的要求创建)

  • error:异常对象(如果有)

  • request_time:请求开始到结束的秒数

  • time_info:来自请求的诊断定时信息的字典。可用数据可能更改,但目前使用 http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html 提供的时间,加上 queue,这是通过在 AsyncHTTPClientmax_clients 设置下等待插槽引入的延迟(如果有的话)。

rethrow()[源代码]

如果请求中存在错误,请提出 HTTPError

例外

exception tornado.httpclient.HTTPError(code, message=None, response=None)[源代码]

未成功的HTTP请求抛出异常。

属性:

  • code - HTTP错误整数错误代码,例如当没有接收到HTTP响应时,例如使用错误代码599。超时。

  • response - HTTPResponse 对象(如果有)。

请注意,如果 follow_redirects 为False,重定向将变为HTTPErrors,您可以查看 error.response.headers['Location'] 以查看重定向的目标。

命令行界面

此模块提供了一个简单的命令行界面,使用Tornado的HTTP客户端提取url。用法示例:

# Fetch the url and print its body
python -m tornado.httpclient http://www.google.com

# Just print the headers
python -m tornado.httpclient --print_headers --print_body=false http://www.google.com

实现

class tornado.simple_httpclient.SimpleAsyncHTTPClient[源代码]

非阻塞HTTP客户端,没有外部依赖。

这个类在Tornado的IOStreams上实现一个HTTP 1.1客户端。在基于curl的AsyncHTTPClient中发现的一些功能尚不支持。特别地,不支持代理,不重新使用连接,并且呼叫者不能选择要使用的网络接口。

initialize(io_loop, max_clients=10, hostname_mapping=None, max_buffer_size=104857600, resolver=None, defaults=None, max_header_size=None, max_body_size=None)[源代码]

创建AsyncHTTPClient。

每个IOLoop只存在一个AsyncHTTPClient实例,以便对挂起的连接数提供限制。 force_instance=True 可以用于抑制这种行为。

注意,由于这种隐式重用,除非使用 force_instance,只有对构造函数的第一次调用实际上使用其参数。建议使用 configure 方法而不是构造函数来确保参数生效。

max_clients 是可以进行的并发请求数;当达到此限制时,其他请求将排队。请注意,在此队列中等待的时间仍然会计入 request_timeout

hostname_mapping 是将主机名映射到IP地址的字典。当修改系统范围的设置(如 /etc/hosts)不可能或不可取时(例如,在单元测试中),它可用于进行本地DNS更改。

max_buffer_size (默认100MB)是可以一次读入内存的字节数。 max_body_size (默认为 max_buffer_size)是客户端将接受的最大响应体。没有 streaming_callback,这两个限制中的较小者适用;与 streaming_callback 只有 max_body_size

在 4.2 版更改: 添加了 max_body_size 参数。

class tornado.curl_httpclient.CurlAsyncHTTPClient(io_loop, max_clients=10, defaults=None)[源代码]

基于 libcurl 的HTTP客户端。