开发者界面¶

本部分文档涵盖 Requests 的所有界面。对于 Requests 依赖于外部库的部分，我们在此处记录最重要的部分，并提供指向规范文档的链接。

主界面¶

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

requests.request(method, url, **kwargs)[source]¶

构建并发送 Request。

参数:

method – 新 Request 对象的方法：GET、OPTIONS、HEAD、POST、PUT、PATCH 或 DELETE。
url – 新 Request 对象的 URL。
params –（可选）用于在 Request 的查询字符串中发送的字典、元组列表或字节。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json –（可选）要发送到 Request 正文中的 JSON 可序列化 Python 对象。
headers –（可选）要随 Request 发送的 HTTP 标头字典。
cookies –（可选）要随 Request 发送的 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 是一个类似于字典的对象，其中包含要为该文件添加的其他标头。
auth –（可选）用于启用基本/摘要/自定义 HTTP 身份验证的身份验证元组。
超时 (浮点数或元组) – (可选)以浮点数或(连接超时，读取超时)元组形式表示放弃之前等待服务器发送数据的秒数。
允许重定向 (布尔值) – (可选)布尔值。启用/禁用 GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD 重定向。默认为 True。
代理 – (可选)将协议映射到代理 URL 的字典。
验证 – (可选)布尔值，在这种情况下它控制我们是否验证服务器的 TLS 证书，或字符串，在这种情况下它必须是用于 CA 捆绑包的路径。默认为 True。
流 – (可选)如果为 False，则立即下载响应内容。
证书 – (可选)如果为字符串，则为 SSL 客户端证书文件 (.pem) 的路径。如果是元组，则为 (‘cert’, ‘key’) 对。

返回:

Response 对象

返回类型:

requests.Response

用法

>>> import requests
>>> req = requests.request('GET', 'https://httpbin.org/get')
>>> req
<Response [200]>

requests.head(url, **kwargs)[source]¶

发送 HEAD 请求。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。如果未提供 allow_redirects，则将其设置为 False（与默认 request 行为相反）。

返回:

Response 对象

返回类型:

requests.Response

requests.get(url, params=None, **kwargs)[source]¶

发送 GET 请求。

参数:

url – 新 Request 对象的 URL。
params –（可选）用于在 Request 的查询字符串中发送的字典、元组列表或字节。
**kwargs – request 采用的可选参数。

返回:

Response 对象

返回类型:

requests.Response

requests.post(url, data=None, json=None, **kwargs)[source]¶

发送 POST 请求。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json –（可选）要发送到 Request 正文中的 JSON 可序列化 Python 对象。
**kwargs – request 采用的可选参数。

返回:

Response 对象

返回类型:

requests.Response

requests.put(url, data=None, **kwargs)[source]¶

发送 PUT 请求。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json –（可选）要发送到 Request 正文中的 JSON 可序列化 Python 对象。
**kwargs – request 采用的可选参数。

返回:

Response 对象

返回类型:

requests.Response

requests.patch(url, data=None, **kwargs)[source]¶

发送 PATCH 请求。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json –（可选）要发送到 Request 正文中的 JSON 可序列化 Python 对象。
**kwargs – request 采用的可选参数。

返回:

Response 对象

返回类型:

requests.Response

requests.delete(url, **kwargs)[source]¶

发送 DELETE 请求。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。

返回:

Response 对象

返回类型:

requests.Response

异常¶

exception requests.RequestException(*args, **kwargs)[source]¶: 处理请求时发生了一个不明确的异常。

exception requests.ConnectionError(*args, **kwargs)[source]¶: 发生连接错误。

exception requests.HTTPError(*args, **kwargs)[source]¶: 发生 HTTP 错误。

异常 requests.URLRequired(*args, **kwargs)[源代码]¶: 进行请求需要一个有效的 URL。

异常 requests.TooManyRedirects(*args, **kwargs)[源代码]¶: 重定向次数过多。

异常 requests.ConnectTimeout(*args, **kwargs)[源代码]¶

尝试连接到远程服务器时，请求超时。

产生此错误的请求可以安全地重试。

异常 requests.ReadTimeout(*args, **kwargs)[源代码]¶: 服务器在分配的时间内未发送任何数据。

异常 requests.Timeout(*args, **kwargs)[源代码]¶

请求超时。

捕获此错误将同时捕获 ConnectTimeout 和 ReadTimeout 错误。

异常 requests.JSONDecodeError(*args, **kwargs)[源代码]¶: 无法将文本解码为 json

请求会话¶

class requests.Session[source]¶

请求会话。

提供 cookie 持久性、连接池和配置。

基本用法

>>> import requests
>>> s = requests.Session()
>>> s.get('https://httpbin.org/get')
<Response [200]>

或作为上下文管理器

>>> with requests.Session() as s:
...     s.get('https://httpbin.org/get')
<Response [200]>

auth¶: 要附加到 Request 的默认身份验证元组或对象。

cert¶: SSL 客户端证书默认值，如果为字符串，则为 ssl 客户端证书文件 (.pem) 的路径。如果是元组，则为 (‘cert’, ‘key’) 对。

close()[source]¶: 关闭所有适配器，以及会话

