传输适配器

toolbelt 随附了几个不同的传输适配器，供您与请求一起使用。传输适配器全部保留在 requests_toolbelt.adapters 中，包括

FingerprintAdapter

0.4.0 版本中的新增功能。

默认情况下，requests 将验证服务器的证书以确保连接安全。除此之外，用户还可以提供他们期望接收的证书指纹。遗憾的是，requests API 不支持这种相当罕见的用例。当用户需要此额外验证时，他们应该使用 FingerprintAdapter 类来执行验证。

class requests_toolbelt.adapters.fingerprint.FingerprintAdapter(fingerprint, **kwargs)

Python Requests 的 HTTPS 适配器，用于验证证书指纹，而不是证书主机名。

示例用法

import requests
import ssl
from requests_toolbelt.adapters.fingerprint import FingerprintAdapter

twitter_fingerprint = '...'
s = requests.Session()
s.mount(
    'https://twitter.com',
    FingerprintAdapter(twitter_fingerprint)
)

指纹应作为十六进制字符串提供，可以选择包含冒号。

SSLAdapter

SSLAdapter 是 Cory Benfield 博客中提出的适配器的规范实现，此处。此适配器允许用户为传出 HTTPS 连接选择 Python 的 ssl 模块中提供的 SSL/TLS 协议之一。

原则上，这应该是没有必要的：兼容的 SSL 服务器应该能够协商所需的 SSL 版本。实际上，OpenSSL 的某些版本中存在错误，这意味着此协商不会按计划进行。能够简单地插入一个可以解决问题的传输适配器会很有用。

例如，假设您在使用为 GitHub 提供 TLS 的服务器时遇到困难。您可以使用以下代码解决此问题

from requests_toolbelt.adapters.ssl import SSLAdapter

import requests
import ssl

s = requests.Session()
s.mount('https://github.com/', SSLAdapter(ssl.PROTOCOL_TLSv1))

通过该适配器发出的任何未来的 GitHub 请求都将自动尝试协商 TLSv1，并且希望会成功。

class requests_toolbelt.adapters.ssl.SSLAdapter(ssl_version=None, **kwargs)

Python Requests 的 HTTPS 适配器，允许选择 Requests 协商的 SSL/TLS 版本。这可用于强制选择高安全 TLS 版本（在支持的情况下），或解决无法正确协商所提供的默认 TLS 版本的服务器故障问题。

示例用法

>>> import requests
>>> import ssl
>>> from requests_toolbelt import SSLAdapter
>>> s = requests.Session()
>>> s.mount('https://', SSLAdapter(ssl.PROTOCOL_TLSv1))

你可以用默认 Python SSL 模块中的任何可用协议替换所选协议。所有匹配适配器前缀的后续请求都将使用所选 SSL 版本，而不是默认版本。

此适配器还将尝试在使用代理时更改 Requests 协商的 SSL/TLS 版本。但是，这可能并不总是可行的：在 Requests v2.4.0 之前，适配器无法访问代理设置代码。在 Requests 的早期版本中，此适配器在与代理一起使用时将无法正常运行。

HostHeaderSSLAdapter

0.7.0 版中的新增功能。

Requests 默认支持 SSL 验证。但是，它依赖于用户使用包含主机名的 URL 发出请求。但是，如果用户需要使用 IP 地址发出请求，他们实际上无法针对他们想要请求的主机名验证证书。此适配器将 服务器名称指示 设置为 Host 头中的主机名，并针对该主机名验证证书。

为了满足这种非常罕见的需求，我们添加了 HostHeaderSSLAdapter。示例用法

import requests
from requests_toolbelt.adapters import host_header_ssl
s = requests.Session()
s.mount('https://', host_header_ssl.HostHeaderSSLAdapter())
s.get("https://93.184.216.34", headers={"Host": "example.org"})
class requests_toolbelt.adapters.host_header_ssl.HostHeaderSSLAdapter(pool_connections=10, pool_maxsize=10, max_retries=0, pool_block=False)

