aiohttp 中文文档

客户端会话(Client Session):

客户端会话(Client Session)是比较推荐使用的发起HTTP请求的接口。

会话(Session)封装有一个连接池(连接器实例)，默认支持持久连接。除非你要连接非常多不同的服务器，否则建议你在你的应用程序中只使用一个会话(Session)，这样有利于连接池.

使用案例:

import aiohttp
import asyncio

async def fetch(client):
    async with client.get('http://python.org') as resp:
        assert resp.status == 200
        return await resp.text()

async def main():
    async with aiohttp.ClientSession() as client:
        html = await fetch(client)
        print(html)

loop = asyncio.get_event_loop()
loop.run_until_complete(main())

新增于0.17版本。

客户端会话(ClientSession)支持使用上下文管理器在结束时自动关闭。

class aiohttp.ClientSession(*, connector=None, loop=None, cookies=None, headers=None, skip_auto_headers=None, auth=None, json_serialize=json.dumps, version=aiohttp.HttpVersion11, cookie_jar=None, read_timeout=None, conn_timeout=None, raise_for_status=False, connector_owner=True, auto_decompress=True, proxies=None)

该类用于创建客户端会话以及发起请求。

(参数)Parameters:

connector (aiohttp.connector.BaseConnector) – 基础连接器(BaseConnector)的子类实例，用于支持连接池。
loop –
事件循环(event loop)用于处理HTTP请求。
如果loop为None,则从connector中获取(如果也有的话)。
一般用asyncio.get_event_loop()来获取事件循环。
自 2.0版本后已被弃用。(2.0版本发布日是2017/3/20，之前的文档内写明遭到弃用的还是会保留一年半。)
cookies (dict) – 发送请求时所携带的cookies(可选)。
headers –
所有请求发送时携带的HTTP头(可选)。
可以是任何可迭代的键值对(key-value)对象或Mapping.(例如: dict, CIMultiDict)
skip_auto_headers –
跳过会自动产生的headers值.
如果没有显式传递，那么aiohttp会自动生成诸如User-Agent或Content-Type。使用该参数可以指定跳过，但注意Content-Length是不能跳过的。
auth(aiohttp.BasicAuth) – 表示 HTTP基本认证的对象。
version –
使用的HTTP版本，默认是HTTP 1.1。
新增于0.21版本。
cookie_jar –
Cookie jar ,AbstractCookieJar的实例。
默认情况下每个会话实例都有自己的私有cookie jar用于自动处理cookies，但用户也可使用自己的jar重新定义其行为。
在代理模式下不会处理cookies。
如果不需要cookie处理，可以传递一个aiohttp.helper.DummyCookieJar实例。
新增于0.22版本。
json_serialize (可调用对象) –
可调用的Json序列化对象，默认是json.dumps()函数。
raise_for_status (布尔类型) –
每完成一个响应就自动调用 ClientResponse.raise_for_status(), 默认是False.
新增于2.0版本。
read_timeout (浮点数) –
请求操作的超时时间。read_timeout是累计自所有的请求操作(请求，重定向，响应，数据处理)。默认情况下是 5*60秒(5分钟)。传递None或0来禁用超时检测。
conn_timeout (浮点数) –
建立连接的超时时间(可选)。0或None则禁用超时检测。
connector_owner (布尔类型) –
会话关闭时一同关闭连接器实例。
传递False让构造器允许在多个会话间共享连接池，不过cookies等信息是不共享的。
新增于2.1版本。
auto_decompress (布尔类型) –
自动解压响应体。
新增于2.3版本。
trust_env(布尔类型) –
若该参数设置为True则从环境变量HTTP_PROXY / HTTPS_PROXY中获取代理信息。
新增于2.3版本。

closed
若会话已关闭则返回True，否则返回False。
该属性只读。

connector
返回aiohttp.connector.BaseConnector的派生实例对象，connector通常用于会话操作
该属性只读。

cookie_jar
返回会话中的cookies，是AbstractCookieJar的实例对象。
返回的对象可以用于访问和修改cookie jar中的内容。
该属性只读。
新增于1.0版本。

requote_redirect_url
aiohttp默认会重新编译传入的urls，如果服务器需要未编译的url。将其设置为False来禁用编译。
新增于2.1版本。

注意:

设置后会影响这之后的所有请求。

loop
返回用于会话创建的循环(loop)实例对象。
该属性只读。

