tornado.httpclient — Asynchronous HTTP client

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

该模块定义了两个实现共享的通用接口, simple_httpclientcurl_httpclient . 应用程序可以直接实例化其选择的实现类,也可以使用此模块中的AsyncHTTPClient类,该类选择可以用AsyncHTTPClient.configure方法覆盖的实现.

默认实现为simple_httpclient ,这有望满足大多数用户的需求. 但是, curl_httpclient以下原因,某些应用程序可能希望切换到curl_httpclient

  • curl_httpclient有一些功能没有发现simple_httpclient ,包括HTTP代理支持和使用指定的网络接口的能力.

  • curl_httpclient is more likely to be compatible with sites that are not-quite-compliant with the HTTP spec, or sites that use little-exercised features of HTTP.

  • curl_httpclient更快.

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

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

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

HTTP client interfaces

class tornado.httpclient.HTTPClient(async_client_class: Type[AsyncHTTPClient] = None, **kwargs)[source]

阻塞的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[source]

关闭HTTPClient,释放所有使用的资源.

fetch(request: Union[HTTPRequest, str], **kwargs) → tornado.httpclient.HTTPResponse[source]

执行一个请求,返回一个HTTPResponse .

该请求可以是字符串URL或HTTPRequest对象. 如果它是字符串,则使用任何其他kwargs构造一个HTTPRequestHTTPRequest(request, **kwargs)

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

class tornado.httpclient.AsyncHTTPClient[source]

非阻塞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中更改: The io_loop argument (deprecated since version 4.1) has been removed.

close() → None[source]

销毁此HTTP客户端,释放所有使用的文件描述符.

由于透明地重用了AsyncHTTPClient对象, 因此在正常使用中不需要此方法. close()通常仅需要要么当IOLoop也被关闭,或者force_instance=True创建当使用参数AsyncHTTPClient .

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

fetch(request: Union[str, HTTPRequest], raise_error: bool = True, **kwargs) → Awaitable[tornado.httpclient.HTTPResponse][source]

执行一个请求,异步返回一个HTTPResponse .

该请求可以是字符串URL或HTTPRequest对象. 如果它是字符串,则使用任何其他kwargs构造一个HTTPRequestHTTPRequest(request, **kwargs)

此方法返回一个Future其结果是HTTPResponse . 默认情况下,如果请求返回非200响应代码,则Future将引发HTTPError (如果无法联系服务器,则也可能引发其他错误). 相反,如果将raise_error设置为False,则无论响应代码如何,都将始终返回响应.

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

在版本6.0中更改: callback参数已删除. 请改用返回的Future .

仅当使用非200响应代码时, raise_error=False参数才会影响引发的HTTPError ,而不是抑制所有错误.

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

配置要使用的AsyncHTTPClient子类.

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

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

Example:

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

Request objects

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

HTTP客户端请求对象.

url外的所有参数都是可选的.

