原文链接 -> 传送门
The API Documentation / Guide(1)
目录
The API Documentation / Guide(1)
文档包含了所有 Requests 自身的接口讲解,对于外部依赖的库,我们在这里介绍最核心的内容,并给大家提供其官方文档的链接。
一、主要接口
Requests 所有的功能都可以通过以下 7 个方法访问,它们的返回值都是一个 Response 对象的实例。
1、requests.request(method, url, **kwargs)
构建并发送一个 Request 对象。【源代码】
参数:
参数 | 含义 |
method | 指定 Request 对象的方法 |
url | 指定 Request 对象的 URL |
params(可选) | 指定 Request 对象的查询字符串,可以是字典(Dict)或者字节数组(Bytes) |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
headers(可选) | 指定 Request 对象的 HTTP 头部内容,是以字典(Dict)的形式 |
cookies(可选) | 指定 Request 对象的 cookies 内容,可以是字典(Dict)或者 CookieJar 对象 |
files(可选) | 以字典的形式上传多部分编码文件({'name': file-like-objects} 或 {'name': file-tuple}),其中的 file-tuple 可以是一个 2 元组 ('filename', fileobj),也可以是一个 3 元组 ('filename', fileobj, 'content_type'),还可以是一个 4 元组 ('filename', fileobj, 'content_type', custom_headers)。注:'content-type' 是由一个字符串来描述上传的文件类型;custom_headers 是一个类似字典的对象,包含额外的 header 信息 |
auth(可选) | 启用 Basic(基础)或 Digest(摘要式)或 Custom(自定义)的 HTTP 认证 |
timeout(可选) | 指定等待服务器响应的超时时间,可以是整形、浮点型,也可以是一个元组 (t1, t2),如果是元组,那么 t1 表示连接超时,t2 表示读取超时 |
allow_redirects(可选) | 是否允许重定向,Enable(启用)或 disable(禁用)GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD 的重定向,默认值是 True |
proxies(可选) | 指定代理网址,是以字典(Dict)的形式 |
verify(可选) | 可以是一个布尔类型的值,表示是否验证服务器的 TLS 证书;也可以是一个字符串,包含一个 CA 证书的路径。默认值是 True |
stream(可选) | 是否允许流式传输数据,如果为 False,响应内容会立即下载 |
cert(可选) | 如果是字符串,那么是 ssl 客户端证书(.pem)的路径;如果是元组,那么是一个 ('cert', 'key') 的键值对 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
用法:
>>> import requests
>>> req = requests.request('GET', 'http://bbs.fishc.com')
>>> req
<Response [200]>
2、requests.head(url, **kwargs)
发送一个 HEAD 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
3、requests.get(url, params=None, **kwargs)
发送一个 GET 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
params(可选) | 指定 Request 对象的查询字符串,可以是字典(Dict)或者字节数组(Bytes) |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
4、requests.post(url, data=None, json=None, **kwargs)
发送一个 POST 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
5、requests.put(url, data=None, json=None, **kwargs)
发送一个 PUT 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
6、requests.patch(url, data=None, **kwargs)
发送一个 PATCH 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
7、requests.delete(url, **kwargs)
发送一个 DELETE 请求。【源代码】
参数:
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
二、异常
exception requests.RequestException(*args, **kwargs)
处理请求的时候发生不确定类型的异常。【源代码】
exception requests.ConnectionError(*args, **kwargs)
发生连接上的错误。【源代码】
exception requests.HTTPError(*args, **kwargs)
发生 HTTP 错误。【源代码】
exception requests.URLRequired(*args, **kwargs)
请求需要一个合法的 URL(言下之意就是你的 URL 有问题)。【源代码】
exception requests.TooManyRedirects(*args, **kwargs)
太多重定向。【源代码】
exception requests.ConnectTimeout(*args, **kwargs)
尝试连接远程服务器超时。【源代码】
exception requests.ReadTimeout(*args, **kwargs)
在指定时间内,服务器并没有返回任何数据。【源代码】
exception requests.Timeout(*args, **kwargs)
请求超时(捕获该异常相当于同时捕获 ConnectTimeout 和 ReadTimeout)。【源代码】
三、会话
class requests.Session
Requests 的 Session 类。【源代码】
Requests 的会话对象基于 Session 类创建,提供了 cookie 保持、连接池(connection-pooling)和配置信息。
基本用法:
>>> import requests
>>> s = requests.Session()
>>> s.get('http://httpbin.org/get')
<Response [200]>
或者使用上下文管理器:
>>> with requests.Session() as s:
>>> s.get('http://httpbin.org/get')
<Response [200]>
auth = None
指定附加到 Request 上的默认认证数组或对象。
cert = None
指定默认的 SSL 客户端证书。如果是字符串,其内容是 ssl 客户端证书文件的路径;如果是元组,则是 ('cert', 'key') 键值对。
close()
关闭所有的适配器及会话。【源代码】
cookies = None
指定一个 CookieJar 对象,包含此会话中所有未完成的 cookies。默认情况下是一个 RequestsCookieJar 对象(见 Cookies 章节),但也可以是其他兼容的 cookielib.CookieJar 对象。
delete(url, **kwargs)
发送一个 DELETE 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
get(url, **kwargs)
发送一个 GET 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
get_adapter(url)
返回 URL 对应的连接适配器对象(requests.adapters.BaseAdapter,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
get_redirect_target(resp)
获取一个响应,返回重定向的 URI 或 None。
head(url, **kwargs)
发送一个 HEAD 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
headers = None
headers 是一个不区分大小写的字典(dict),用于在本次会话中发给每一个 Request 对象。
hooks = None
指定事件处理钩子。
max_redirects = None
指定允许重定向的最大数目。如果请求超过这个限制,将抛出一个 TooManyRedirects 的异常(TooManyRedirects,见 异常 章节)。默认值是 requests.models.DEFAULT_REDIRECT_LIMIT,即 30。
merge_environment_settings(url, proxies, stream, verify, cert)
检查环境并与一些设置合并,返回类型是字典(dict)。【源代码】
mount(prefix, adapter)
注册一个连接适配器到前缀。适配器的排序按前缀的长度降序排序。【源代码】
options(url, **kwargs)
发送一个 OPTIONS 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
params = None
以字典(dict)的形式指定附加到每个 Request 对象的查询字符串,字典值可以是表示多值查询参数的列表。
patch(url, data=None, **kwargs)
发送一个 PATCH 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
post(url, data=None, json=None, **kwargs)
发送一个 POST 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
prepare_request(request)
构建一个传输用的 PreparedRequest 对象(requests.PreparedRequest,见 更低级别的类 章节)并返回。PreparedRequest 对象拥有 Request 实例对象和会话的合并设置。【源代码】
参数 | 含义 |
url | 指定一个 Request 实例对象。 |
proxies = None
指定用于每个 Request 对象使用的代理,字典(dict)映射协议或协议和主机代理服务器的 URL(例如 {'http': 'foo.bar:3128', 'http://host.name': 'foo.bar:4012'})。
put(url, data=None, **kwargs)
发送一个 PUT 请求,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
参数 | 含义 |
url | 指定 Request 对象的 URL |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
**kwargs(可选) | 同 request 方法的 **kwargs 参数 |
rebuild_auth(prepared_request, response)
在重定向时,我们可能希望取消请求的身份验证,以避免泄漏认证信息。这个方法可以智能移除认证并尽可能避免重复认证。
rebuild_method(prepared_request, response)
在重定向时,我们可能希望根据某些规范或浏览器行为更改请求的方法。
rebuild_proxies(prepared_request, proxies)
此方法根据当前的环境变量来重新评估代理配置。如果我们重定向到一个 NO_PROXY 的 URL 上,则跳过代理配置。否则,我们设置该 URL 为缺少代理密钥(因为它们被先前的重定向删除了)。
这种方法在必要的时候可以取代 HTTP 头中的 Proxy-Authorization。
request(method, url, params=None, data=None, headers=None, cookies=None, files=None, auth=None, timeout=None, allow_redirects=True, proxies=None, hooks=None, stream=None, verify=None, cert=None, json=None)
构建并发送一个 Request 对象。【源代码】
参数 | 含义 |
method | 指定 Request 对象的方法 |
url | 指定 Request 对象的 URL |
params(可选) | 指定 Request 对象的查询字符串,可以是字典(Dict)或者字节数组(Bytes) |
data(可选) | 指定 Request 对象的 body 内容,可以是字典(Dict)、包含元组的列表 [(key, value)]、字节数组(Bytes)或者类文件对象 |
json(可选) | 指定 Request 对象的 body 内容,是以 JSON 格式的形式 |
headers(可选) | 指定 Request 对象的 HTTP 头部内容,是以字典(Dict)的形式 |
cookies(可选) | 指定 Request 对象的 cookies 内容,可以是字典(Dict)或者 CookieJar 对象 |
files(可选) | 以字典的形式上传多部分编码文件({'name': file-like-objects} 或 {'name': file-tuple}),其中的 file-tuple 可以是一个 2 元组 ('filename', fileobj),也可以是一个 3 元组 ('filename', fileobj, 'content_type'),还可以是一个 4 元组 ('filename', fileobj, 'content_type', custom_headers)。注:'content-type' 是由一个字符串来描述上传的文件类型;custom_headers 是一个类似字典的对象,包含额外的 header 信息 |
auth(可选) | 启用 Basic(基础)或 Digest(摘要式)或 Custom(自定义)的 HTTP 认证 |
timeout(可选) | 指定等待服务器响应的超时时间,可以是整形、浮点型,也可以是一个元组 (t1, t2),如果是元组,那么 t1 表示连接超时,t2 表示读取超时 |
allow_redirects(可选) | 是否允许重定向,Enable(启用)或 disable(禁用)GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD 的重定向,默认值是 True |
proxies(可选) | 指定代理网址,是以字典(Dict)的形式 |
verify(可选) | 可以是一个布尔类型的值,表示是否验证服务器的 TLS 证书;也可以是一个字符串,包含一个 CA 证书的路径。默认值是 True |
stream(可选) | 是否允许流式传输数据,如果为 False,响应内容会立即下载 |
cert(可选) | 如果是字符串,那么是 ssl 客户端证书(.pem)的路径;如果是元组,那么是一个 ('cert', 'key') 的键值对 |
返回值:
返回一个 Response 对象(requests.Response,见 低级别的类 章节)。
resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)
获取一个 Response,返回 Responses 或 Requests 的生成器。
send(request, **kwargs)
发送一个 PreparedRequest,返回一个 Response 对象(requests.Response,见 低级别的类 章节)。【源代码】
stream = None
指定流响应内容的默认值。
trust_env = None
指定类似代理配置、默认身份认证的信任环境设置。
verify = None
指定默认的 SSL 认证。