tornado.httpclient ---异步HTTP客户端

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

该模块定义了两个实现共享的公共接口， simple_httpclient 和 curl_httpclient . 应用程序可以直接实例化所选的实现类，也可以使用 AsyncHTTPClient 此模块中的类，该模块选择可被重写的实现 AsyncHTTPClient.configure 方法。

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

  • curl_httpclient 在中找不到某些功能 simple_httpclient 包括对HTTP代理的支持以及使用指定网络接口的能力。

  • curl_httpclient 更可能与不完全符合HTTP规范的站点或使用很少执行的HTTP功能的站点兼容。

  • curl_httpclient 更快。

请注意，如果您正在使用 curl_httpclient ，强烈建议您使用最新版本的 libcurl 和 pycurl . 目前支持的libcurl的最低版本是7.22.0，而pycurl的最低版本是7.18.2。强烈建议您 libcurl 安装是使用异步DNS解析程序（线程或C-ARES）构建的，否则您可能会遇到请求超时的各种问题（有关详细信息，请参阅http://curl.haxx.se/libcurl/c/curl-easy-setopt.html curloptconnecttimeoutms和curl-httpclient.py中的注释）。

选择 curl_httpclient ，呼叫 AsyncHTTPClient.configure 启动时：

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

HTTP客户端接口

class tornado.httpclient.HTTPClient(async_client_class: Optional[Type[tornado.httpclient.AsyncHTTPClient]] = None, **kwargs: Any)[源代码]

阻塞的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()

在 5.0 版更改: 由于 asyncio ，无法再使用同步 HTTPClient 而一个 IOLoop 正在运行。使用 AsyncHTTPClient 相反。

close() → None[源代码]

关闭httpclient，释放所有使用的资源。

fetch(request: Union[tornado.httpclient.HTTPRequest, str], **kwargs: Any) → tornado.httpclient.HTTPResponse[源代码]

执行请求，返回 HTTPResponse .

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

如果在提取过程中发生错误，我们将引发 HTTPError 除非 raise_error 关键字参数设置为false。

class tornado.httpclient.AsyncHTTPClient(force_instance: bool = False, **kwargs: Any)[源代码]

非阻塞HTTP客户端。

示例用法：

async def f():
    http_client = AsyncHTTPClient()
    try:
        response = await http_client.fetch("http://www.google.com")
    except Exception as e:
        print("Error: %s" % e)
    else:
        print(response.body)

这个类的构造函数在几个方面都很神奇：它实际上创建了一个特定于实现的子类的实例，并且实例被重用为一种伪单例（每个 IOLoop ）关键字参数 force_instance=True 可用于抑制此单例行为。除非 force_instance=True 不应将任何参数传递给 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"))

在 5.0 版更改: 这个 io_loop 已删除参数（自4.1版以来已弃用）。

close() → None[源代码]

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

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

不能在上调用其他方法 AsyncHTTPClient 之后 close() .

fetch(request: Union[str, HTTPRequest], raise_error: bool = True, **kwargs: Any) → Future[HTTPResponse][源代码]

执行请求，异步返回 HTTPResponse .

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

此方法返回 Future 其结果是 HTTPResponse . 默认情况下， Future 将提高 HTTPError 如果请求返回了非200响应代码（如果无法联系服务器，也可能会引发其他错误）。相反，如果 raise_error 如果设置为false，则无论响应代码如何，都将始终返回响应。

如果A callback 如果给定，则将使用 HTTPResponse . 在回调接口中， HTTPError 不是自动提升的。相反，您必须检查响应 error 属性或调用其 rethrow 方法。

在 6.0 版更改: 这个 callback 参数已删除。使用返回的 Future 相反。

这个 raise_error=False 参数只影响 HTTPError 使用非200响应代码而不是禁止所有错误时引发。

classmethod configure(impl: Union[None, str, Type[tornado.util.Configurable]], **kwargs: Any) → None[源代码]

配置 AsyncHTTPClient 要使用的子类。

AsyncHTTPClient() 实际创建子类的实例。可以使用类对象或此类类的完全限定名（或 None 要使用默认值， SimpleAsyncHTTPClient ）

如果提供了其他关键字参数，它们将传递给每个创建的子类实例的构造函数。关键字参数 max_clients 确定最大同时数 fetch() 可以对每个操作并行执行的操作 IOLoop . 根据所使用的实现类，可能支持其他参数。

例子：：

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

请求对象

