Requests 模块中文文档（三）

刺骨的言语ヽ痛彻心扉 2022-04-22 23:28 710阅读 0赞

原文链接 -> [传送门][Link 1]

# The API Documentation / Guide（1） #

**目录**

The API Documentation / Guide（1）

一、主要接口

二、异常

三、会话

--------------------

文档包含了所有 Requests 自身的接口讲解，对于外部依赖的库，我们在这里介绍最核心的内容，并给大家提供其官方文档的链接。

--------------------

## **一、主要接口** ##

Requests 所有的功能都可以通过以下 7 个方法访问，它们的返回值都是一个 Response 对象的实例。

**1、requests.****request****(method, url, \*\*kwargs)**

构建并发送一个 Request 对象。【[源代码][Link 2]】

**参数：**

<table> 
 <tbody> 
  <tr> 
   <td style="border-color:#e3edf5;"> <p><strong>参数</strong></p> </td> 
   <td style="border-color:#e3edf5;"> <p><strong>含义</strong></p> </td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">method</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的方法</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">url</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的 URL</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">params（可选）</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的查询字符串，可以是字典（Dict）或者字节数组（Bytes）</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">data（可选）</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的 body 内容，可以是字典（Dict）、包含元组的列表&nbsp;[(key, value)]、字节数组（Bytes）或者类文件对象</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">json（可选）</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的 body 内容，是以 JSON 格式的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">headers（可选）</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的 HTTP 头部内容，是以字典（Dict）的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">cookies（可选）</td> 
   <td style="border-color:#e3edf5;">指定 Request 对象的 cookies 内容，可以是字典（Dict）或者 CookieJar 对象</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">files（可选）</td> 
   <td style="border-color:#e3edf5;">以字典的形式上传多部分编码文件（{'name': file-like-objects}&nbsp;或&nbsp;{'name': file-tuple}），其中的&nbsp;file-tuple&nbsp;可以是一个 2 元组&nbsp;('filename', fileobj)，也可以是一个 3 元组&nbsp;('filename', fileobj, 'content_type')，还可以是一个 4 元组&nbsp;('filename', fileobj, 'content_type', custom_headers)。注：'content-type'&nbsp;是由一个字符串来描述上传的文件类型；custom_headers&nbsp;是一个类似字典的对象，包含额外的 header 信息</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">auth（可选）</td> 
   <td style="border-color:#e3edf5;">启用 Basic（基础）或 Digest（摘要式）或 Custom（自定义）的 HTTP 认证</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">timeout（可选）</td> 
   <td style="border-color:#e3edf5;">指定等待服务器响应的超时时间，可以是整形、浮点型，也可以是一个元组 (t1, t2)，如果是元组，那么 t1 表示连接超时，t2 表示读取超时</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">allow_redirects（可选）</td> 
   <td style="border-color:#e3edf5;">是否允许重定向，Enable（启用）或 disable（禁用）GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD 的重定向，默认值是&nbsp;True</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">proxies（可选）</td> 
   <td style="border-color:#e3edf5;">指定代理网址，是以字典（Dict）的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">verify（可选）</td> 
   <td style="border-color:#e3edf5;">可以是一个布尔类型的值，表示是否验证服务器的 TLS 证书；也可以是一个字符串，包含一个 CA 证书的路径。默认值是&nbsp;True</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">stream（可选）</td> 
   <td style="border-color:#e3edf5;">是否允许流式传输数据，如果为&nbsp;False，响应内容会立即下载</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">cert（可选）</td> 
   <td style="border-color:#e3edf5;">如果是字符串，那么是 ssl 客户端证书（.pem）的路径；如果是元组，那么是一个 ('cert', 'key') 的键值对</td> 
  </tr> 
 </tbody> 
</table>

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**用法：**

>>> import requests
    >>> req = requests.request('GET', 'http://bbs.fishc.com')
    >>> req
    <Response [200]>

**2、requests.****head****(url, \*\*kwargs)**

发送一个 HEAD 请求。【[源代码][Link 5]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**3、requests.****get****(url, params=None, \*\*kwargs)**

发送一个 GET 请求。【[源代码][Link 6]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**4、requests.****post****(url, data=None, json=None, \*\*kwargs)**

发送一个 POST 请求。【[源代码][Link 7]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**5、requests.****put****(url, data=None, json=None, \*\*kwargs)**

发送一个 PUT 请求。【[源代码][Link 8]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**6、requests.****patch****(url, data=None, \*\*kwargs)**

发送一个 PATCH 请求。【[源代码][Link 9]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**7、requests.****delete****(url, \*\*kwargs)**

发送一个 DELETE 请求。【[源代码][Link 9]】

**参数：**

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

--------------------

## **二、异常** ##

exception requests.**RequestException**(\*args, \*\*kwargs)

处理请求的时候发生不确定类型的异常。【[源代码][Link 10]】

exception requests.**ConnectionError**(\*args, \*\*kwargs)

发生连接上的错误。【[源代码][Link 11]】

exception requests.**HTTPError**(\*args, \*\*kwargs)

发生 HTTP 错误。【[源代码][Link 12]】