Parameters
  • urlstr )–要获取的URL

  • 方法str )– HTTP方法,例如" GET"或" POST"

  • 标头HTTPHeadersdict )–传递请求的其他HTTP标头

  • body – HTTP请求正文,为字符串(字节或unicode;如果为unicode,则将使用utf-8编码)

  • body_producer –可调用的,用于延迟/异步请求正文. 它由一个参数和一个write函数调用,并应返回Future . 当新数据可用时,应使用新数据调用write函数. 写函数返回一个可以用于流控制的Future . 只能指定bodybody_producer之一. body_producer不支持curl_httpclient . 使用body_producer ,建议在标头中传递Content-Length ,否则将使用分块编码,并且许多服务器不支持对请求的分块编码. Tornado 4.0的新功能

  • auth_usernamestr )– HTTP认证的用户名

  • auth_passwordstr )– HTTP验证的密码

  • auth_modestr )–身份验证模式; 默认为"基本". 允许值是实现定义的; curl_httpclient支持"基本"和"摘要"; simple_httpclient仅支持"基本"

  • connect_timeout (float) – Timeout for initial connection in seconds, default 20 seconds

  • request_timeoutfloat )–整个请求的超时时间(以秒为单位),默认为20秒

  • if_modified_sincedatetimefloat )– If-Modified-Since标头的时间戳

  • follow_redirectsbool )–应该自动遵循重定向还是返回3xx响应? 默认为True.

  • max_redirects (int) – Limit for follow_redirects, default 5.

  • user_agentstr )–要作为User-Agent标头发送的字符串

  • decompress_responsebool )–从服务器请求压缩的响应,并在下载后将其解压缩. 默认值为True. 龙卷风4.0的新功能.

  • use_gzipbool )–自Tornado 4.0起不推荐使用decompress_response别名.

  • network_interfacestr )–用于请求的网络接口或源IP. 请参阅下面的curl_httpclient注释.

  • streaming_callbackcollections.abc.Callable )–如果设置, streaming_callback将在接收到每个数据块时运行,并且HTTPResponse.bodyHTTPResponse.buffer在最终响应中将为空.

  • header_callbackcollections.abc.Callable )–如果设置,则header_callback将在收到的每个标题行(包括第一行,例如HTTP/1.0 200 OK\r\n ,最后一行仅包含\r\n .所有行均包含尾随换行符). HTTPResponse.headers在最终响应中将为空. 与streaming_callback结合使用时,这是最有用的,因为这是在请求进行过程中访问标头数据的唯一方法.

  • prepare_curl_callbackcollections.abc.Callable )–如果设置,将使用pycurl.Curl对象调用,以允许应用程序进行其他setopt调用.

  • proxy_hoststr )– HTTP代理主机名. 要使用代理,必须设置proxy_hostproxy_port . proxy_usernameproxy_passproxy_auth_mode是可选的. 目前仅curl_httpclient支持代理.

  • proxy_portint )– HTTP代理端口

  • proxy_usernamestr )– HTTP代理用户名

  • proxy_passwordstr )– HTTP代理密码

  • proxy_auth_modestr )– HTTP代理身份验证模式; 默认为"基本". 支持"基本"和"摘要"

  • allow_nonstandard_methods (bool) – Allow unknown values for method argument? Default is False.

  • validate_certbool )–对于HTTPS请求,请验证服务器的证书? 默认值为True.

  • ca_certsstr )– PEM格式的CA证书的文件名,或者为None以使用默认值. 与curl_httpclient使用时,请参见下面的curl_httpclient .

  • client_keystr )–客户端SSL密钥的文件名(如果有). 与curl_httpclient使用时,请参见下面的curl_httpclient .

  • client_certstr )–客户端SSL证书的文件名(如果有). 与curl_httpclient使用时,请参见下面的curl_httpclient .

  • ssl_options( ssl.SSLContext ) - ssl.SSLContext对象用于在使用中simple_httpclient (由不受支持curl_httpclient ). 覆盖validate_certca_certsclient_keyclient_cert .

  • allow_ipv6bool )–在可用时使用IPv6吗? 默认值为True.

  • Expect_100_continuebool )–如果为true,则发送Expect: 100-continue标头,并在发送请求正文之前等待继续响应. 仅受simple_httpclient支持.

Note

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

3.1版的新功能: The auth_mode argument.

版本4.0中的新功能: The body_producer and expect_100_continue arguments.

New in version 4.2: The ssl_options argument.

4.5版的新功能: The proxy_auth_mode argument.

Response objects

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

HTTP响应对象.

Attributes:

  • request :HTTPRequest对象

  • code :数字HTTP状态代码,例如200或404

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

  • headers: tornado.httputil.HTTPHeaders object

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

  • buffer :响应主体的cStringIO对象

  • body :响应主体(以字节为单位)(根据需要从self.buffer创建)

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

  • request_time :从请求开始到完成的秒数. 包括从DNS解析到接收数据的最后一个字节的所有网络操作. 不包括花费在队列中的时间(由于max_clients选项). 如果遵循重定向,则仅包含最终请求.

  • start_time :基于time.time (不是IOLoop.time使用的单调时钟)的HTTP操作开始的时间. 如果请求在队列中超时,则可能为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_httpclientcurl_httpclient . 现在,这两种实现方式都排除了排队时间. 现在, curl_httpclient request_time更准确,因为它在可用时使用单调时钟.

rethrow() → None[source]

如果请求有错误,请引发HTTPError .

Exceptions

exception tornado.httpclient.HTTPClientError(code: int, message: str = None, response: tornado.httpclient.HTTPResponse = None)[source]

由于HTTP请求失败而引发的异常.

Attributes:

  • 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

HTTPClientError别名.

Command-line interface

该模块提供了一个简单的命令行界面,以使用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

Implementations

class tornado.simple_httpclient.SimpleAsyncHTTPClient[source]

无阻塞HTTP客户端,无外部依赖关系.

此类在Tornado的IOStreams之上实现HTTP 1.1客户端. 尚不支持基于curl的AsyncHTTPClient中的某些功能. 特别是,不支持代理,不重用连接,并且呼叫者无法选择要使用的网络接口.

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

创建一个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 ,则这两个限制中的较小者适用; 仅具有max_body_sizestreaming_callback .

在版本4.2中进行了更改:添加了max_body_size参数.

class tornado.curl_httpclient.CurlAsyncHTTPClient(max_clients=10, defaults=None)

基于libcurl的HTTP客户端.

Example Code