cookies¶: 一个 CookieJar，其中包含在此会话上设置的所有当前未完成的 cookie。默认情况下，它是一个 RequestsCookieJar，但可以是任何其他 cookielib.CookieJar 兼容对象。

delete(url, **kwargs)[source]¶

发送 DELETE 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

get(url, **kwargs)[source]¶

发送 GET 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

get_adapter(url)[source]¶

返回给定 URL 的适当连接适配器。

返回类型:: requests.adapters.BaseAdapter

get_redirect_target(resp)¶: 接收响应。返回重定向 URI 或 None

head(url, **kwargs)[源代码]¶

发送 HEAD 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

headers¶: 不区分大小写的字典，用于发送从该 Session 发送的每个 Request 的标头。

hooks¶: 事件处理钩子。

max_redirects¶: 允许的最大重定向次数。如果请求超过此限制，则会引发 TooManyRedirects 异常。默认为 requests.models.DEFAULT_REDIRECT_LIMIT，即 30。

merge_environment_settings(url, proxies, stream, verify, cert)[源代码]¶

检查环境并将其与某些设置合并。

返回类型:: dict

mount(prefix, adapter)[源代码]¶

将连接适配器注册到前缀。

适配器按前缀长度降序排列。

options(url, **kwargs)[源代码]¶

发送 OPTIONS 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

params¶: 要附加到每个 Request 的查询字符串数据的字典。字典值可以是列表，表示多值查询参数。

patch(url, data=None, **kwargs)[源代码]¶

发送 PATCH 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

post(url, data=None, json=None, **kwargs)[源代码]¶

发送 POST 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json – （可选）在 Request 的正文中发送的 json。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

prepare_request(request)[源代码]¶

为传输构建 PreparedRequest 并返回它。 PreparedRequest 的设置从 Request 实例和 Session 的设置中合并。

参数:: request – 使用此会话的设置准备的 Request 实例。
返回类型:: requests.PreparedRequest

proxies¶: 将协议或协议和主机映射到代理 URL（例如 {‘http’: ‘foo.bar:3128’, ‘http://host.name’: ‘foo.bar:4012’}）的字典，用于每个 Request。

put(url, data=None, **kwargs)[源代码]¶

发送 PUT 请求。返回 Response 对象。

参数:

url – 新 Request 对象的 URL。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
**kwargs – request 采用的可选参数。

返回类型:

requests.Response

rebuild_auth(prepared_request, response)¶: 在被重定向时，我们可能希望从请求中删除身份验证，以避免泄露凭据。此方法在可能的情况下智能地删除和重新应用身份验证，以避免凭据丢失。

rebuild_method(prepared_request, response)¶: 在被重定向时，我们可能希望根据某些规范或浏览器行为更改请求的方法。

rebuild_proxies(prepared_request, proxies)¶

此方法通过考虑环境变量重新评估代理配置。如果我们被重定向到 NO_PROXY 涵盖的 URL，我们将删除代理配置。否则，我们将为此 URL 设置缺失的代理密钥（如果它们被之前的重定向删除）。

此方法还将在必要时替换 Proxy-Authorization 头。

返回类型:: dict

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)[source]¶

构造 Request，准备并发送它。返回 Response 对象。

参数:

method – 新 Request 对象的方法。
url – 新 Request 对象的 URL。
params –（可选）字典或字节，用于在查询字符串中发送 Request。
data –（可选）用于在 Request 的正文中发送的字典、元组列表、字节或类似文件对象。
json – （可选）在 Request 的正文中发送的 json。
headers –（可选）要随 Request 发送的 HTTP 标头字典。
cookies –（可选）要随 Request 发送的 Dict 或 CookieJar 对象。
files –（可选）字典 'filename': file-like-objects 用于多部分编码上传。
auth –（可选）Auth 元组或可调用项，以启用 Basic/Digest/Custom HTTP Auth。
timeout (float 或 tuple) –（可选）以浮点数或 (连接超时，读取超时) 元组形式，等待服务器发送数据之前放弃的时间。
allow_redirects (bool) –（可选）默认设置为 True。
proxies –（可选）将协议或协议和主机名映射到代理 URL 的字典。
hooks –（可选）将钩子名称映射到一个事件或事件列表的字典，事件必须可调用。
stream – （可选）是否立即下载响应内容。默认为 False。
verify – （可选）布尔值，用于控制是否验证服务器的 TLS 证书，或字符串，在这种情况下，它必须是用于 CA 捆绑包的路径。默认为 True。当设置为 False 时，请求将接受服务器提供的任何 TLS 证书，并忽略主机名不匹配和/或过期证书，这会使你的应用程序容易受到中间人 (MitM) 攻击。在本地开发或测试期间，将 verify 设置为 False 可能有用。
证书 – (可选)如果为字符串，则为 SSL 客户端证书文件 (.pem) 的路径。如果是元组，则为 (‘cert’, ‘key’) 对。

返回类型:

requests.Response

resolve_redirects(resp, req, stream=False, timeout=None, verify=True, cert=None, proxies=None, yield_requests=False, **adapter_kwargs)¶: 接收响应。返回响应或请求的生成器。