class tornado.httpclient.HTTPRequest(url: str, method: str = 'GET', headers: Optional[Union[Dict[str, str], tornado.httputil.HTTPHeaders]] = None, body: Optional[Union[bytes, str]] = None, auth_username: Optional[str] = None, auth_password: Optional[str] = None, auth_mode: Optional[str] = None, connect_timeout: Optional[float] = None, request_timeout: Optional[float] = None, if_modified_since: Optional[Union[float, datetime.datetime]] = None, follow_redirects: Optional[bool] = None, max_redirects: Optional[int] = None, user_agent: Optional[str] = None, use_gzip: Optional[bool] = None, network_interface: Optional[str] = None, streaming_callback: Optional[Callable[[bytes], None]] = None, header_callback: Optional[Callable[[str], None]] = None, prepare_curl_callback: Optional[Callable[[Any], None]] = None, proxy_host: Optional[str] = None, proxy_port: Optional[int] = None, proxy_username: Optional[str] = None, proxy_password: Optional[str] = None, proxy_auth_mode: Optional[str] = None, allow_nonstandard_methods: Optional[bool] = None, validate_cert: Optional[bool] = None, ca_certs: Optional[str] = None, allow_ipv6: Optional[bool] = None, client_key: Optional[str] = None, client_cert: Optional[str] = None, body_producer: Optional[Callable[[Callable[[bytes], None]], Future[None]]] = None, expect_100_continue: bool = False, decompress_response: Optional[bool] = None, ssl_options: Optional[Union[Dict[str, Any], ssl.SSLContext]] = None)[源代码]

HTTP客户端请求对象。

所有参数，除了 url 是可选的。

参数

  • url (str) -- 获取网址

  • method (str) -- HTTP方法，例如“get”或“post”

  • headers (HTTPHeaders or dict) -- 请求时要传递的其他HTTP头

  • body (str or bytes) -- HTTP请求正文作为字符串（字节或Unicode；如果Unicode，则使用UTF-8编码）

  • body_producer (collections.abc.Callable) -- 可调用，用于惰性/异步请求主体。它是通过一个参数调用的，即 write 函数，并应返回 Future . 当新数据可用时，它应该使用新数据调用写函数。write函数返回 Future 可用于流量控制。只有一个 body 和 body_producer 可以指定。 body_producer 上不支持 curl_httpclient . 使用时 body_producer 建议通过 Content-Length 在头中，否则将使用分块编码，许多服务器不支持请求的分块编码。 Tornado 4.0中的新功能

  • auth_username (str) -- HTTP身份验证的用户名

  • auth_password (str) -- HTTP身份验证的密码

  • auth_mode (str) -- 认证模式；默认为“基本”。允许值是实现定义的； curl_httpclient 支持“基本”和“摘要”； simple_httpclient 仅支持“基本”

  • connect_timeout (float) -- 初始连接超时（秒），默认为20秒（0表示无超时）

  • request_timeout (float) -- 整个请求的超时时间（秒），默认为20秒（0表示无超时）

  • if_modified_since (datetime or float) -- 时间戳 If-Modified-Since 页眉

  • follow_redirects (bool) -- 应该自动执行重定向还是返回3xx响应？默认为真。

  • max_redirects (int) -- 极限 follow_redirects 默认值为5。

  • user_agent (str) -- 要作为发送的字符串 User-Agent 页眉

  • decompress_response (bool) -- 从服务器请求压缩响应，并在下载后将其解压缩。默认值为true。 Tornado 4.0中的新功能。

  • use_gzip (bool) -- 的别名已弃用 decompress_response 从 Tornado 4.0开始。

  • network_interface (str) -- 用于请求的网络接口或源IP。见 curl_httpclient 注意如下。

  • streaming_callback (collections.abc.Callable) -- 如果设置， streaming_callback 将与接收到的每个数据块一起运行，并且 HTTPResponse.body 和 HTTPResponse.buffer 将在最终响应中为空。

  • header_callback (collections.abc.Callable) -- 如果设置， header_callback 将在收到每个标题行时运行（包括第一行，例如 HTTP/1.0 200 OK\r\n 最后一行只包含 \r\n . 所有行包括尾随的换行符）。 HTTPResponse.headers 将在最终响应中为空。这与 streaming_callback ，因为这是在请求进行过程中访问头数据的唯一方法。

  • prepare_curl_callback (collections.abc.Callable) -- 如果设置，将使用 pycurl.Curl 对象以允许应用程序添加 setopt 电话。

  • proxy_host (str) -- HTTP代理主机名。使用代理， proxy_host 和 proxy_port 必须设置； proxy_username ， proxy_pass 和 proxy_auth_mode 是可选的。目前仅支持代理 curl_httpclient .

  • proxy_port (int) -- HTTP代理端口

  • proxy_username (str) -- HTTP代理用户名

  • proxy_password (str) -- HTTP代理密码

  • proxy_auth_mode (str) -- HTTP代理身份验证模式；默认为“基本”。支持“基本”和“摘要”

  • allow_nonstandard_methods (bool) -- 允许未知值用于 method 参数？默认值为假。

  • validate_cert (bool) -- 对于HTTPS请求，验证服务器的证书？默认值为true。

  • ca_certs (str) -- PEM格式的CA证书的文件名，或者不使用默认值。与一起使用时，请参见下面的注释 curl_httpclient .

  • client_key (str) -- 客户端SSL密钥的文件名（如果有）。与一起使用时，请参见下面的注释 curl_httpclient .

  • client_cert (str) -- 客户端SSL证书的文件名（如果有）。与一起使用时，请参见下面的注释 curl_httpclient .

  • ssl_options (ssl.SSLContext) -- ssl.SSLContext 用于的对象 simple_httpclient （不支持） curl_httpclient ）重写 validate_cert ， ca_certs ， client_key 和 client_cert .

  • allow_ipv6 (bool) -- 在可用时使用IPv6？默认值为true。

  • expect_100_continue (bool) -- 如果为真，则发送 Expect: 100-continue 在发送请求正文之前，请等待继续响应。仅支持 simple_httpclient .

