原文链接 -> 传送门
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 认证。