send(request, **kwargs)[源代码]¶

发送给定的 PreparedRequest。

返回类型:: requests.Response

should_strip_auth(old_url, new_url)¶: 决定在重定向时是否应删除授权标头

stream¶: 流式响应内容默认值。

trust_env¶: 信任环境设置，用于代理配置、默认身份验证等。

verify¶: SSL 验证默认值。默认为 True，要求请求验证远程端的 TLS 证书。如果 verify 设置为 False，请求将接受服务器提供的任何 TLS 证书，并忽略主机名不匹配和/或过期证书，这会使你的应用程序容易受到中间人 (MitM) 攻击。仅在测试时将其设置为 False。

较低级别的类¶

类 requests.Request(方法=无, 网址=无, 标头=无, 文件=无, 数据=无, 参数=无, 身份验证=无, Cookie=无, 挂钩=无, json=无)[源代码]¶

用户创建的 Request 对象。

用于准备 PreparedRequest，该请求将发送到服务器。

参数:

方法 – 要使用的 HTTP 方法。
网址 – 要发送的网址。
标头 – 要发送的标头字典。
文件 – 要多部分上传的文件的 {文件名：文件对象} 字典。
数据 – 要附加到请求的主体。如果提供了字典或元组列表 [(key, value)]，将进行表单编码。
json – 要附加到请求的主体的 json（如果未指定文件或数据）。
参数 – 要附加到网址的网址参数。如果提供了字典或元组列表 [(key, value)]，将进行表单编码。
身份验证 – 身份验证处理程序或 (用户、密码) 元组。
Cookie – 要附加到此请求的 Cookie 字典或 CookieJar。
挂钩 – 用于内部使用的回调挂钩字典。

用法

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

取消注册挂钩(事件, 挂钩)¶: 取消注册先前注册的挂钩。如果挂钩存在，则返回 True，否则返回 False。

准备()[源代码]¶: 为传输构造 PreparedRequest 并返回该请求。

注册挂钩(事件, 挂钩)¶: 正确注册挂钩。

类 requests.Response[源代码]¶

包含服务器对 HTTP 请求的响应的 Response 对象。

property apparent_encoding¶: 由 charset_normalizer 或 chardet 库提供的表观编码。

close()[source]¶

将连接释放回池。一旦调用此方法，就不应再访问底层 raw 对象。

注意：通常不需要显式调用。

property content¶: 响应的内容，以字节为单位。

cookies¶: 服务器发回的 CookieJar 的 Cookie。

elapsed¶: 发送请求和响应到达之间的时间量（以 timedelta 为单位）。此属性专门测量发送请求的第一个字节和完成标头解析之间的时间。因此，它不受消耗响应内容或 stream 关键字参数的值的影响。

encoding¶: 访问 r.text 时要解码的编码。

headers¶: 不区分大小写的响应标头字典。例如，headers['content-encoding'] 将返回 'Content-Encoding' 响应标头的值。

history¶: 来自请求历史记录的 Response 对象的列表。任何重定向响应都将在此处结束。该列表按从最旧到最新的请求排序。

property is_permanent_redirect¶: 如果此响应是重定向的永久版本之一，则为 True。

property is_redirect¶: 如果此响应是格式良好的 HTTP 重定向，则为 True，该重定向可以自动处理（通过 Session.resolve_redirects）。

iter_content(chunk_size=1, decode_unicode=False)[source]¶

遍历响应数据。当请求上设置 stream=True 时，这避免一次将内容读入内存以获取较大的响应。块大小是它应读入内存的字节数。这并不一定是返回的每个项目的长度，因为可以进行解码。

chunk_size 必须为 int 类型或 None。None 的值将根据 stream 的值而有不同的功能。stream=True 将以块接收到的任何大小读取数据。如果 stream=False，数据将作为一个单独的块返回。

如果 decode_unicode 为 True，将使用基于响应的最佳可用编码对内容进行解码。

iter_lines(chunk_size=512, decode_unicode=False, delimiter=None)[source]¶: 逐行迭代响应数据。当在请求中设置 stream=True 时，这可以避免一次性将内容读入内存以进行大响应。

注意

此方法不是可重入安全的。

json(**kwargs)[source]¶

如果存在，返回响应的 json 编码内容。

参数:: **kwargs – json.loads 采用的可选参数。
引发:: requests.exceptions.JSONDecodeError – 如果响应正文不包含有效的 json。

property links¶: 如果存在，返回响应的已解析标头链接。

property next¶: 如果存在，返回重定向链中下一个请求的 PreparedRequest。

property ok¶

如果 status_code 小于 400，则返回 True；否则返回 False。

此属性检查响应的状态代码是否在 400 到 600 之间，以查看是否存在客户端错误或服务器错误。如果状态代码在 200 到 400 之间，则将返回 True。这不是检查响应代码是否为 200 OK。

raise_for_status()[source]¶: 如果发生，引发 HTTPError。

raw¶: 响应的文件类对象表示（用于高级用法）。使用 raw 要求在请求中设置 stream=True。此要求不适用于在 Requests 内部使用。

reason¶: 响应的 HTTP 状态的文本原因，例如“未找到”或“确定”。

