公用事业#

使用的有用方法 http.client ，完全从特定于 ULLIb3 .

就其核心而言，就像它的前身一样，urllib3构建在 http.client --包含在Python标准库中的最低级别的HTTP库。

的有限功能。 http.client 模块，urllib3提供了各种帮助器方法，这些帮助器方法与更高级别的组件一起使用，但也可以独立使用。

class urllib3.util.Retry(total=10, connect=None, read=None, redirect=None, status=None, other=None, allowed_methods=frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'}), status_forcelist=None, backoff_factor=0, backoff_max=120, raise_on_redirect=True, raise_on_status=True, history=None, respect_retry_after_header=True, remove_headers_on_redirect=frozenset({'Authorization'}), backoff_jitter=0.0)#

基类：object

重试配置。

每个重试尝试将创建具有更新值的新重试对象，因此可以安全地重用它们。

重试次数可以定义为池的默认设置：

retries = Retry(connect=5, read=2, redirect=5)
http = PoolManager(retries=retries)
response = http.request("GET", "https://example.com/")

或按请求(覆盖池的默认值)：

response = http.request("GET", "https://example.com/", retries=Retry(10))

重试可以通过传递 False ：

response = http.request("GET", "https://example.com/", retries=False)

错误将包含在 MaxRetryError 除非禁用重试，否则将引发引发异常。

参数:

total (int) -- 允许的重试总数。优先于其他计数。设置为 None 取消这一限制并求助于其他方面。设置为 0 在第一次重试时失败。设置为 False 禁用并暗示 raise_on_redirect=False 。
connect (int) -- 要重试的连接相关错误数。这些是在将请求发送到远程服务器之前引发的错误，我们假定该服务器没有触发服务器来处理该请求。设置为 0 在这种类型的第一次重试时失败。
read (int) -- 读取错误时重试多少次。这些错误是在请求发送到服务器后提出的，因此请求可能会产生副作用。设置为 0 在这种类型的第一次重试时失败。
redirect (int) -- 要执行的重定向数。限制它以避免无限的重定向循环。重定向是状态代码为301、302、303、307或308的http响应。设置为 0 在这种类型的第一次重试时失败。设置为 False 使无效并暗示 raise_on_redirect=False .
status (int) -- 在错误状态代码上重试多少次。这些是对响应的重试，其中状态代码匹配 status_forcelist . 设置为 0 在这种类型的第一次重试时失败。
other (int) -- 对其他错误重试的次数。其他错误是不是连接、读取、重定向或状态错误的错误。这些错误可能在请求发送到服务器之后引发，因此请求可能会有副作用。设置为 0 在此类型的第一次重试时失败。如果 total 未设置，则最好将其设置为0，以考虑意外的边缘情况并避免无限重试循环。
allowed_methods (Collection) -- 我们应该重试的一组评分较高的HTTP方法谓词。默认情况下，我们只在被认为是幂等的方法上重试(具有相同参数的多个请求以相同的状态结束)。看见 Retry.DEFAULT_ALLOWED_METHODS 。设置为 None 值以重试任何谓词。
status_forcelist (Collection) -- 我们应该强制重试的一组整数HTTP状态代码。如果请求方法在 allowed_methods 并且响应状态代码在 status_forcelist 。默认情况下，这是禁用的 None 。
backoff_factor (float) --
在第二次尝试之后，在两次尝试之间应用的退避系数（大多数错误都会立即通过第二次尝试解决，不会延迟）。urllib3将睡眠时间：
```
{backoff factor} * (2 ** ({number of previous retries}))
```
几秒钟。如果 backoff_jitter 为非零，则此休眠延长：：
```
random.uniform(0, {backoff jitter})
```
几秒钟。例如，如果Backoff_factor为0.1，则 Retry.sleep() 会睡上几个小时 [0.0s, 0.2s, 0.4s, 0.8s, ...] 两次重试之间。任何退避都不会比 backoff_max 。

默认情况下，回退处于禁用状态(系数设置为0)。
raise_on_redirect (bool) -- 如果重定向次数已用尽，是否引发MaxRetryerror，或返回响应代码在3xx范围内的响应。
raise_on_status (bool) -- 类似于 raise_on_redirect ：如果状态为 status_forcelist 范围和重试次数已用尽。
history (tuple) -- 每次调用时遇到的请求的历史记录 increment() . 列表按请求发生的顺序排列。每个列表项都属于类 RequestHistory .
respect_retry_after_header (bool) -- 是否尊重定义为的状态代码上的retry after头 Retry.RETRY_AFTER_STATUS_CODES 或者没有。
remove_headers_on_redirect (Collection) -- 在触发重定向请求之前返回指示重定向的响应时从请求中删除的头序列。
backoff_max (float) --
backoff_jitter (float) --

DEFAULT_ALLOWED_METHODS = frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'})#: 要用于的默认方法 allowed_methods

DEFAULT_BACKOFF_MAX = 120#: 默认最大退避时间。

DEFAULT_REMOVE_HEADERS_ON_REDIRECT = frozenset({'Authorization'})#: 要用于的默认标头 remove_headers_on_redirect

RETRY_AFTER_STATUS_CODES = frozenset({413, 429, 503})#: 要用于的默认状态代码 status_forcelist

classmethod from_int(retries, redirect=True, default=None)#

旧重试格式的向后兼容性。

参数:

retries (Retry | bool | int | None) --
redirect (bool | int | None) --
default (Retry | bool | int | None) --

返回类型:

Retry

get_backoff_time()#

计算电流回退的公式

返回类型:: float

get_retry_after(response)#

在秒后获取重试的值。

参数:: response (BaseHTTPResponse) --
返回类型:: float | None

increment(method=None, url=None, response=None, error=None, _pool=None, _stacktrace=None)#

返回一个带有递增重试计数器的新重试对象。

参数:

response (BaseHTTPResponse) -- 如果服务器未返回响应，则返回响应对象或无。
error (Exception) -- 请求中遇到的错误，或者如果成功接收响应，则没有错误。
method (str | None) --
url (str | None) --
_pool (ConnectionPool | None) --
_stacktrace (TracebackType | None) --

返回:

一个新的 Retry 对象。

返回类型:

Retry

is_exhausted()#

我们没有重试了吗？

返回类型:: bool

is_retry(method, status_code, has_retry_after=False)#

此方法/状态代码是否可重试？(基于允许列表和控制变量，例如允许的总重试次数、是否尊重Rtry-After标头、该标头是否存在、以及返回的状态代码是否在存在前述标头时要重试的状态代码列表上)

参数:

method (str) --
status_code (int) --
has_retry_after (bool) --

返回类型:

bool

sleep(response=None)#

在重试之间睡眠。

此方法将尊重服务器的 Retry-After 响应头和睡眠请求的持续时间。如果不存在，它将使用指数退避。默认情况下，退避因子为0，此方法将立即返回。

参数:: response (BaseHTTPResponse | None) --
返回类型:: None

class urllib3.util.SSLContext(protocol=None, *args, **kwargs)#

基类：_SSLContext

sslcontext包含各种与ssl相关的配置选项和数据，例如证书和可能的私钥。

sslobject_class#: SSLObject 的别名

sslsocket_class#: SSLSocket 的别名

class urllib3.util.Timeout(total=None, connect=_TYPE_DEFAULT.token, read=_TYPE_DEFAULT.token)#

基类：object

超时配置。

可以将超时定义为池的默认值：

import urllib3

timeout = urllib3.util.Timeout(connect=2.0, read=7.0)

http = urllib3.PoolManager(timeout=timeout)

resp = http.request("GET", "https://example.com/")

print(resp.status)

或按请求(覆盖池的默认值)：

response = http.request("GET", "https://example.com/", timeout=Timeout(10))

通过将所有参数设置为，可以禁用超时 None ：

no_timeout = Timeout(connect=None, read=None)
response = http.request("GET", "https://example.com/", timeout=no_timeout)

参数:

total (int, float, or None) -- 这将连接和读取超时合并为一个；读取超时将设置为连接尝试剩余的时间。如果同时指定了连接超时和总计，或者指定了读取超时和总计，则将应用较短的超时。默认为无。
connect (int, float, or None) -- 等待与服务器的连接尝试成功的最长时间（秒）。省略该参数可能会将连接超时默认为系统默认值 the global default timeout in socket.py . 无将设置连接尝试的无限超时。
read (int, float, or None) -- 在连续读取操作之间等待来自服务器的响应的最长时间（秒）。省略该参数可能会将读取超时默认为系统默认值 the global default timeout in socket.py . 没有人会设置无限超时。

备注

许多因素会影响URLILB3返回HTTP响应的总时间。

例如，python的dns解析器不遵守套接字上指定的超时。影响总请求时间的其他因素包括高CPU负载、高交换、低优先级运行的程序或其他行为。

此外，读取超时和总超时仅测量连接客户端和服务器的套接字上的读取操作之间的时间，而不是请求返回完整响应的总时间。对于大多数请求，由于服务器在指定时间内未发送第一个字节，因此会引发超时。情况并非总是如此；如果服务器每15秒传输一个字节，则不会触发20秒的超时，即使请求需要几分钟才能完成。

如果您的目标是在设置的挂钟时间后切断任何请求，请考虑使用第二个“watcher”线程来切断慢请求。

DEFAULT_TIMEOUT: float | _TYPE_DEFAULT | None = -1#: 表示默认超时值的sentinel对象

clone()#

创建超时对象的副本

每个池存储超时属性，但每个请求都需要一个新的超时对象，以确保每个请求都配置了自己的启动/停止。

返回:: Timeout对象的副本
返回类型:: Timeout

property connect_timeout: float | _TYPE_DEFAULT | None#

获取设置连接超时时要使用的值。

这将是一个正浮点数或整数、值none（永不超时）或默认系统超时。

返回:: 连接超时。
返回类型:: int，浮动， Timeout.DEFAULT_TIMEOUT 或无

classmethod from_float(timeout)#

从旧超时值创建新超时。

httplib.py使用的超时值在connect（）和recv（）套接字请求上设置相同的超时。这将创建 Timeout 对象，该对象将单个超时设置为 timeout 传递给此函数的值。

参数:: timeout (integer, float, urllib3.util.Timeout.DEFAULT_TIMEOUT, or None) -- 传统超时值。
返回:: 超时对象
返回类型:: Timeout

get_connect_duration()#

获取自调用 start_connect() .

返回:: 以秒为单位的运行时间。
返回类型:: float
抛出:: urllib3.exceptions.TimeoutStateError -- 如果试图获取尚未启动的计时器的持续时间。

property read_timeout: float | None#

获取读取超时的值。

这假设连接超时已过一段时间，并相应地计算读取超时。

如果设置了self.total，则读取超时取决于连接超时所花费的时间。如果尚未建立连接时间，则 TimeoutStateError 将被提升。

返回:: 用于读取超时的值。
返回类型:: int, float or None
抛出:: urllib3.exceptions.TimeoutStateError -- 如果 start_connect() 尚未对此对象调用。

start_connect()#

启动超时时钟，在connect（）尝试期间使用

抛出:: urllib3.exceptions.TimeoutStateError -- 如果试图启动已经启动的计时器。
返回类型:: float

class urllib3.util.Url(scheme=None, auth=None, host=None, port=None, path=None, query=None, fragment=None)#

基类：Url

用于表示http url的数据结构。用作的返回值 parse_url() . 根据rfc 3986，方案和主机都是规范化的，因为它们都不区分大小写。

参数:

scheme (str | None) --
auth (str | None) --
host (str | None) --
port (int | None) --
path (str | None) --
query (str | None) --
fragment (str | None) --

property authority: str | None#

RFC 3986 3.2中定义的授权组件。这包括用户信息(身份验证)、主机和端口。

即: 用户名@主机：端口

property hostname: str | None#: 与urlparse向后兼容。我们这样很好。

property netloc: str | None#

网络位置，包括主机和端口。

如果您需要与urllib.parse的 netloc ，请使用 authority 属性而不是。

property request_uri: str#: 包含查询字符串的绝对路径。

property url: str#

将self转换为url

此功能或多或少应与 parse_url() . 返回的url可能与输入到的url不完全相同 parse_url() ，但它应该与rfc等价（例如，具有空端口的url将具有：removed）。

例子：

import urllib3

U = urllib3.util.parse_url("https://google.com/mail/")

print(U.url)
# "https://google.com/mail/"

print( urllib3.util.Url("https", "username:password",
                        "host.com", 80, "/path", "query", "fragment"
                        ).url
    )
# "https://username:password@host.com:80/path?query#fragment"

urllib3.util.assert_fingerprint(cert, fingerprint)#

检查给定的指纹是否与提供的证书匹配。

参数:

cert (bytes | None) -- 作为字节对象的证书。
fingerprint (str) -- 指纹作为六位数的字符串，可以用冒号散布。

返回类型:

None

urllib3.util.create_urllib3_context(ssl_version=None, cert_reqs=None, options=None, ciphers=None, ssl_minimum_version=None, ssl_maximum_version=None)#

创建和配置 ssl.SSLContext 与urllib3一起使用的实例。

参数:

ssl_version (int | None) -- 要使用的所需协议版本。这将默认为PROTOCOL_SSLv23，它将协商服务器和您的OpenSSL安装都支持的最高协议。此参数已弃用，请改用‘SSL_MINIMUM_VERSION’。
ssl_minimum_version (int | None) -- 要使用的TLS的最低版本。使用‘ssl.TLSVersion’枚举指定值。
ssl_maximum_version (int | None) -- 要使用的TLS的最高版本。使用‘ssl.TLSVersion’枚举指定值。不建议设置为默认值‘ssl.TLSVersion.MAXIMUM_SUPPORTED’以外的任何值。
cert_reqs (int | None) -- 是否需要证书验证。该默认为 ssl.CERT_REQUIRED 。
options (int | None) -- 特定的OpenSSL选项。这些默认设置为 ssl.OP_NO_SSLv2 ， ssl.OP_NO_SSLv3 ， ssl.OP_NO_COMPRESSION ，以及 ssl.OP_NO_TICKET 。
ciphers (str | None) -- 允许服务器选择哪些密码套件。如果OpenSSL 1.1.1+，则默认为任一系统配置的密码，否则使用一组安全的默认密码。

返回:

使用指定选项构造了SSLContext对象

返回类型:

SSLContext

urllib3.util.is_connection_dropped(conn)#

如果连接已断开并应关闭，则返回True。 :param conn: urllib3.connection.HTTPConnection 对象。

参数:: conn (BaseHTTPConnection) --
返回类型:: bool

urllib3.util.is_fp_closed(obj)#

检查给定的类文件对象是否已关闭。

参数:: obj (object) -- 要检查的类似文件的对象。
返回类型:: bool

urllib3.util.make_headers(keep_alive=None, accept_encoding=None, user_agent=None, basic_auth=None, proxy_basic_auth=None, disable_cache=None)#

生成请求头的快捷方式。

参数:

keep_alive (bool | None) -- 如果 True ，添加“connection:keep alive”标题。
accept_encoding (bool | list[str] | str | None) -- 可以是布尔值、列表或字符串。 True 翻译过来就是‘gZip，eflate’。如果不是 brotli 或 brotlicffi 安装的程序包是‘gzip，deflate，br’。列表将以逗号连接。字符串将按照提供的方式使用。
user_agent (str | None) -- 表示所需用户代理的字符串，例如“python-urllib3/0.6”
basic_auth (str | None) -- 冒号分隔的用户名：“authorization:basic…”身份验证标题的密码字符串。
proxy_basic_auth (str | None) -- 冒号分隔的用户名：“代理授权：基本…”身份验证头的密码字符串。
disable_cache (bool | None) -- 如果 True ，添加“缓存控制：无缓存”头。

返回类型:

dict[str, str]

例子：

import urllib3

print(urllib3.util.make_headers(keep_alive=True, user_agent="Batman/1.0"))
# {'connection': 'keep-alive', 'user-agent': 'Batman/1.0'}
print(urllib3.util.make_headers(accept_encoding=True))
# {'accept-encoding': 'gzip,deflate'}

urllib3.util.parse_url(url)#

在给定URL的情况下，返回已解析的 Url 命名元组。尽最大努力解析不完整的URL。未提供的字段将为无。该解析器与RFC 3986和RFC 6874兼容。

解析器逻辑和helper函数主要基于 rfc3986 模块。

参数:: url (str) -- 解析为 Url 命名元组。
返回类型:: Url

部分向后兼容 urllib.parse 。

例子：

import urllib3

print( urllib3.util.parse_url('http://google.com/mail/'))
# Url(scheme='http', host='google.com', port=None, path='/mail/', ...)

print( urllib3.util.parse_url('google.com:80'))
# Url(scheme=None, host='google.com', port=80, path=None, ...)

print( urllib3.util.parse_url('/foo?bar'))
# Url(scheme=None, host=None, port=None, path='/foo', query='bar', ...)

urllib3.util.resolve_cert_reqs(candidate)#

将参数解析为数值常量，该数值常量可以从SSL模块传递到WrAPHSoCultFult/方法。默认为 ssl.CERT_REQUIRED . 如果给定一个字符串，则假定它是 ssl 模块或其缩写。（所以你可以指定 REQUIRED 而不是 CERT_REQUIRED . 如果两者都不是 None 我们也假定它已经是数字常量，可以直接传递给WrAPHSoCK。

参数:: candidate (None | int | str) --
返回类型:: VerifyMode

urllib3.util.resolve_ssl_version(candidate)#

比如解决证书需求

参数:: candidate (None | int | str) --
返回类型:: int

urllib3.util.ssl_wrap_socket(sock, keyfile=None, certfile=None, cert_reqs=None, ca_certs=None, server_hostname=None, ssl_version=None, ciphers=None, ssl_context=None, ca_cert_dir=None, key_password=None, ca_cert_data=None, tls_in_tls=False)#

除了服务器主机名、ssl上下文和ca_cert_dir之外的所有参数都具有与使用时相同的含义 ssl.wrap_socket() .

参数:

server_hostname (str | None) -- 支持sni时，证书的预期主机名
ssl_context (ssl.SSLContext | None) -- 预制的 SSLContext 对象。如果没有提供，则将使用 create_urllib3_context() .
ciphers (str | None) -- 我们希望客户支持的一系列密码。
ca_cert_dir (str | None) -- 在多个独立文件中包含CA证书的目录，由OpenSSL的-capath标志或sslcontext.load_verify_locations（）的capath参数支持。
key_password (str | None) -- 如果密钥文件已加密，则为可选密码。
ca_cert_data (None | str | bytes) -- 可选字符串，包含PEM格式的CA证书，适合作为cadata参数传递给SSLContext.load_Verify_Locations()
tls_in_tls (bool) -- 使用SSLTransport包装现有套接字。
sock (socket.socket) --
keyfile (str | None) --
certfile (str | None) --
cert_reqs (int | None) --
ca_certs (str | None) --
ssl_version (int | None) --

返回类型:

ssl.SSLSocket | SSLTransportType

urllib3.util.wait_for_read(sock, timeout=None)#

等待给定套接字上的读取可用。如果套接字可读，则返回true；如果超时，则返回false。

参数:

sock (socket) --
timeout (float | None) --

返回类型:

bool

urllib3.util.wait_for_write(sock, timeout=None)#

等待给定套接字上的写入可用。如果套接字可读，则返回true；如果超时，则返回false。

参数:

sock (socket) --
timeout (float | None) --

返回类型:

bool