一个用于 Python Requests 的 HTTPS 适配器，它基于 Host 头设置证书验证的主机名。

这允许直接通过 HTTPS 请求 IP 地址，而不会收到“主机名不匹配”异常。

示例用法

>>> s.mount('https://', HostHeaderSSLAdapter())
>>> s.get("https://93.184.216.34", headers={"Host": "example.org"})

SourceAddressAdapter

0.3.0 版中的新增功能。

SourceAddressAdapter 允许用户为其连接指定源地址。

class requests_toolbelt.adapters.source.SourceAddressAdapter(source_address, **kwargs)

一个用于 Python Requests 的源地址适配器，它使你可以选择要绑定的本地地址。这允许你从特定接口和 IP 地址发送 HTTP 请求。

接受两种地址格式。第一个是字符串：这会将本地 IP 地址设置为字符串中给出的地址，还将为本地端口号选择一个半随机的高端口。

第二个是形式为 (ip 地址，端口) 的二元组：例如，('10.10.10.10', 8999)。这会将本地 IP 地址设置为第一个元素，将本地端口设置为第二个元素。如果 0 被用作端口号，则会选择一个半随机的高端口。

警告

在 Requests 中设置显式本地端口可能会对连接池产生负面影响：特别是，它有可能会出现“地址正在使用”错误。通常首选仅字符串参数，而不是元组形式。

示例用法

import requests
from requests_toolbelt.adapters.source import SourceAddressAdapter

s = requests.Session()
s.mount('http://', SourceAddressAdapter('10.10.10.10'))
s.mount('https://', SourceAddressAdapter(('10.10.10.10', 8999)))

SocketOptionsAdapter

0.4.0 版本中的新增功能。

注意

此适配器仅适用于 2.4.0 或更高版本的请求。在 2.4.0 之前的请求中，不存在设置任意套接字选项的功能。

SocketOptionsAdapter 允许用户在不进行子类化的前提下，在构造适配器时传递特定选项，以便在创建套接字时对其进行设置。该适配器利用 urllib3 的 支持 为每个 urllib3.connection.HTTPConnection（以及 HTTPSConnection）设置任意套接字选项。

要传递套接字选项，您需要发送一个由三项元组组成的列表。例如，requests 和 urllib3 默认情况下禁用 Nagle 算法。如果您需要重新启用它，请执行以下操作

import socket
import requests
from requests_toolbelt.adapters.socket_options import SocketOptionsAdapter

nagles = [(socket.IPPROTO_TCP, socket.TCP_NODELAY, 0)]
session = requests.Session()
for scheme in session.adapters.keys():
    session.mount(scheme, SocketOptionsAdapter(socket_options=nagles))

这将为使用该会话建立的所有 http:// 和 https:// 连接重新启用 Nagle 算法。

class requests_toolbelt.adapters.socket_options.SocketOptionsAdapter(**kwargs)

一个允许用户指定套接字选项的请求适配器。

从 2.4.0 版请求开始，可以指定一个自定义套接字选项列表，需要在建立连接之前设置这些选项。

示例用法

>>> import socket
>>> import requests
>>> from requests_toolbelt.adapters import socket_options
>>> s = requests.Session()
>>> opts = [(socket.IPPROTO_TCP, socket.TCP_NODELAY, 0)]
>>> adapter = socket_options.SocketOptionsAdapter(socket_options=opts)
>>> s.mount('http://', adapter)

您还可以利用此类上的默认选项列表，除了自定义选项之外，还可以继续使用原始选项。在这种情况下，opts 可能如下所示

>>> opts = socket_options.SocketOptionsAdapter.default_options + opts

TCPKeepAliveAdapter

0.4.0 版本中的新增功能。

注意

此适配器仅适用于 2.4.0 或更高版本的请求。在 2.4.0 之前的请求中，不存在设置任意套接字选项的功能。

TCPKeepAliveAdapter 允许用户传递特定与保持活动性相关的选项作为关键字参数以及任意套接字选项。