request¶: PreparedRequest 对象，这是它的响应。

status_code¶: 响应的 HTTP 状态的整数代码，例如 404 或 200。

property text¶

响应的内容，以 Unicode 编码。

如果 Response.encoding 为 None，则将使用 charset_normalizer 或 chardet 猜测编码。

响应内容的编码完全根据 HTTP 标头确定，完全遵循 RFC 2616。如果您能利用非 HTTP 知识对编码做出更好的猜测，则应在访问此属性之前适当地设置 r.encoding。

url¶: 响应的最终 URL 位置。

更低级别的类¶

class requests.PreparedRequest[source]¶

完全可变的 PreparedRequest 对象，包含将发送到服务器的确切字节。

实例从 Request 对象生成，不应手动实例化；这样做可能会产生不良影响。

用法

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

>>> s = requests.Session()
>>> s.send(r)
<Response [200]>

body¶: 要发送到服务器的请求正文。

deregister_hook(event, hook)¶: 取消注册先前注册的挂钩。如果挂钩存在，则返回 True，否则返回 False。

headers¶: HTTP 标头的字典。

hooks¶: 回调挂钩的字典，供内部使用。

method¶: 要发送到服务器的 HTTP 动词。

property path_url¶: 生成要使用的路径 URL。

prepare(method=None, url=None, headers=None, files=None, data=None, params=None, auth=None, cookies=None, hooks=None, json=None)[source]¶: 使用给定的参数准备整个请求。

prepare_auth(auth, url='')[source]¶: 准备给定的 HTTP 身份验证数据。

prepare_body(data, files, json=None)[source]¶: 准备给定的 HTTP 正文数据。

prepare_content_length(body)[source]¶: 根据请求方法和正文准备 Content-Length 标头

prepare_cookies(cookies)[source]¶

准备给定的 HTTP cookie 数据。

此函数最终使用 cookielib 从给定的 cookie 中生成 Cookie 标头。由于 cookielib 的设计，如果标头已存在，则不会重新生成，这意味着此函数只能在 PreparedRequest 对象的生命周期内调用一次。对 prepare_cookies 的任何后续调用都不会产生实际效果，除非事先删除了“Cookie”标头。

prepare_headers(headers)[source]¶: 准备给定的 HTTP 标头。

prepare_hooks(hooks)[source]¶: 准备给定的钩子。

prepare_method(method)[source]¶: 准备给定的 HTTP 方法。

prepare_url(url, params)[source]¶: 准备给定的 HTTP URL。

register_hook(event, hook)¶: 正确注册挂钩。

url¶: 发送请求的 HTTP URL。

class requests.adapters.BaseAdapter[source]¶

基本传输适配器

close()[source]¶: 清理特定于适配器的项目。

发送(请求, 流=错误, 超时=无, 验证=真, 证书=无, 代理=无)[源代码]¶

发送 PreparedRequest 对象。返回 Response 对象。

参数:

请求 – 正在发送的 PreparedRequest。
流 – （可选）是否流式传输请求内容。
timeout (float 或 tuple) –（可选）以浮点数或 (连接超时，读取超时) 元组形式，等待服务器发送数据之前放弃的时间。
验证 – （可选）布尔值，在这种情况下，它控制我们是否验证服务器的 TLS 证书，或者是一个字符串，在这种情况下，它必须是所用 CA 捆绑包的路径
证书 – （可选）任何用户提供的受信任的 SSL 证书。
代理 – （可选）要应用于请求的代理字典。

类 requests.adapters.HTTPAdapter(池连接=10, 池最大值=10, 最大重试次数=0, 池块=错误)[源代码]¶

urllib3 的内置 HTTP 适配器。

通过实现传输适配器接口，为请求会话提供与 HTTP 和 HTTPS URL 联系的一般情况接口。此类通常由 Session 类在后台创建。

参数:

池连接 – 要缓存的 urllib3 连接池数。
池最大值 – 要保存在池中的最大连接数。
最大重试次数 – 每个连接应尝试的最大重试次数。请注意，这仅适用于失败的 DNS 查找、套接字连接和连接超时，而永远不适用于数据已到达服务器的请求。默认情况下，Requests 不会重试失败的连接。如果您需要对我们重试请求的条件进行细粒度控制，请导入 urllib3 的 Retry 类，并改为传递该类。
池块 – 连接池是否应阻塞连接。

用法

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

add_headers(request, **kwargs)[source]¶

添加连接所需的任何标头。从 v2.0 开始，此操作默认情况下不执行任何操作，但可供子类化为 HTTPAdapter 的用户覆盖。

此操作不应从用户代码中调用，并且仅在子类化为 HTTPAdapter 时才公开使用。

参数:

request – 要向其添加标头的 PreparedRequest。
kwargs – 从 send() 调用中获取的关键字参数。

build_connection_pool_key_attributes(request, verify, cert=None)[source]¶

构建 urllib3 用于返回连接的 PoolKey 属性。

此操作会查看 PreparedRequest、用户指定的 verify 值和 cert 参数的值，以确定要使用哪些 PoolKey 值从给定的 urllib3 连接池中选择连接。

