urllib3
1.20

urllib3.contrib package

These modules implement various extra features, that may not be ready for prime time or that require optional third-party dependencies.

urllib3.contrib.appengine module

urllib3.contrib.ntlmpool module

urllib3.contrib.pyopenssl module

Module for using pyOpenSSL as a TLS backend. This module was relevant before the standard library ssl module supported SNI, but now that we’ve dropped support for Python 2.7 all relevant Python versions support SNI so this module is no longer recommended.

This needs the following packages installed:

However, pyOpenSSL depends on cryptography, which depends on idna, so while we use all three directly here we end up having relatively few packages required.

You can install them with the following command:

$ python -m pip install pyopenssl cryptography idna

To activate certificate checking, call inject_into_urllib3() from your Python code before you begin making HTTP requests. This can be done in a sitecustomize module, or at any other time before your application begins using urllib3, like this:

try:
    import urllib3.contrib.pyopenssl
    urllib3.contrib.pyopenssl.inject_into_urllib3()
except ImportError:
    pass
urllib3.contrib.pyopenssl.extract_from_urllib3() → None[source]

Undo monkey-patching by inject_into_urllib3().

urllib3.contrib.pyopenssl.inject_into_urllib3() → None[source]

Monkey-patch urllib3 with PyOpenSSL-backed SSL-support.

urllib3.contrib.socks module

This module contains provisional support for SOCKS proxies from within urllib3. This module supports SOCKS4, SOCKS4A (an extension of SOCKS4), and SOCKS5. To enable its functionality, either install PySocks or install this module with the socks extra.

The SOCKS implementation supports the full range of urllib3 features. It also supports the following SOCKS features:

  • SOCKS4A (proxy_url='socks4a://...)

  • SOCKS4 (proxy_url='socks4://...)

  • SOCKS5 with remote DNS (proxy_url='socks5h://...)

  • SOCKS5 with local DNS (proxy_url='socks5://...)

  • Usernames and passwords for the SOCKS proxy

Note

It is recommended to use socks5h:// or socks4a:// schemes in your proxy_url to ensure that DNS resolution is done from the remote server instead of client-side when connecting to a domain name.

SOCKS4 supports IPv4 and domain names with the SOCKS4A extension. SOCKS5 supports IPv4, IPv6, and domain names.

When connecting to a SOCKS4 proxy the username portion of the proxy_url will be sent as the userid section of the SOCKS request:

proxy_url="socks4a://<userid>@proxy-host"

When connecting to a SOCKS5 proxy the username and password portion of the proxy_url will be sent as the username/password to authenticate with the proxy:

proxy_url="socks5h://<username>:<password>@proxy-host"
class urllib3.contrib.socks.SOCKSConnection(_socks_options: _TYPE_SOCKS_OPTIONS, *args: Any, **kwargs: Any)[source]

Bases: HTTPConnection

A plain-text HTTP connection that connects via a SOCKS proxy.

class urllib3.contrib.socks.SOCKSHTTPConnectionPool(host: str, port: int | None = None, timeout: Timeout | float | _TYPE_DEFAULT | None = _TYPE_DEFAULT.token, maxsize: int = 1, block: bool = False, headers: Mapping[str, str] | None = None, retries: Retry | bool | int | None = None, _proxy: Url | None = None, _proxy_headers: Mapping[str, str] | None = None, _proxy_config: ProxyConfig | None = None, **conn_kw: Any)[source]

Bases: HTTPConnectionPool

ConnectionCls

alias of SOCKSConnection

class urllib3.contrib.socks.SOCKSHTTPSConnection(_socks_options: _TYPE_SOCKS_OPTIONS, *args: Any, **kwargs: Any)[source]

Bases: SOCKSConnection, HTTPSConnection

class urllib3.contrib.socks.SOCKSHTTPSConnectionPool(host: str, port: int | None = None, timeout: _TYPE_TIMEOUT | None = _TYPE_DEFAULT.token, maxsize: int = 1, block: bool = False, headers: Mapping[str, str] | None = None, retries: Retry | bool | int | None = None, _proxy: Url | None = None, _proxy_headers: Mapping[str, str] | None = None, key_file: str | None = None, cert_file: str | None = None, cert_reqs: int | str | None = None, key_password: str | None = None, ca_certs: str | None = None, ssl_version: int | str | None = None, ssl_minimum_version: ssl.TLSVersion | None = None, ssl_maximum_version: ssl.TLSVersion | None = None, assert_hostname: str | Literal[False] | None = None, assert_fingerprint: str | None = None, ca_cert_dir: str | None = None, **conn_kw: Any)[source]

Bases: HTTPSConnectionPool

ConnectionCls

alias of SOCKSHTTPSConnection

class urllib3.contrib.socks.SOCKSProxyManager(proxy_url: str, username: str | None = None, password: str | None = None, num_pools: int = 10, headers: Mapping[str, str] | None = None, **connection_pool_kw: Any)[source]

Bases: PoolManager

A version of the urllib3 ProxyManager that routes connections via the defined SOCKS proxy.

pool_classes_by_scheme = {'http': <class 'urllib3.contrib.socks.SOCKSHTTPConnectionPool'>, 'https': <class 'urllib3.contrib.socks.SOCKSHTTPSConnectionPool'>}