Python Requests 库是一个非常优雅而且简单的 HTTP 工具库，但在官网中只有英文文档，相关的教程也只对核心功能做了说明，并没对 Requests 本身做一些全量的说明，基于此，本文将翻译后的 Requests 文档整理于此，用于各位学习参考，如有不正确的地方请评论区指出。此翻译版本为 2.31.0

Quickstart （快速开始）

首先，请确保：

• 已正确的安装了 Requests
• Requests 已经是最新的

pip install requests

让我们从一些简单的例子开始。

发起一个请求

使用 Requests 发起一个请求是非常简单的。

首先导入 Requests 模块：

import requests

现在，来尝试获取一个网页。在此示例中，我们来获取 github 的发布时间线。

r = requests.get('https://api.github.com/events')

现在我们获取到了一个被命名到 r 的一个 Response 对象。至此，我们可以从这个对象中获取我们想要的所有信息。

Requests 的简单 API 意味着所有形式的 HTTP 请求都是非常明显易懂的。如下，是一个 POST 请求：

r = requests.post('https://httpbin.org/post', data={'key': 'value'})

非常给力是吧，其他 HTTP 请求同样如此：PUT、DELETE、HEAD 和 OPTIONS.

r = requests.put('https://httpbin.org/put', data={'key': 'value'})
r = requests.delete('https://httpbin.org/delete')
r = requests.head('https://httpbin.org/get')
r = requests.options('https://httpbin.org/get')

这一切看着都非常棒，但这只是 Requests 所能做的开始。

Passing Parameters In URLs （在 URL 中传递参数）

通常我们希望在 URL 中发送一些短数据。如果你使用手动创建这样的 URL，则需要将数据作为 key=value 键值对形式附着在 url 的 ？后边，例如 httpbin.org/get?key=val 。而 Requests 中则允许你将这些参数作为字符串字典提供给 params 这个关键字参数。例如，你想添加 key1=value1 和 key2=value2 到 httpbin.org/get 请求中，你就可以使用以下代码：

payload = {'key1': 'value1', 'key2': 'value2'}
r = requests.get('https://httpbin.org/get', params=payload)

此时，可以通过打印 URL 来查看拼接是否正确：

print(r.url)
# https://httpbin.org/get?key2=value2&key1=value1

Response Content（响应内容）

我们可以读取服务器响应的内容，依然以 github 时间线为例：

import requests

r = requests.get('https://api.github.com/events')
r.text
# '[{"repository":{"open_issues":0,"url":"https://github.com/...

请求将自动解码来自服务器的内容，大多数 Unicode 字符集都是无缝解码的。

当你发送请求时，Requests 会基于HTTP响应数据头中编码方式来猜测对应的编码格式（Requests makes educated guesses about the encoding of the response based on the HTTP headers）。则在访问 t.text 属性的时候，文本就会使用上边猜测的编码格式解码。你可以使用 r.encoding 来获取当前的编码格式，也可以通过它来修改其值。

r.encoding
# 'utf-8'
r.encoding = 'ISO-8859-1'

如果你修改了编码，则在你使用 r.text 时，Requests 将始终使用r.encoding 指定的新的编码方式。你可能希望在任何有特殊逻辑处理的情况下执行此操作。例如，HTML 和 XML 有能力在其自身数据中指定其编码格式。在这种情况下，你应该使用 r.content 来查找对应的编码格式，并且设置相应的编码 r.encoding，只有这样才能使你通过 r.text 来获取到正确的编码格式。

Requests 也同样适用用户自定义的情况，如果你已经创建了属于自己的编码方式并将其注册到 codecs 模块中，就可以容易地使用自定义的编码名称作为 r.enncoding 的值， 剩下的交给 Requests 来对应的编码问题。

Binary Response Content（二进制响应内容）

对于非文本内容请求，你可以使用以字节形式保存的响应体。

r.content
# b'[{"repository":{"open_issues":0,"url":"https://github.com/...

gzip 和 defalte，transfer-encodings 会自动为您解码。

如果你安装了像 Brotli 或 Brotlicffi 这样的 Brotli 库，它们则会自动为你解码。例如，要从请求返回的二进制中创建一张图片，就可以使用如下代码：

from PIL import Image
from io import BytesIO

i = Image.open(BytesIO(r.content))

JSON Response Content（JSON 响应内容）

在 Requests 中内置了一个 JSON 解码器，用于你处理 JSON 数据。

import requests

r = requests.get('https://api.github.com/events')
r.json()
# [{'repository': {'open_issues': 0, 'url': 'https://github.com/...

如果 JSON 解码失败， r.json 方法会抛出一个异常，例如，如果相应获取一个 204 响应（无内容），或者响应包含了无效的 JSON 就会抛出（
requests.exceptions.JSONDecodeError）。此包装异常为可能由不同python版本和json序列化库引发的多个异常。

应该注意的是，成功调用 r.json 方法不意味着响应也是成功的，某些服务器可能会返回一个 JSON 对象在请求失败后（例如：HTTP500 的错误），这种 JSON 将会被解码和返回。因此可以使用 r.raise_for_status() 或 r.status_code来检测请求是否符合你的预期。

Raw Response Content（原始响应内容）

在极少数情况下， 你可能希望从服务器获取原生的通讯内容，这时，你就可以使用 r.raw 来获取。与此同时，你还需要在请求的时候设置 stream=True。

r = requests.get('https://api.github.com/events', stream=True)

r.raw
# 

r.raw.read(10)
# b'\x1f\x8b\x08\x00\x00\x00\x00\x00\x00\x03'

一般情况，都是使用这样的方式来将流式数据保存到一个文件中。

with open(filename, 'wb') as fd:
    for chunk in r.iter_content(chunk_size=128):
        fd.write(chunk)

使用 Response.iter_content 可以直接解决绝大多数使用 Response.raw 的情况。当下载流式数据时，上边的方式是首选和推荐的方式。并且可以自由地调整 chunk_size 的值来适应你的实际情况。

注意：

Response.iter_content 和 Response.raw 差异对比

Response.iter_content 会自动解码 gzip 和 deflate 的传输编码。

Response.raw 是一个原生的字节流，它没有解码响应中的内容。

如果你确实需要获取响应的原生字节数据，则使用Response.raw。