Requests 模块中文文档（四）

太过爱你忘了你带给我的痛 2022-03-25 00:41 356阅读 0赞

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

# The API Documentation / Guide（2） #

**目录**

The API Documentation / Guide（2）

四、低级别的类

五、更低级别的类

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

## **四、低级别的类** ##

### **1、class requests.****Request****(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)** ###

一个用户创建的 Request 对象。

用于准备一个发送到服务器的 PreparedRequest 对象（requests.PreparedRequest 见 更低级别的类 章节）。【[源代码][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;">指定 HTTP 使用的方法</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">url</td> 
   <td style="border-color:#e3edf5;">指定 URL</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">headers</td> 
   <td style="border-color:#e3edf5;">指定 HTTP 头部内容，是以字典（Dict）的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">files</td> 
   <td style="border-color:#e3edf5;">以字典的形式&nbsp;{filename: fileobject}&nbsp;上传多部分编码文件</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">data</td> 
   <td style="border-color:#e3edf5;">指定附加到请求上的 body 内容，如果提供的是字典，则将进行表单编码</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">json</td> 
   <td style="border-color:#e3edf5;">指定附加到请求上的 body 内容，是以 JSON 格式的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">params</td> 
   <td style="border-color:#e3edf5;">指定附加到 URL 上的查询字符串，是以字典（Dict）的形式</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">cookies</td> 
   <td style="border-color:#e3edf5;">指定附加到请求上的 cookies 内容，可以是字典（Dict）或者 CookieJar 对象</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">hooks</td> 
   <td style="border-color:#e3edf5;">指定供内部使用的回调钩子，是以字典（Dict）的形式</td> 
  </tr> 
 </tbody> 
</table>

**用法：**

>>> import requests
    >>> req = requests.Request('GET', 'http://httpbin.org/get')
    >>> req.prepare()
    <PreparedRequest [GET]>

**deregister\_hook**(event, hook)

注销以前注册的钩子。

如果钩子存在返回 True，否则返回 False。

**prepare**()

构建一个用于传输的 PreparedRequest 对象（requests.PreparedRequest 见 [更低级别的类][Link 3] 章节）并返回。【[源代码][Link 4]】

**register\_hook**(event, hook)

注册一个钩子。

### **2、class requests.Response** ###

Response 对象包含服务器对 HTTP 请求的响应内容。【[源代码][Link 5]】

**apparent\_encoding**

当前的编码，由 chardet 库提供编码检测技术（参见 -> [一次性解决你所有的编码检测问题][Link 6]）。

**close**()

将连接释放回池中。一个该方法被调用，就不能再次访问底层的 raw 对象了。【[源代码][Link 7]】

注意：该方法通常不需要显式地去调用它。

**content**

响应的内容，是以字节的形式存放。

**cookies** = None

一个 CookieJar 对象，存放服务器发回的 Cookies。

**elapsed** = None

从发送请求开始到响应抵达的时间量。这个属性用于测量从发送请求的第一个字节到完成解析 HTTP 头之间的时间。因此，不受响应内容或 stream 关键字参数的值影响。

**encoding** = None

解码访问 r.text 时的编码。

**headers** = None

以字典的形式存放响应头（不区分大小写）。

例如，headers\['content-encoding'\] 将返回一个 'Content-Encoding' 响应头。

**history** = None

一个存放 Request 历史中的 Response 对象，任何重定向响应都将会记录在这里。

这个列表按照访问时间从旧到新进行排序。

**is\_permanent\_redirect**

如果 Response 是一个永久重定向，该值为 True。

**is\_redirect**

如果 Response 是一个正确的 HTTP 重定向，可以自动处理（通过 **Sesson.resolve\_redirects**，见 [会话][Link 8] 章节）。

**iter\_content**(chunk\_size=1, decode\_unicode=False)

遍历响应的数据。【[源代码][Link 9]】

当请求设置为 stream=True 时，这个方法可以避免一次性读取大量的响应内容。

chunk\_size 参数指定了每次读入内存的字节数，这个值不一定是在解码时返回的每个项目长度。

chunk\_size 必须是 int 或 None 类型。如果是 None，则根据 stream 的值拥有不同的功能：如果 stream=True，无论接收到的块大小如何，都会读取数据；如果 stream=False，数据会作为一个单一的块返回。

如果 decode\_unicode 是 True，将根据响应的最佳可用编码对内容进行解码。

**iter\_lines**(chunk\_size=512, decode\_unicode=None, delimiter=None)

遍历响应的数据，每次遍历一行数据。【[源代码][Link 10]】

当请求设置为 stream=True 时，这个方法可以避免一次性读取大量的响应内容。

注意：这个方法不是安全的可重入方法。

**json**(\*\*kwargs)

如果存在的话，返回 json 编码的响应内容【[源代码][Link 11]】。

参数：\*\*kwargs -- 可选参数，用于 json.loads。

异常：ValueError -- 如果响应体没有包含合法的 json 格式数据，则抛出该异常。

**links**

如果存在的话，返回响应的解析标题链接。

**next**

如果存在的话，返回重定向链中下一个请求的 PreparedRequest 对象。

**ok**

如果 **status\_code** 的值小于 400，返回 True。

该属性检测响应的状态码是否在 400 到 600 之间，以查看是否存在客户端错误或服务端错误。

如果状态码在 200 到 400 之间，会返回 True。

这个属性并不是检测响应状态码是否等于 200。

**raise\_for\_status**()

如果存在，则抛出 **HTTPError** 异常（requests.HTTPError，查看 [异常][Link 8] 章节）。【[源代码][Link 12]】

**raw** = None

表示响应的文件对象（高阶用法），使用 raw 需要在请求时设置 stream=True。

**reason** = None

响应的 HTTP 状态码对应的原因。比如 "Not Found" 或 "OK"。

**request** = None

对应该响应的 PreparedRequest 对象（requests.PreparedRequest，见 [更低级别的类][Link 3] 章节）。

**status\_code** = None

响应的 HTTP 状态码。比如 404 或 200。

**text**

响应的内容，以 unicode 的形式。

如果 **Response.encoding** 是 None，那么将使用 chardet 库来检测编码（参见 -> [一次性解决你所有的编码检测问题][Link 6]）。

响应内容的编码仅基于 HTTP 报头决定，遵循 RFC 2616 规范。如果你可以利用非 HTTP 的知识更好地猜测出编码，那么应该在访问该属性之前设置 r.encoding 的值。

**url** = None

Response 最终的 URL 地址。

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

## **五、更低级别的类** ##

### **1、class requests.****PreparedRequest** ###

PreparedRequest 对象是一个完全可变对象，包含将要发送给服务器的确切数据【[源代码][Link 13]】。

PreparedRequest 对象可以由 Request 对象（requests.Request，见 低级别的类 章节）生成，也可以手动生成。

**用法：**

>>> import requests
    >>> req = requests.Request('GET', 'http://httpbin.org/get')
    >>> r = req.prepare()
    <PreparedRequest [GET]>
    
    >>> s = requests.Session()
    >>> s.send(r)
    <Response [200]>

**body** = None

指定发送给服务器的请求体（request body）。

**deregister\_hook**(event, hook)

注销以前注册的钩子。

如果钩子存在返回 True，否则返回 False。

**headers** = None

指定 HTTP 头部，是以字典（dict）的形式。

**hooks** = None

指定供内部使用的回调钩子，是以字典（Dict）的形式。

**method** = None

指定发送给服务器的 HTTP 动词。

**path\_url**

构建 URL 使用的路径。

**prepare**(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)

进行整个请求的准备工作。【[源代码][Link 14]】

**prepare\_auth**(auth, url='')

准备 HTTP 认证数据。【[源代码][Link 15]】

**prepare\_body**(data, files, json=None)

准备 HTTP 数据体。【[源代码][Link 16]】

**prepare\_content\_length**(body)

准备基于请求方法和数据体的 Content-Length 头。【[源代码][Link 17]】

**prepare\_cookies**(cookies)

准备 HTTP 的 cookie 数据。【[源代码][Link 18]】

这个方法最后使用 cookielib 从给定的 cookies 中生成一个 Cookie 头。由于 cookielib 的设计缘故，如果 Cookie 头本身已经存在，则不会重新生成，这就意味着该方法在 **PreparedRequest** 对象的整个生命过程中只能调用一次，随后再次调用该方法将没有任何实际效果，除非 Cookie 头事先被去除。

**prepare\_headers**(headers)

准备 HTTP 头。【[源代码][Link 19]】

**prepare\_hooks**(hooks)

准备钩子。【[源代码][Link 20]】

**prepare\_method**(method)

准备 HTTP 方法。【[源代码][Link 21]】

**prepare\_url**(url, params)

准备 HTTP URL。【[源代码][Link 22]】

**register\_hook**(event, hook)

正确地注册一个钩子。

**url** = None

指定请求发送的目的地 URL。

### **2、class requests.adapters.BaseAdapter** ###

基本传输适配器。【[源代码][Link 23]】

**close**()

清理适配器特定项目。【[源代码][Link 24]】

**send**(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)

发送 PreparedRequest 对象。返回 Response 对象。【[源代码][Link 25]】

<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;">request</td> 
   <td style="border-color:#e3edf5;">指定发送的 PreparedRequest 对象</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">stream（可选）</td> 
   <td style="border-color:#e3edf5;">是否使用流传输请求的内容</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">timeout（可选）</td> 
   <td style="border-color:#e3edf5;">指定等待服务器发送数据的超时时间；可以是一个浮点数，也可以是一个元组（连接超时，读取超时）</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">verify（可选）</td> 
   <td style="border-color:#e3edf5;">如果是一个布尔类型的值，表示是否验证服务器的 TLS 证书；如果是一个字符串，表示要使用的 CA 证书的路径</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">cert（可选）</td> 
   <td style="border-color:#e3edf5;">指定由用户提供的可信 SSL 证书</td> 
  </tr> 
  <tr> 
   <td style="border-color:#e3edf5;">proxies（可选）</td> 
   <td style="border-color:#e3edf5;">指定请求使用的代理，是以字典（dict）的形式</td> 
  </tr> 
 </tbody> 
</table>

### **3、class requests.adapters.HTTPAdapter(pool\_connections=10, pool\_maxsize=10, max\_retries=0, pool\_block=False)** ###

urllib3 内置的 HTTP 适配器。【[源代码][Link 26]】

通过实现传输适配器接口，为 Requests 会话提供一个通用的接口来联系 HTTP 和 HTTPS URL。这个类通常由封面下面的 Session 类（requests.Session，见 [会话][Link 8] 章节）创建。

**用法：**

>>> import requests
    >>> s = requests.Session()
    >>> a = requests.adapters.HTTPAdapter(max_retries=3)
    >>> s.mount('http://', a)

**add\_headers**(request, \*\*kwargs)

添加任何连接需要的 header 信息。【[源代码][Link 27]】

从 v2.0 开始，默认情况下不执行任何操作，但仍然被覆盖在 **HTTPAdapter** 子类化的用户中。