coroutine async-with request(method, url, *, params=None, data=None, json=None, headers=None, skip_auto_headers=None, auth=None, allow_redirects=True, max_redirects=10, compress=None, chunked=None, expect100=False, read_until_eof=True, proxy=None, proxy_auth=None, timeout=5*60, verify_ssl=None, fingerprint=None, ssl_context=None, proxy_headers=None) 以异步方式执行HTTP请求，返回响应对象。

Parameters:

method (字符串) – HTTP方法，接受字符串。
url – 请求URL, 接受字符串或URL对象。
params –
可传入Maaping对象，有键值对的元组或字符串，会在发送新请求时作为查询字符串发送。不会对之后的重定向请求也传入查询字符串。(该参数可选)
允许传入的值参考:
collections.abc.Mapping : dict, aiohttp.MultiDict 或 aiohttp.MultiDictProxy
collections.abc.Iterable: tuple 或 list
已被url编码好的str(aiohttp不能对str进行url编码)
data – 放在请求体中的数据，接受字典(dcit), 字节或类文件对象。(该参数可选)
json – 任何可被json解码的python对象(该参数可选)。注: json不能与data参数同时使用。
headers (字典) – 发送请求时携带的HTTP头信息。(该参数可选)
skip_auto_headers – 跳过会自动生成的headers信息。
aiohttp会自动生成诸如User-Agent或Content-Type的信息(当然如果没有指定的话)。使用skip_auto_headers参数来跳过。
接受str或istr。(该参数可选)
auth(aiohttp.BasicAuth) – 接受HTTP基本认证对象。(该参数可选)
allow_redirects(布尔类型) – 如果设为False，则不允许重定向。默认是True。(该参数可选)
compress (布尔类型) – 如果请求内容要进行deflate编码压缩可以设为True。如果设置了Content-Encoding和Content-Length则不要使用这个参数。默认是None。(该参数可选)
chunked (整数) – 允许使用分块编码传输。开发者想使用分块数据流时，用它就没错啦。如果是允许的，aiohttp将会设置为"Transfer-encoding:chunked"，这时不要在设置Transfer-encoding和content-length这两个headers了。默认该参数为None。(该参数可选)
expect100(布尔类型) 服务器返回100时将等待响应(返回100表示服务器正在处理数据)。默认是False。(该参数可选)
read_until_eof (布尔类型) 如果响应不含Content-Length头信息将会一直读取响应内容直到无内容可读。默认是True。(该参数可选)
proxy – 代理URL，接受字符串或URL对象(该参数可选)
proxy_auth(aiohttp.BaicAuth) – 传入表示HTTP代理基础认证的对象。(该参数可选)
timeout(整数) – 覆盖会话的超时时间。
verify_ssl(布尔类型) – 对HTTPS请求验证SSL证书(默认是验证的)。如果某些网站证书无效的话也可禁用。
新增于2.3版本。
fringerprint (字节) – 传递想要验证的证书(使用DER编码的证书)的SHA256值来验证服务器是否可以成功匹配。对证书固定非常有用。
警告: 不赞成使用不安全的MD5和SHA1哈希值。
新增于2.3版本。
ssl_context (ssl.SLLContext) –
ssl上下文(管理器)用于处理HTTPS请求。(该参数可选)
ssl_context 用于配置证书授权通道，支持SSL选项等作用。
新增于2.3版本。
proxy_headers(abc.Mapping) – 如果该参数有提供内容，则会将其做为HTTP headers发送给代理。
新增于2.3版本。

返回ClientResponse:
返回一个**客户端响应(client response)**对象。
1.0版本新增的内容: 增加proxy和proxy_auth参数。添加timeout参数。
1.1版本修改的内容: URLs可以是字符串和URL对象。

coroutine async-with get(url, *, allow_redirects=True, **kwargs)
该方法会进行GET请求。
kwargs用于指定些request的参数。
Parameters:

url - 请求的URL, 字符串或URL对象。
allow_redirects (布尔类型) - 如果设为False，则不允许重定向。默认是True。返回ClientResponse:
返回一个**客户端响应(client response)**对象。
1.1版本修改的内容: URLs可以是字符串和URL对象。

coroutine async-with post(url, *, data=None, **kwargs)
该方法会执行POST请求。
kwargs用于指定些request的参数。
Parameters:

url - 请求的URL, 字符串或URL对象。
data - 接受字典，字节或类文件对象，会作为请求主体发送(可选)。