SSL 相关的池密钥参数没有始终如一地设置。截至撰写本文时，请使用以下内容来确定该字典中可能包含哪些密钥

如果 verify 为 True，则 "ssl_context" 将被设置，并且将是默认的 Requests SSL 上下文
如果 verify 为 False，则 "ssl_context" 将不会被设置，但 "cert_reqs" 将被设置
如果 verify 是一个字符串（即，它是一个用户指定的信任包），则 "ca_certs" 将被设置（如果字符串不是 os.path.isdir 识别的目录），否则 "ca_certs_dir" 将被设置。
如果指定了 "cert"，则 "cert_file" 将始终被设置。如果 "cert" 是一个包含第二个项目的元组，则 "key_file" 也将存在

要覆盖这些设置，可以对该类进行子类化，调用该方法并使用上述逻辑来根据需要更改参数。例如，如果希望使用自定义 ssl.SSLContext，则必须同时设置 "ssl_context"，并根据其他需要，更改其他键以确保所需行为。

参数:

request (PreparedRequest) – 通过连接发送的 PreparedReqest。
verify – 布尔值，在这种情况下，它控制是否验证服务器的 TLS 证书，或字符串，在这种情况下，它必须是用于 CA 捆绑包的路径。
cert – （可选）任何用户提供的 SSL 证书，用于客户端身份验证（又称 mTLS）。这可能是一个字符串（即，仅包含证书和密钥的文件路径）或长度为 2 的元组，其中包含证书文件路径和密钥文件路径。

返回:

两个字典的元组。第一个是 Pool Key 的“主机参数”部分，包括方案、主机名和端口。第二个是与 SSLContext 相关的参数字典。

build_response(req, resp)[source]¶

从 urllib3 响应构建 Response 对象。这不应从用户代码中调用，并且仅在对 HTTPAdapter 进行子类化时才公开使用。

参数:

req – 用于生成响应的 PreparedRequest。
resp – urllib3 响应对象。

返回类型:

requests.Response

cert_verify(conn, url, verify, cert)[source]¶

验证 SSL 证书。此方法不应从用户代码中调用，并且仅在对 HTTPAdapter 进行子类化时才公开使用。

参数:

conn – 与证书关联的 urllib3 连接对象。
url – 请求的 URL。
verify – 布尔值，在这种情况下，它控制是否验证服务器的 TLS 证书，或字符串，在这种情况下，它必须是用于 CA 捆绑包的路径
cert – 要验证的 SSL 证书。

close()[source]¶

处理任何内部状态。

目前，这会关闭 PoolManager 和任何活动的 ProxyManager，从而关闭任何池连接。

get_connection(url, proxies=None)[source]¶

已弃用：对于使用 Requests>=2.32.2 的 HTTPAdapter 的所有子类，用户应迁移到 get_connection_with_tls_context。

返回给定 URL 的 urllib3 连接。不应从用户代码中调用此方法，并且仅在对 HTTPAdapter 进行子类化时才公开以供使用。

参数:

url – 要连接到的 URL。
proxies – （可选）此请求中使用的代理的 Requests 样式字典。

返回类型:

urllib3.ConnectionPool

get_connection_with_tls_context(request, verify, proxies=None, cert=None)[source]¶

返回给定请求和 TLS 设置的 urllib3 连接。不应从用户代码中调用此方法，并且仅在对 HTTPAdapter 进行子类化时才公开以供使用。

参数:

request – 要通过连接发送的 PreparedRequest 对象。
verify – 布尔值，在这种情况下，它控制是否验证服务器的 TLS 证书，或字符串，在这种情况下，它必须是用于 CA 捆绑包的路径。
代理 – （可选）要应用于请求的代理字典。
cert – （可选）任何用户提供的 SSL 证书，用于客户端身份验证（又称 mTLS）。

返回类型:

urllib3.ConnectionPool

init_poolmanager(connections, maxsize, block=False, **pool_kwargs)[source]¶

初始化 urllib3 PoolManager。

不应从用户代码中调用此方法，并且仅在对 HTTPAdapter 进行子类化时才公开以供使用。

参数:

connections – 要缓存的 urllib3 连接池数。
maxsize – 池中保存的最大连接数。
block – 当没有空闲连接时阻塞。
pool_kwargs – 用于初始化池管理器的额外关键字参数。

proxy_headers(proxy)[source]¶

返回通过代理发送的任何请求要添加的标头字典。这与 urllib3 magic 协同工作，以确保它们正确发送到代理，而不是在使用 CONNECT 时以隧道请求的形式发送。

此操作不应从用户代码中调用，并且仅在子类化为 HTTPAdapter 时才公开使用。

参数:: proxy – 用于此请求的代理的 URL。
返回类型:: dict

proxy_manager_for(proxy, **proxy_kwargs)[source]¶

返回给定代理的 urllib3 ProxyManager。

不应从用户代码中调用此方法，并且仅在对 HTTPAdapter 进行子类化时才公开以供使用。

参数:

proxy – 要返回 urllib3 ProxyManager 的代理。
proxy_kwargs – 用于配置代理管理器的额外关键字参数。

返回:

ProxyManager

返回类型:

urllib3.ProxyManager