注解

使用时 curl_httpclient 某些选项可能由后续提取继承，因为 pycurl 不允许它们被完全重置。这适用于 ca_certs ， client_key ， client_cert 和 network_interface 参数。如果使用这些选项，则应在每个请求上传递它们（不必总是使用相同的值，但不能将指定这些选项的请求与使用默认值的请求混合使用）。

3.1 新版功能: 这个 auth_mode 参数。

4.0 新版功能: 这个 body_producer 和 expect_100_continue 参数。

4.2 新版功能: 这个 ssl_options 参数。

4.5 新版功能: 这个 proxy_auth_mode 参数。

响应对象

class tornado.httpclient.HTTPResponse(request: tornado.httpclient.HTTPRequest, code: int, headers: Optional[tornado.httputil.HTTPHeaders] = None, buffer: Optional[_io.BytesIO] = None, effective_url: Optional[str] = None, error: Optional[BaseException] = None, request_time: Optional[float] = None, time_info: Optional[Dict[str, float]] = None, reason: Optional[str] = None, start_time: Optional[float] = None)[源代码]

HTTP响应对象。

属性：

  • request ：httpRequest对象

  • code ：数字HTTP状态代码，例如200或404

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

  • headers ： tornado.httputil.HTTPHeaders 对象

  • effective_url ：执行任何重定向后资源的最终位置

  • buffer ： cStringIO 响应主体的对象

  • body ：响应正文为字节（按需创建自 self.buffer ）

  • error ：异常对象（如果有）

  • request_time ：从请求开始到完成的秒数。包括从DNS解析到接收最后一字节数据的所有网络操作。不包括在队列中花费的时间（由于 max_clients 选择权。如果遵循重定向，则只包括最终请求。

  • start_time ：HTTP操作开始的时间，基于 time.time （不是使用的单调时钟 IOLoop.time ）可能是 None 如果请求在队列中超时。

  • time_info ：来自请求的诊断定时信息字典。可用数据可能会发生变化，但目前使用http://curl.haxx.se/libcurl/c/curl_easy_getinfo.html提供的计时，以及 queue ，这是等待下一个插槽所引起的延迟（如果有）。 AsyncHTTPClient 的 max_clients 设置。

5.1 新版功能: 增加了 start_time 属性。

在 5.1 版更改: 这个 request_time 属性以前包括在队列中花费的时间 simple_httpclient ，但不在 curl_httpclient . 现在，两种实现都排除了排队时间。 request_time 现在更准确地 curl_httpclient 因为它使用了一个单调的时钟。

rethrow() → None[源代码]

如果请求出错，则引发 HTTPError .

例外情况

exception tornado.httpclient.HTTPClientError(code: int, message: Optional[str] = None, response: Optional[tornado.httpclient.HTTPResponse] = None)[源代码]

对未成功的HTTP请求引发异常。

属性：

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

  • response - HTTPResponse 对象，如果有的话。

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

在 5.1 版更改: 更名为 HTTPError 到 HTTPClientError 以避免与 tornado.web.HTTPError . 名字 tornado.httpclient.HTTPError 保留为别名。

exception tornado.httpclient.HTTPError

Alias HTTPClientError .

命令行界面

该模块提供了一个简单的命令行接口，可以使用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(force_instance: bool = False, **kwargs: Any)[源代码]

无外部依赖关系的非阻塞HTTP客户端。

这个类在Tornado的iostreams之上实现了一个HTTP1.1客户端。还不支持在基于curl的AsynchTtpClient中找到的某些功能。特别是，代理不受支持，连接不被重用，调用方无法选择要使用的网络接口。

initialize(max_clients: int = 10, hostname_mapping: Optional[Dict[str, str]] = None, max_buffer_size: int = 104857600, resolver: Optional[tornado.netutil.Resolver] = None, defaults: Optional[Dict[str, Any]] = None, max_header_size: Optional[int] = None, max_body_size: Optional[int] = None) → None[源代码]

创建AsynchHttpClient。

每个IOLoop只存在一个AsynchHttpClient实例，以限制挂起的连接数。 force_instance=True 可用于抑制此行为。

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

max_clients 是可以进行的并发请求数；达到此限制时，将对其他请求进行排队。请注意，在此队列中等待的时间仍然与 request_timeout .

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

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(max_clients=10, defaults=None)

libcurl -基于HTTP客户端。

示例代码