exception requests.**URLRequired**(\*args, \*\*kwargs)

请求需要一个合法的 URL（言下之意就是你的 URL 有问题）。【[源代码][Link 13]】

exception requests.**TooManyRedirects**(\*args, \*\*kwargs)

太多重定向。【[源代码][Link 14]】

exception requests.**ConnectTimeout**(\*args, \*\*kwargs)

尝试连接远程服务器超时。【[源代码][Link 15]】

exception requests.**ReadTimeout**(\*args, \*\*kwargs)

在指定时间内，服务器并没有返回任何数据。【[源代码][Link 16]】

exception requests.**Timeout**(\*args, \*\*kwargs)

请求超时（捕获该异常相当于同时捕获 ConnectTimeout 和 ReadTimeout）。【[源代码][Link 17]】

--------------------

## **三、会话** ##

**class requests.Session**

Requests 的 Session 类。【[源代码][Link 18]】

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()**

关闭所有的适配器及会话。【[源代码][Link 19]】

**cookies = None**

指定一个 CookieJar 对象，包含此会话中所有未完成的 cookies。默认情况下是一个 **RequestsCookieJar** 对象（见 Cookies 章节），但也可以是其他兼容的 cookielib.CookieJar 对象。

**delete(url, \*\*kwargs)**

发送一个 DELETE 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 20]】

**get(url, \*\*kwargs)**

发送一个 GET 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 21]】

**get\_adapter(url)**

返回 URL 对应的连接适配器对象（requests.adapters.BaseAdapter，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 22]】

**get\_redirect\_target(resp)**

获取一个响应，返回重定向的 URI 或 None。

**head(url, \*\*kwargs)**

发送一个 HEAD 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 23]】

**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）。【[源代码][Link 24]】

**mount(prefix, adapter)**

注册一个连接适配器到前缀。适配器的排序按前缀的长度降序排序。【[源代码][Link 25]】

**options(url, \*\*kwargs)**

发送一个 OPTIONS 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 26]】

**params = None**

以字典（dict）的形式指定附加到每个 Request 对象的查询字符串，字典值可以是表示多值查询参数的列表。

**patch(url, data=None, \*\*kwargs)**

发送一个 PATCH 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 27]】

**post(url, data=None, json=None, \*\*kwargs)**

发送一个 POST 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 28]】

**prepare\_request(request)**

构建一个传输用的 **PreparedRequest** 对象（requests.PreparedRequest，见 [更低级别的类 ][Link 3]章节）并返回。PreparedRequest 对象拥有 Request 实例对象和会话的合并设置。【[源代码][Link 29]】

**proxies = None**

指定用于每个 Request 对象使用的代理，字典（dict）映射协议或协议和主机代理服务器的 URL（例如 \{'http': 'foo.bar:3128', 'http://host.name': 'foo.bar:4012'\}）。

**put(url, data=None, \*\*kwargs)**

发送一个 PUT 请求，返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 30]】

**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 对象。【[源代码][Link 31]】

**返回值：**

返回一个 Response 对象（requests.Response，见 [低级别的类][Link 3][ ][Link 4]章节）。

**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，见 [低级别的类][Link 3][ ][Link 4]章节）。【[源代码][Link 32]】

**stream = None**

指定流响应内容的默认值。

**trust\_env = None**

指定类似代理配置、默认身份认证的信任环境设置。

**verify = None**

指定默认的 SSL 认证。

[Link 1]: http://docs.python-requests.org/en/master/#
[Link 2]: http://docs.python-requests.org/en/master/_modules/requests/api/#request
[Link 3]: https://blog.csdn.net/qq_41556318/article/details/86532048
[Link 4]: https://blog.csdn.net/qq_41556318/article/details/84485541
[Link 5]: http://docs.python-requests.org/en/master/_modules/requests/api/#head
[Link 6]: http://docs.python-requests.org/en/master/_modules/requests/api/#get
[Link 7]: http://docs.python-requests.org/en/master/_modules/requests/api/#post
[Link 8]: http://docs.python-requests.org/en/master/_modules/requests/api/#put
[Link 9]: http://docs.python-requests.org/en/master/_modules/requests/api/#patch
[Link 10]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#RequestException
[Link 11]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#ConnectionError
[Link 12]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#HTTPError
[Link 13]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#URLRequired
[Link 14]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#TooManyRedirects
[Link 15]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#ConnectTimeout
[Link 16]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#ReadTimeout
[Link 17]: http://docs.python-requests.org/en/master/_modules/requests/exceptions/#Timeout
[Link 18]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session
[Link 19]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.close
[Link 20]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.delete
[Link 21]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.get
[Link 22]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.get_adapter
[Link 23]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.head
[Link 24]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.merge_environment_settings
[Link 25]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.mount
[Link 26]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.options
[Link 27]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.patch
[Link 28]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.post
[Link 29]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.prepare_request
[Link 30]: http://docs.python-requests.org/en/master/_modules/requests/sessions/#Session.put
[Link 31]: http://docs.python-requests.org/en/latest/_modules/requests/sessions/#Session.request
[Link 32]: http://docs.python-requests.org/en/latest/api/#requests.Response