request_url(request, proxies)[source]¶

获取在发出最终请求时要使用的 URL。

如果消息通过 HTTP 代理发送，则必须使用完整的 URL。否则，我们应该只使用 URL 的路径部分。

此操作不应从用户代码中调用，并且仅在子类化为 HTTPAdapter 时才公开使用。

参数:

请求 – 正在发送的 PreparedRequest。
proxies – 方案或方案和主机到代理 URL 的字典。

返回类型:

str

send(request, stream=False, timeout=None, verify=True, cert=None, proxies=None)[source]¶

发送 PreparedRequest 对象。返回 Response 对象。

参数:

请求 – 正在发送的 PreparedRequest。
流 – （可选）是否流式传输请求内容。
超时 (float 或 tuple 或 urllib3 Timeout 对象) – (可选) 以浮点数或 (连接超时，读取超时) 元组形式指定放弃之前等待服务器发送数据的时长。
验证 – （可选）布尔值，在这种情况下，它控制我们是否验证服务器的 TLS 证书，或者是一个字符串，在这种情况下，它必须是所用 CA 捆绑包的路径
证书 – （可选）任何用户提供的受信任的 SSL 证书。
代理 – （可选）要应用于请求的代理字典。

返回类型:

requests.Response

认证¶

class requests.auth.AuthBase[source]¶: 所有认证实现派生的基类

class requests.auth.HTTPBasicAuth(username, password)[source]¶: 将 HTTP 基本认证附加到给定的请求对象。

class requests.auth.HTTPProxyAuth(username, password)[source]¶: 将 HTTP 代理认证附加到给定的请求对象。

class requests.auth.HTTPDigestAuth(username, password)[source]¶: 将 HTTP 摘要认证附加到给定的请求对象。

编码¶

requests.utils.get_encodings_from_content(content)[source]¶

从给定的内容字符串中返回编码。

参数:: content – 要从中提取编码的字节串。

requests.utils.get_encoding_from_headers(headers)[source]¶

从给定的 HTTP 头部字典中返回编码。

参数:: headers – 要从中提取编码的字典。
返回类型:: str

requests.utils.get_unicode_from_response(r)[source]¶

以 Unicode 形式返回请求的内容。

参数:: r – 从中获取 unicode 内容的响应对象。

已尝试

从内容类型中获取字符集
回退并替换所有 unicode 字符

返回类型:: str

Cookie¶

requests.utils.dict_from_cookiejar(cj)[source]¶

从 CookieJar 返回一个键/值字典。

参数:: cj – 要从中提取 Cookie 的 CookieJar 对象。
返回类型:: dict

requests.utils.add_dict_to_cookiejar(cj, cookie_dict)[source]¶

从键/值字典返回一个 CookieJar。

参数:

cj – 要向其中插入 Cookie 的 CookieJar。
cookie_dict – 要插入 CookieJar 的键/值字典。

返回类型:

CookieJar

requests.cookies.cookiejar_from_dict(cookie_dict, cookiejar=None, overwrite=True)[source]¶

从键/值字典返回一个 CookieJar。

参数:

cookie_dict – 要插入 CookieJar 的键/值字典。
cookiejar –（可选）要向其中添加 Cookie 的 Cookiejar。
overwrite –（可选）如果为 False，则不会用新的 Cookie 替换 Cookiejar 中已有的 Cookie。

返回类型:

CookieJar

class requests.cookies.RequestsCookieJar(policy=None)[source]¶

兼容性类；是一个 http.cookiejar.CookieJar，但公开了一个字典接口。

这是我们为未指定 CookieJar 的请求和会话默认创建的 CookieJar，因为某些客户端可能希望 response.cookies 和 session.cookies 支持字典操作。

Requests 在内部不使用字典接口；它只是为了与外部客户端代码兼容。所有请求代码都应该能直接与外部提供的 CookieJar 实例一起使用，例如 LWPCookieJar 和 FileCookieJar。

与常规 CookieJar 不同，此类是可序列化的。

警告

通常为 O(1) 的字典操作可能为 O(n)。

add_cookie_header(request)¶

向请求添加正确的 Cookie: 标头（urllib.request.Request 对象）。

除非 policy.hide_cookie2 为 true，否则还会添加 Cookie2 标头。

clear(domain=None, path=None, name=None)¶

清除一些 Cookie。

不带参数调用此方法将清除所有 Cookie。如果给定一个参数，则只删除属于该域的 Cookie。如果给定两个参数，则删除属于该域内指定路径的 Cookie。如果给定三个参数，则删除具有指定名称、路径和域的 Cookie。

如果不存在匹配的 Cookie，则引发 KeyError。

clear_expired_cookies()¶

丢弃所有已过期的 Cookie。

您可能不需要调用此方法：已过期的 Cookie 永远不会发送回服务器（前提是您使用 DefaultCookiePolicy），此方法会由 CookieJar 本身定期调用，而且 .save() 方法无论如何都不会保存已过期的 Cookie（除非您通过传递 true ignore_expires 参数另行要求）。

clear_session_cookies()¶

丢弃所有会话 Cookie。

请注意，.save() 方法无论如何都不会保存会话 Cookie，除非您通过传递 true ignore_discard 参数另行要求。