注意

不同的与保持活动性相关的套接字选项可能不适用于您的平台。检查套接字模块以了解以下常量的可用性

  • socket.TCP_KEEPIDLE

  • socket.TCP_KEEPCNT

  • socket.TCP_KEEPINTVL

该适配器将忽略为不存在的选项传递的任何选项。

适配器的示例用法

import requests
from requests_toolbelt.adapters.socket_options import TCPKeepAliveAdapter

session = requests.Session()
keep_alive = TCPKeepAliveAdapter(idle=120, count=20, interval=30)
session.mount('https://region-a.geo-1.compute.hpcloudsvc.com', keep_alive)
session.post('https://region-a.geo-1.compute.hpcloudsvc.com/v2/1234abcdef/servers',
             # ...
             )

在这种情况下，我们知道在 HP 公共云上创建服务器会导致请求在不使用 TCP 保持活动性的情况下挂起。因此，我们专门为该域挂载适配器，而不是将其添加到每个 https:// 和 http:// 请求中。

class requests_toolbelt.adapters.socket_options.TCPKeepAliveAdapter(**kwargs)

一个默认情况下启用 TCP 保持活动性的请求适配器。

适配器设置 4 个套接字选项

  • SOL_SOCKET SO_KEEPALIVE - 这会启用 TCP 保持活动

  • IPPROTO_TCP TCP_KEEPINTVL 20 - 设置保持活动间隔

  • IPPROTO_TCP TCP_KEEPCNT 5 - 设置保持活动探测次数

  • IPPROTO_TCP TCP_KEEPIDLE 60 - 如果套接字库具有 TCP_KEEPIDLE 常量，则设置保持活动时间

后三个可被关键字参数（分别）覆盖

  • interval

  • count

  • idle

你可以像这样使用此适配器

>>> from requests_toolbelt.adapters import socket_options
>>> tcp = socket_options.TCPKeepAliveAdapter(idle=120, interval=10)
>>> s = requests.Session()
>>> s.mount('http://', tcp)

X509Adapter

默认情况下，Requests 支持使用 .pem 格式的证书进行 SSL 验证。在某些情况下，需要将完整证书链作为请求的一部分传递，或者将证书解密为 .pem 文件被认为风险太大。

对于此类用例，我们创建了 X509Adapter。示例用法

import requests
from requests_toolbelt.adapters.x509 import X509Adapter
s = requests.Session()
a = X509Adapter(max_retries=3,
                cert_bytes=b'...', pk_bytes=b'...', encoding='...')
s.mount('https://', a)
class requests_toolbelt.adapters.x509.X509Adapter(*args, **kwargs)

用于 X.509 证书的适配器。

通过实现传输适配器接口，为 Requests 会话提供了一个接口，用于联系 HTTPS URL 并使用 X.509 证书进行身份验证。此类需要手动实例化并挂载到会话

参数:

  • pool_connections – 要缓存的 urllib3 连接池数。

  • pool_maxsize – 要保存在池中的最大连接数。

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

  • pool_block – 连接池是否应阻塞连接。

  • cert_bytes (bytes) – 包含使用 encoding 参数指定的编码的 cryptography.x509Certificate 对象内容的字节对象。

  • pk_bytes (bytes) – 包含使用 encoding 参数指定的编码的实现 cryptography.hazmat.primitives.serialization.PrivateFormat 的对象的字节对象。

  • password – 包含用于私钥的密码的字符串或 utf8 编码的字节。如果未加密，则为 None。默认为 None。

  • encoding – 详细说明对 cert_bytes 参数使用的编码方法的枚举。可以是 PEM 或 DER。默认为 PEM。

用法

>>> import requests
>>> from requests_toolbelt.adapters.x509 import X509Adapter
>>> s = requests.Session()
>>> a = X509Adapter(max_retries=3,
          cert_bytes=b'...', pk_bytes=b'...', encoding='...'
>>> s.mount('https://', a)