公用事业

使用的有用方法 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, method_whitelist=frozenset({'DELETE', 'GET', 'HEAD', 'OPTIONS', 'PUT', 'TRACE'}), status_forcelist=None, backoff_factor=0, raise_on_redirect=True, raise_on_status=True, history=None, respect_retry_after_header=True, remove_headers_on_redirect=frozenset({'Authorization'}))

基类:object

重试配置。

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

重试可以定义为池的默认值:

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

或每个请求(覆盖池的默认值):

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

可以通过重试禁用重试。 False ::

response = http.request('GET', 'http://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 在这种类型的第一次重试时失败。

  • method_whitelist (iterable) -- 一组大写的http方法谓词,我们应在其上重试。默认情况下,我们只对被认为是等幂的方法重试(具有相同参数的多个请求以相同状态结束)。见 Retry.DEFAULT_METHOD_WHITELIST . 设置为 False 对任何谓词重试的值。

  • status_forcelist (iterable) -- 一组整数http状态代码,我们应该强制对其重试。如果请求方法处于 method_whitelist 并且响应状态代码在 status_forcelist . 默认情况下,这是禁用的 None .

  • backoff_factor (float) --

    在第二次尝试之后,在两次尝试之间应用的退避系数(大多数错误都会立即通过第二次尝试解决,不会延迟)。urllib3将睡眠时间:

    {backoff factor} * (2 ** ({number of total retries} - 1))
    

    秒。如果退避系数为0.1,则 sleep() 会睡觉的 [0.0秒,0.2秒,0.4秒,…] 两次重试之间。不会超过 Retry.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 (iterable) -- 在触发重定向请求之前返回指示重定向的响应时从请求中删除的头序列。

BACKOFF_MAX = 120

最长退避时间。

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

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

get_backoff_time()

计算电流回退的公式

返回类型

float

get_retry_after(response)

在秒后获取重试的值。

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

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

参数
  • response (HTTPResponse) -- 如果服务器未返回响应,则返回响应对象或无。

  • error (Exception) -- 请求中遇到的错误,或者如果成功接收响应,则没有错误。

返回

一个新的 Retry 对象。

is_exhausted()

我们没有重试了吗?

is_retry(method, status_code, has_retry_after=False)

此方法/状态代码是否可重试?(基于白名单和控制变量,例如允许的总重试次数、是否尊重重试后报头、此报头是否存在,以及返回的状态代码是否在出现上述报头时要重试的状态代码列表中)

sleep(response=None)

在重试之间睡眠。

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

class urllib3.util.SSLContext(protocol=<_SSLMethod.PROTOCOL_TLS: 2>, *args, **kwargs)

基类:_ssl._SSLContext

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

sslobject_class

SSLObject 的别名

sslsocket_class

SSLSocket 的别名

class urllib3.util.Timeout(total=None, connect=<object object>, read=<object object>)

基类:object

超时配置。

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

timeout = Timeout(connect=2.0, read=7.0)
http = PoolManager(timeout=timeout)
response = http.request('GET', 'http://example.com/')

或每个请求(覆盖池的默认值):

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

可以通过设置所有参数来禁用超时。 None ::

no_timeout = Timeout(connect=None, read=None)
response = http.request('GET', 'http://example.com/, timeout=no_timeout)
参数
  • total (integer, float, or None) -- 这将连接和读取超时合并为一个;读取超时将设置为连接尝试剩余的时间。如果同时指定了连接超时和总计,或者指定了读取超时和总计,则将应用较短的超时。默认为无。

  • connect (integer, float, or None) -- 等待与服务器的连接尝试成功的最长时间(秒)。省略该参数可能会将连接超时默认为系统默认值 the global default timeout in socket.py . 无将设置连接尝试的无限超时。

  • read (integer, float, or None) -- 在连续读取操作之间等待来自服务器的响应的最长时间(秒)。省略该参数可能会将读取超时默认为系统默认值 the global default timeout in socket.py . 没有人会设置无限超时。

注解

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

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

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

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

DEFAULT_TIMEOUT = <object object>

表示默认超时值的sentinel对象

clone()

创建超时对象的副本

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

返回

Timeout对象的副本

返回类型

Timeout

property connect_timeout

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

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

返回

连接超时。

返回类型

int,浮动, Timeout.DEFAULT_TIMEOUT 或无

classmethod from_float(timeout)

从旧超时值创建新超时。

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

参数

timeout (integer, float, sentinel default object, or None) -- 传统超时值。

返回

超时对象

返回类型

Timeout

get_connect_duration()

获取自调用 start_connect() .

返回

以秒为单位的运行时间。

返回类型

float

引发

urllib3.exceptions.TimeoutStateError -- 如果试图获取尚未启动的计时器的持续时间。

property read_timeout

获取读取超时的值。

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

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

返回

用于读取超时的值。

返回类型

int,浮动, Timeout.DEFAULT_TIMEOUT 或无

引发

urllib3.exceptions.TimeoutStateError -- 如果 start_connect() 尚未对此对象调用。

start_connect()

启动超时时钟,在connect()尝试期间使用

引发

urllib3.exceptions.TimeoutStateError -- 如果试图启动已经启动的计时器。

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

基类:urllib3.util.url.Url

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

property hostname

与urlparse向后兼容。我们这样很好。

property netloc

网络位置,包括主机和端口

property request_uri

包含查询字符串的绝对路径。

property url

将self转换为url

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

例子::

>>> U = parse_url('http://google.com/mail/')
>>> U.url
'http://google.com/mail/'
>>> Url('http', 'username:password', 'host.com', 80,
... '/path', 'query', 'fragment').url
'http://username:password@host.com:80/path?query#fragment'
urllib3.util.assert_fingerprint(cert, fingerprint)

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

参数
  • cert -- 作为字节对象的证书。

  • fingerprint -- 指纹作为六位数的字符串,可以用冒号散布。

urllib3.util.current_time()

单调的

单调的时钟,不能倒转。

urllib3.util.get_host(url)

不赞成的使用 parse_url() 相反。

urllib3.util.is_connection_dropped(conn)

如果连接已断开并应关闭,则返回true。

参数

conn -- httplib.HTTPConnection 对象。

注意:对于appengine这样的平台,这将始终返回 False 让平台为我们透明地处理连接回收。

urllib3.util.is_fp_closed(obj)

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

参数

obj -- 要检查的类似文件的对象。

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 -- 如果 True ,添加“connection:keep alive”标题。

  • accept_encoding -- 可以是布尔型、列表或字符串。 True 翻译成“gzip,deflate”。列表将以逗号连接。字符串将按规定使用。

  • user_agent -- 表示所需用户代理的字符串,例如“python-urllib3/0.6”

  • basic_auth -- 冒号分隔的用户名:“authorization:basic…”身份验证标题的密码字符串。

  • proxy_basic_auth -- 冒号分隔的用户名:“代理授权:基本…”身份验证头的密码字符串。

  • disable_cache -- 如果 True ,添加“缓存控制:无缓存”头。

例子::

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

给定一个url,返回一个解析的 Url 命名元组。尽最大努力解析不完整的url。未提供的字段将为“无”。这个解析器符合rfc 3986。

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

参数

url (str) -- 解析为 Url 命名元组。

部分向后兼容 urlparse .

例子::

>>> parse_url('http://google.com/mail/')
Url(scheme='http', host='google.com', port=None, path='/mail/', ...)
>>> parse_url('google.com:80')
Url(scheme=None, host='google.com', port=80, path=None, ...)
>>> 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。

urllib3.util.resolve_ssl_version(candidate)

比如解决证书需求

urllib3.util.split_first(s, delims)

1.25 版后已移除.

给定一个字符串和一个iterable分隔符,在找到的第一个分隔符上拆分。返回两个拆分部分和匹配的分隔符。

如果找不到,则第一部分是完整的输入字符串。

例子::

>>> split_first('foo/bar?baz', '?/=')
('foo', 'bar?baz', '/')
>>> split_first('foo/bar?baz', '123')
('foo/bar?baz', '', None)

与熟食店的数量成线性关系。不是很多熟食店的理想选择。

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)

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

参数
  • server_hostname -- 支持sni时,证书的预期主机名

  • ssl_context -- 预制的 SSLContext 对象。如果没有提供,则将使用 create_urllib3_context() .

  • ciphers -- 我们希望客户支持的一系列密码。

  • ca_cert_dir -- 在多个独立文件中包含CA证书的目录,由OpenSSL的-capath标志或sslcontext.load_verify_locations()的capath参数支持。

  • key_password -- 如果密钥文件已加密,则为可选密码。

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

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

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

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