copy()[source]¶: 返回此 RequestsCookieJar 的副本。

extract_cookies(response, request)¶: 从响应中提取 Cookie，在给定请求的情况下允许提取。

get(name, default=None, domain=None, path=None)[source]¶: 类似于字典的 get()，它还支持可选的域和路径参数，以便解决在多个域上使用一个 Cookie Jar 导致的命名冲突。

警告

操作为 O(n)，而不是 O(1)。

get_dict(domain=None, path=None)[source]¶

以一个可选的域和路径作为参数，并返回一个满足要求的 cookie 的名称-值对的普通 Python 字典。

返回类型:: dict

get_policy()[source]¶: 返回使用的 CookiePolicy 实例。

items()[source]¶: 类似字典的 items()，它从 jar 中返回一个名称-值对元组列表。允许客户端代码调用 dict(RequestsCookieJar) 并获取一个键值对的普通 python 字典。

另请参阅

keys() 和 values()。

iteritems()[source]¶: 类似字典的 iteritems()，它从 jar 中返回一个名称-值对元组的迭代器。

另请参阅

iterkeys() 和 itervalues()。

iterkeys()[source]¶: 类似字典的 iterkeys()，它从 jar 中返回一个 cookie 名称的迭代器。

另请参阅

itervalues() 和 iteritems()。

itervalues()[source]¶: 类似字典的 itervalues()，它从 jar 中返回一个 cookie 值的迭代器。

另请参阅

iterkeys() 和 iteritems()。

keys()[source]¶: 类似字典的 keys()，它从 jar 中返回一个 cookie 名称列表。

另请参阅

values() 和 items()。

list_domains()[source]¶: 列出 jar 中所有域的实用方法。

list_paths()[source]¶: 列出 jar 中所有路径的实用方法。

make_cookies(response, request)¶: 返回从响应对象中提取的 Cookie 对象序列。

multiple_domains()[source]¶

如果 jar 中有多个域，则返回 True。否则返回 False。

返回类型:: bool

pop(k[, d]) → v, remove specified key and return the corresponding value.¶: 如果找不到 key，则返回 d（如果已提供），否则引发 KeyError。

popitem() → (k, v), remove and return some (key, value) pair¶: 作为 2 元组；但如果 D 为空，则引发 KeyError。

set(name, value, **kwargs)[source]¶: 类似于字典的 set()，还支持可选的 domain 和 path 参数，以便解决在多个域上使用一个 cookie jar 时出现的命名冲突。

set_cookie(cookie, *args, **kwargs)[source]¶: 设置 cookie，而不检查是否应该设置。

set_cookie_if_ok(cookie, request)¶: 如果策略允许，则设置 cookie。

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D¶

update(other)[source]¶: 使用另一个 CookieJar 或类似字典的对象更新此 jar

values()[source]¶: 类似于字典的 values()，它返回 jar 中 cookie 的值列表。

另请参阅

keys() 和 items()。

类 requests.cookies.CookieConflictError[源代码]¶

Cookie Jar 中有两个 Cookie 符合指定的条件。使用 .get 和 .set 并且包含 domain 和 path 参数以更具体。

add_note()¶: Exception.add_note(note) – 向异常添加注释

with_traceback()¶: Exception.with_traceback(tb) – 将 self.__traceback__ 设置为 tb 并返回 self。

状态代码查找¶

requests.codes¶: {} 的别名

codes 对象定义了一个映射，其中包含 HTTP 状态的常用名称及其数字代码，可以通过属性或字典项进行访问。

示例

>>> import requests
>>> requests.codes['temporary_redirect']
307
>>> requests.codes.teapot
418
>>> requests.codes['\o/']
200

某些代码具有多个名称，并且允许使用名称的大写和小写版本。例如，codes.ok、codes.OK 和 codes.okay 都对应于 HTTP 状态代码 200。

100: continue
101: switching_protocols
102: processing, early-hints
103: checkpoint
122: uri_too_long, request_uri_too_long
200: ok, okay, all_ok, all_okay, all_good, \o/, ✓
201: created
202: accepted
203: non_authoritative_info, non_authoritative_information
204: no_content
205: reset_content, reset
206: partial_content, partial
207: multi_status, multiple_status, multi_stati, multiple_stati
208: already_reported
226: im_used
300: multiple_choices
301: moved_permanently, moved, \o-
302: found
303: see_other, other
304: not_modified
305: use_proxy
306: switch_proxy
307: temporary_redirect, temporary_moved, temporary
308: permanent_redirect, resume_incomplete, resume
400: bad_request, bad
401: unauthorized
402: payment_required, payment
403: forbidden
404: not_found, -o-
405: method_not_allowed, not_allowed
406: not_acceptable
407: proxy_authentication_required, proxy_auth, proxy_authentication
408: request_timeout, timeout
409: conflict
410: gone
411: length_required
412: precondition_failed, precondition
413: request_entity_too_large, content_too_large
414: request_uri_too_large, uri_too_long
415: unsupported_media_type, unsupported_media, media_type
416: requested_range_not_satisfiable, requested_range, range_not_satisfiable
417: expectation_failed
418: im_a_teapot, teapot, i_am_a_teapot
421: misdirected_request
422: unprocessable_entity, unprocessable, unprocessable_content
423: locked
424: failed_dependency, dependency
425: unordered_collection, unordered, too_early
426: upgrade_required, upgrade
428: precondition_required, precondition
429: 请求过多, 过多
431: 标头字段过大, 字段过大
444: 无响应, 无
449: 重试, 重试
450: 被 Windows 家长控制阻止, 家长控制
451: 因法律原因不可用, 法律原因
499: 客户端关闭请求
500: 内部服务器错误, 服务器错误, /o\, ✗
501: 未实现
502: 错误网关
503: 服务不可用, 不可用
504: 网关超时
505: 不支持的 HTTP 版本, HTTP 版本
506: 变体也进行协商
507: 存储空间不足
509: 带宽限制超标, 带宽
510: 未扩展
511: 需要网络身份验证, 网络身份验证, 网络身份验证

