原文链接 -> 传送门
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 见 更低级别的类 章节）。【源代码】
| 参数 |
含义 |
| method | 指定 HTTP 使用的方法 |
| url | 指定 URL |
| headers | 指定 HTTP 头部内容，是以字典（Dict）的形式 |
| files | 以字典的形式 {filename: fileobject} 上传多部分编码文件 |
| data | 指定附加到请求上的 body 内容，如果提供的是字典，则将进行表单编码 |
| json | 指定附加到请求上的 body 内容，是以 JSON 格式的形式 |
| params | 指定附加到 URL 上的查询字符串，是以字典（Dict）的形式 |
| cookies | 指定附加到请求上的 cookies 内容，可以是字典（Dict）或者 CookieJar 对象 |
| hooks | 指定供内部使用的回调钩子，是以字典（Dict）的形式 |
用法：
>>> import requests
>>> req = requests.Request('GET', 'http://httpbin.org/get')
>>> req.prepare()
<PreparedRequest [GET]>deregister_hook(event, hook)
注销以前注册的钩子。
如果钩子存在返回 True，否则返回 False。
prepare()
构建一个用于传输的 PreparedRequest 对象（requests.PreparedRequest 见 更低级别的类 章节）并返回。【源代码】
register_hook(event, hook)
注册一个钩子。
2、class requests.Response
Response 对象包含服务器对 HTTP 请求的响应内容。【源代码】
apparent_encoding
当前的编码，由 chardet 库提供编码检测技术（参见 -> 一次性解决你所有的编码检测问题）。
close()
将连接释放回池中。一个该方法被调用，就不能再次访问底层的 raw 对象了。【源代码】
注意：该方法通常不需要显式地去调用它。
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，见 会话 章节）。
iter_content(chunk_size=1, decode_unicode=False)
遍历响应的数据。【源代码】
当请求设置为 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)
遍历响应的数据，每次遍历一行数据。【源代码】
当请求设置为 stream=True 时，这个方法可以避免一次性读取大量的响应内容。
注意：这个方法不是安全的可重入方法。
json(**kwargs)
如果存在的话，返回 json 编码的响应内容【源代码】。
参数：**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，查看 异常 章节）。【源代码】
raw = None
表示响应的文件对象（高阶用法），使用 raw 需要在请求时设置 stream=True。
reason = None
响应的 HTTP 状态码对应的原因。比如 "Not Found" 或 "OK"。
request = None
对应该响应的 PreparedRequest 对象（requests.PreparedRequest，见 更低级别的类 章节）。
status_code = None
响应的 HTTP 状态码。比如 404 或 200。
text
响应的内容，以 unicode 的形式。
如果 Response.encoding 是 None，那么将使用 chardet 库来检测编码（参见 -> 一次性解决你所有的编码检测问题）。
响应内容的编码仅基于 HTTP 报头决定，遵循 RFC 2616 规范。如果你可以利用非 HTTP 的知识更好地猜测出编码，那么应该在访问该属性之前设置 r.encoding 的值。
url = None
Response 最终的 URL 地址。
五、更低级别的类
1、class requests.PreparedRequest
PreparedRequest 对象是一个完全可变对象，包含将要发送给服务器的确切数据【源代码】。
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)
进行整个请求的准备工作。【源代码】
prepare_auth(auth, url='')
准备 HTTP 认证数据。【源代码】
prepare_body(data, files, json=None)
准备 HTTP 数据体。【源代码】
prepare_content_length(body)
准备基于请求方法和数据体的 Content-Length 头。【源代码】
prepare_cookies(cookies)
准备 HTTP 的 cookie 数据。【源代码】
这个方法最后使用 cookielib 从给定的 cookies 中生成一个 Cookie 头。由于 cookielib 的设计缘故，如果 Cookie 头本身已经存在，则不会重新生成，这就意味着该方法在 PreparedRequest 对象的整个生命过程中只能调用一次，随后再次调用该方法将没有任何实际效果，除非 Cookie 头事先被去除。
prepare_headers(headers)
准备 HTTP 头。【源代码】
prepare_hooks(hooks)
准备钩子。【源代码】
prepare_method(method)
准备 HTTP 方法。【源代码】
prepare_url(url, params)
准备 HTTP URL。【源代码】
register_hook(event, hook)
正确地注册一个钩子。
url = None
指定请求发送的目的地 URL。
2、class requests.adapters.BaseAdapter
基本传输适配器。【源代码】
close()
清理适配器特定项目。【源代码】
send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)
发送 PreparedRequest 对象。返回 Response 对象。【源代码】
| 参数 |
含义 |
| request | 指定发送的 PreparedRequest 对象 |
| stream（可选） | 是否使用流传输请求的内容 |
| timeout（可选） | 指定等待服务器发送数据的超时时间；可以是一个浮点数，也可以是一个元组（连接超时，读取超时） |
| verify（可选） | 如果是一个布尔类型的值，表示是否验证服务器的 TLS 证书；如果是一个字符串，表示要使用的 CA 证书的路径 |
| cert（可选） | 指定由用户提供的可信 SSL 证书 |
| proxies（可选） | 指定请求使用的代理，是以字典（dict）的形式 |
3、class requests.adapters.HTTPAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)
urllib3 内置的 HTTP 适配器。【源代码】
通过实现传输适配器接口，为 Requests 会话提供一个通用的接口来联系 HTTP 和 HTTPS URL。这个类通常由封面下面的 Session 类（requests.Session，见 会话 章节）创建。
| 参数 |
含义 |
| pool_connections | 指定 urllib3 连接池的缓存数量 |
| pool_maxsize | 指定连接池中最多可以保存的连接数目 |
| max_retries | 指定每个连接最多可以尝试多少次 请注意：这仅适用于 DNS 查询失败，套接字连接和连接超时，不会从服务器上请求数据。默认情况下，Requests 不会重新尝试失败的连接。如果你需要重新尝试一个请求，可以导入 urllib3 的 Retry 类代替。 |
| pool_block | 指定连接池是否应该阻塞连接 |
用法：
>>> import requests
>>> s = requests.Session()
>>> a = requests.adapters.HTTPAdapter(max_retries=3)
>>> s.mount('http://', a)add_headers(request, **kwargs)
添加任何连接需要的 header 信息。【源代码】
从 v2.0 开始，默认情况下不执行任何操作，但仍然被覆盖在 HTTPAdapter 子类化的用户中。
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| request | 指定要添加 header 信息的 PreparedRequest 对象 |
| kwargs | 指定来自 call() 方法的关键字参数 |
build_response(req, resp)
从 urllib3 响应中构建一个 Response 对象。【源代码】
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| req | 指定用于生成响应的 PreparedRequest 对象 |
| resp | 指定 urllib3 的响应对象 |
cert_verify(conn, url, verify, cert)
验证 SSL 证书。【源代码】
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| conn | 指定与证书关联的 urllib3 连接对象 |
| url | 指定请求的 URL |
| verify | 如果是一个布尔类型的值，表示是否验证服务器的 TLS 证书；如果是一个字符串，表示要使用的 CA 证书的路径 |
| cert | 指定待认证的 SSL 证书 |
close()
处置任何内部状态。【源代码】
当前，这将关闭 PoolManager 和任何活动的 ProxyManager，即关闭所有的池连接。
get_connection(url, proxies=None)
返回给定 URL 的 urllib3 连接。【源代码】
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| url | 指定待连接的 URL[/tr] |
| proxies（可选） | 该请求使用的代理，是以 Requests 的字典（dict）形式。 |
init_poolmanager(connections, maxsize, block=False, **pool_kwargs)
初始化一个 urllib3 PoolManager。【源代码】
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| connections | 指定 urllib3 连接池的缓存数量 |
| maxsize | 指定连接池中最多可能存放的连接数 |
| block | 当没有空闲的可用连接时是否阻断 |
| pool_kwargs | 其它用于内存池管理（Pool Manager）的关键字参数 |
proxy_headers(proxy)
返回一个字典（dict），包含所有通过代理发送的请求的头部。【源代码】
这可以与 urllib3 一起使用，以确保它们被正确地发送到代理，而不是正在使用的 CONNECT 隧道请求。
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| proxies | 指定该请求的 url 所使用的代理 |
proxy_manager_for(proxy, **proxy_kwargs)
返回代理的 urllib3 ProxyManager。【源代码】
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| proxy | 指定返回 urllib3 ProxyManager 的代理 |
| proxy_kwargs | 其它用于代理管理（Proxy Manager）的关键字参数 |
request_url(request, proxies)
获取最后的请求中所使用的 url。【源代码】
如果消息是通过 HTTP 代理发送的，所使用的就是完整的 URL；否则，我们只需要使用局部 URL 即可。
这个方法不应该从用户代码中调用，并且只有在对 HTTPAdapter 进行子类化时才被使用。
| 参数 |
含义 |
| request | 指定发送的 PreparedRequest 对象 |
| proxies | 以字典（dict）的形式存协议或代理 URLs 的主机和协议 |
send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)
发送 PreparedRequest 对象，返回 Response 对象。【源代码】
| 参数 |
含义 |
| request | 指定发送的 PreparedRequest 对象 |
| stream（可选） | 指定是否以流的形式进行请求连接 |
| timeout（可选） | 指定等待服务器响应的超时时间如果是元组 (t1, t2)，那么 t1 表示连接超时，t2 表示读取超时 可以是浮点型、元组或 urllib3 的 Timeout 对象 |
| verify（可选） | 可以是一个布尔类型的值，表示是否验证服务器的 TLS 证书；也可以是一个字符串，包含一个 CA 证书的路径 |
| cert（可选） | 指定由用户提供的可信 SSL 证书 |
| proxies（可选） | 指定请求应用的代理，是以字典（dict）的形式 |