迁移到 1.x¶

本部分详细介绍了 0.x 和 1.x 之间的主要差异，旨在减轻升级的痛苦。

API 更改¶

Response.json 现在是一个可调用对象，而不是响应的属性。

import requests
r = requests.get('https://api.github.com/events')
r.json()   # This *call* raises an exception if JSON decoding fails

Session API 已更改。会话对象不再采用参数。 Session 现在也大写，但为了向后兼容，它仍然可以用小写的 session 实例化。

s = requests.Session()    # formerly, session took parameters
s.auth = auth
s.headers.update(headers)
r = s.get('https://httpbin.org/headers')

除“response”之外，所有请求挂钩均已删除。
身份验证助手已拆分为单独的模块。请参阅 requests-oauthlib 和 requests-kerberos。

流请求的参数已从 prefetch 更改为 stream，并且逻辑已反转。此外， stream 现在是读取原始响应所必需的。

# in 0.x, passing prefetch=False would accomplish the same thing
r = requests.get('https://api.github.com/events', stream=True)
for chunk in r.iter_content(8192):
    ...

请求方法的 config 参数已删除。其中一些选项现在在 Session 上配置，例如保持活动状态和最大重定向次数。冗长选项应通过配置日志记录来处理。

import requests
import logging

# Enabling debugging at http.client level (requests->urllib3->http.client)
# you will see the REQUEST, including HEADERS and DATA, and RESPONSE with HEADERS but without DATA.
# the only thing missing will be the response.body which is not logged.
try: # for Python 3
    from http.client import HTTPConnection
except ImportError:
    from httplib import HTTPConnection
HTTPConnection.debuglevel = 1

logging.basicConfig() # you need to initialize logging, otherwise you will not see anything from requests
logging.getLogger().setLevel(logging.DEBUG)
requests_log = logging.getLogger("urllib3")
requests_log.setLevel(logging.DEBUG)
requests_log.propagate = True

requests.get('https://httpbin.org/headers')

许可¶

与 API 无关的一个关键差异是许可证从 ISC 许可证更改为 Apache 2.0 许可证。Apache 2.0 许可证确保对 Requests 的贡献也受 Apache 2.0 许可证的保护。

迁移到 2.x¶

与 1.0 版本相比，向后不兼容的更改相对较少，但仍有一些问题需要在此主要版本中注意。

有关此版本中更改的更多详细信息，包括新 API、相关 GitHub 问题链接以及一些错误修复，请阅读 Cory 在此主题上的博客。

API 更改¶

Requests 处理异常的方式有一些更改。 RequestException 现在是 IOError 的子类，而不是 RuntimeError，因为这更准确地对错误类型进行分类。此外，无效的 URL 转义序列现在会引发 RequestException 的子类，而不是 ValueError。
```
requests.get('http://%zz/')   # raises requests.exceptions.InvalidURL
```
最后，由不正确的分块编码引起的 httplib.IncompleteRead 异常现在会引发 Requests ChunkedEncodingError。

代理 API 已经略有更改。现在需要代理 URL 的方案。

proxies = {
  "http": "10.10.1.10:3128",    # use http://10.10.1.10:3128 instead
}

# In requests 1.x, this was legal, in requests 2.x,
#  this raises requests.exceptions.MissingSchema
requests.get("http://example.org", proxies=proxies)

行为更改¶

headers 字典中的键现在在所有 Python 版本中都是本机字符串，即 Python 2 中的字节字符串和 Python 3 中的 unicode。如果键不是本机字符串（Python 2 中的 unicode 或 Python 3 中的字节字符串），它们将转换为本机字符串类型，假设 UTF-8 编码。
headers 字典中的值应始终为字符串。自 1.0 之前，此项目一直坚持此立场，但最近的更改（自版本 2.11.0 起）对此进行了更严格的执行。建议尽可能避免将标头值作为 unicode 传递。

开发者界面¶

主界面¶

异常¶

请求会话¶

较低级别的类¶

更低级别的类¶

认证¶

编码¶

Cookie¶

状态代码查找¶

迁移到 1.x¶

API 更改¶

许可¶

迁移到 2.x¶

API 更改¶

行为更改¶

有用的链接

目录

相关主题