2.0.0a1

Read the v2.0 migration guide for help upgrading to the latest version of urllib3!

Added

• Added type hints to the urllib3 module (#1897).
• Added ssl_minimum_version and ssl_maximum_version options which set
  SSLContext.minimum_version and SSLContext.maximum_version (#2110).
• Added support for Zstandard (RFC 8878) when zstandard 1.18.0 or later is installed.
  Added the zstd extra which installs the zstandard package (#1992).
• Added urllib3.response.BaseHTTPResponse class. All future response classes will be subclasses of BaseHTTPResponse (#2083).
• Added top-level urllib3.request function which uses a preconfigured module-global PoolManager instance (#2150).
• Added FullPoolError which is raised when PoolManager(block=True) and a connection is returned to a full pool (#2197).
• Added HTTPHeaderDict to the top-level urllib3 namespace (#2216).
• Added the json parameter to urllib3.request(), PoolManager.request(), and ConnectionPool.request() methods to send JSON bodies in requests. Using this parameter will set the header Content-Type: application/json if Content-Type isn't already defined.
  Added support for parsing JSON response bodies with HTTPResponse.json() method (#2243).
• Added support for configuring header merging behavior with HTTPHeaderDict
  When using a HTTPHeaderDict to provide headers for a request, by default duplicate
  header values will be repeated. But if combine=True is passed into a call to
  HTTPHeaderDict.add, then the added header value will be merged in with an existing
  value into a comma-separated list (X-My-Header: foo, bar) (#2242).
• Added NameResolutionError exception when a DNS error occurs (#2305).
• Added proxy_assert_hostname and proxy_assert_fingerprint kwargs to ProxyManager (#2409).
• Added a configurable backoff_max parameter to the Retry class.
  If a custom backoff_max is provided to the Retry class, it
  will replace the Retry.DEFAULT_BACKOFF_MAX (#2494).
• Added the authority property to the Url class as per RFC 3986 3.2. This property should be used in place of netloc for users who want to include the userinfo (auth) component of the URI (#2520).
• Added the scheme parameter to HTTPConnection.set_tunnel to configure the scheme of the origin being tunnelled to (#1985).
• Added the is_closed, is_connected and has_connected_to_proxy properties to HTTPConnection (#1985).

Removed

• Removed support for Python 2.7, 3.5, and 3.6 (#883, #2336).
• Removed fallback on certificate commonName in match_hostname() function.
  This behavior was deprecated in May 2000 in RFC 2818. Instead only subjectAltName
  is used to verify the hostname by default. To enable verifying the hostname against
  commonName use SSLContext.hostname_checks_common_name = True (#2113).
• Removed support for Python with an ssl module compiled with LibreSSL, CiscoSSL,
  wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644 (#2168).
• Removed support for OpenSSL versions earlier than 1.1.1 or that don't have SNI support.
  When an incompatible OpenSSL version is detected an ImportError is raised (#2168).
• Removed the list of default ciphers for OpenSSL 1.1.1+ and SecureTransport as their own defaults are already secure (#2082).
• Removed urllib3.contrib.appengine.AppEngineManager and support for Google App Engine Standard Environment (#2044).
• Removed deprecated Retry options method_whitelist, DEFAULT_REDIRECT_HEADERS_BLACKLIST (#2086).
• Removed urllib3.HTTPResponse.from_httplib (#2648).
• Removed default value of None for the request_context parameter of urllib3.PoolManager.connection_from_pool_key. This change should have no effect on users as the default value of None was an invalid option and was never used (#1897).
• Removed the urllib3.request module. urllib3.request.RequestMethods has been made a private API.
  This change was made to ensure that from urllib3 import request imported the top-level request()
  function instead of the urllib3.request module (#2269).
• Removed support for SSLv3.0 from the urllib3.contrib.pyopenssl even when support is available from the compiled OpenSSL library (#2233).
• Removed the deprecated urllib3.contrib.ntlmpool module (#2339).
• Removed DEFAULT_CIPHERS, HAS_SNI, USE_DEFAULT_SSLCONTEXT_CIPHERS, from the private module urllib3.util.ssl_ (#2168).
• Removed urllib3.exceptions.SNIMissingWarning (#2168).
• Removed the _prepare_conn method from HTTPConnectionPool. Previously this was only used to call HTTPSConnection.set_cert() by HTTPSConnectionPool (#1985).
• Removed tls_in_tls_required property from HTTPSConnection. This is now determined from the scheme parameter in HTTPConnection.set_tunnel() (#1985).

Changed

• Changed urllib3.response.HTTPResponse.read to respect the semantics of io.BufferedIOBase regardless of compression. Specifically, this method:
  • Only returns an empty bytes object to indicate EOF (that is, the response has been fully consumed).
  • Never returns more bytes than requested.
  • Can issue any number of system calls: zero, one or multiple.
    If you want each urllib3.response.HTTPResponse.read call to issue a single system call, you need to disable decompression by setting decode_content=False (#2128).
• Changed ssl_version to instead set the corresponding SSLContext.minimum_version
  and SSLContext.maximum_version values. Regardless of ssl_version passed
  SSLContext objects are now constructed using ssl.PROTOCOL_TLS_CLIENT (#2110).
• Changed default SSLContext.minimum_version to be TLSVersion.TLSv1_2 in line with Python 3.10 (#2373).
• Changed ProxyError to wrap any connection error (timeout, TLS, DNS) that occurs when connecting to the proxy (#2482).
• Changed urllib3.util.create_urllib3_context to not override the system cipher suites with
  a default value. The new default will be cipher suites configured by the operating system (#2168).
• Changed multipart/form-data header parameter formatting matches the WHATWG HTML Standard as of 2021-06-10. Control characters in filenames are no longer percent encoded (#2257).
• Changed urllib3.HTTPConnection.getresponse to return an instance of urllib3.HTTPResponse instead of http.client.HTTPResponse (#2648).
• Changed return type of HTTPResponse.getheaders() method to return a list of key-value tuples to match CPython (#1543).
• Changed the error raised when connecting via HTTPS when the ssl module isn't available from SSLError to ImportError (#2589).
• Changed HTTPConnection.request() to always use lowercase chunk boundaries when sending requests with Transfer-Encoding: chunked (#2515).
• Changed enforce_content_length default to True, preventing silent data loss when reading streamed responses (#2514).
• Changed internal implementation of HTTPHeaderDict to use dict instead of collections.OrderedDict for better performance (#2080).
• Changed the urllib3.contrib.pyopenssl module to wrap OpenSSL.SSL.Error with ssl.SSLError in PyOpenSSLContext.load_cert_chain (#2628).
• Changed usage of the deprecated socket.error to OSError (#2120).
• Changed all parameters in the HTTPConnection and ``HTT...

1.26.12

• Deprecated the urllib3[secure] extra and the urllib3.contrib.pyopenssl module. Both will be removed in v2.x. See this GitHub issue for justification and info on how to migrate.

1.26.11

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors.

⚠️ urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

• Fixed an issue where reading more than 2 GiB in a call to HTTPResponse.read would raise an OverflowError on Python 3.9 and earlier.

1.26.10

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors.

⚠️ urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

🔐 This is the first release to be signed with Sigstore! You can verify the distributables using the .sig and .crt files included on this release.

• Removed support for Python 3.5
• Fixed an issue where a ProxyError recommending configuring the proxy as HTTP instead of HTTPS could appear even when an HTTPS proxy wasn't configured.

1.26.9

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors.

⚠️ urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

⚠️ This release will be the last release supporting Python 3.5. Please upgrade to a non-EOL Python version.

• Changed urllib3[brotli] extra to favor installing Brotli libraries that are still receiving updates like brotli and brotlicffi instead of brotlipy. This change does not impact behavior of urllib3, only which dependencies are installed.
• Fixed a socket leaking when HTTPSConnection.connect() raises an exception.
• Fixed server_hostname being forwarded from PoolManager to HTTPConnectionPool
  when requesting an HTTP URL. Should only be forwarded when requesting an HTTPS URL.

1.26.8

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors.

⚠️ urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

⚠️ This release will be the last release supporting Python 3.5. Please upgrade to a non-EOL Python version.

• Added extra message tourllib3.exceptions.ProxyError when urllib3 detects that a proxy is configured to use HTTPS but the proxy itself appears to only use HTTP.
• Added a mention of the size of the connection pool when discarding a connection due to the pool being full.
• Added explicit support for Python 3.11.
• Deprecated the Retry.MAX_BACKOFF class property in favor of Retry.DEFAULT_MAX_BACKOFF to better match the rest of the default parameter names. Retry.MAX_BACKOFF is removed in v2.0.
• Changed location of the vendored ssl.match_hostname function from urllib3.packages.ssl_match_hostname to urllib3.util.ssl_match_hostname to ensure Python 3.10+ compatibility after being repackaged by downstream distributors.
• Fixed absolute imports, all imports are now relative.

1.26.7

⚠️ IMPORTANT: urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

• Fixed a bug with HTTPS hostname verification involving IP addresses and lack of SNI
• Fixed a bug where IPv6 braces weren't stripped during certificate hostname matching

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors

1.26.6

⚠️ IMPORTANT: urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

• Deprecated the urllib3.contrib.ntlmpool module. urllib3 is not able to support it properly due to reasons listed in this issue. If you are a user of this module please leave a comment.
• Changed HTTPConnection.request_chunked() to not erroneously emit multiple Transfer-Encoding headers in the case that one is already specified.
• Fixed typo in deprecation message to recommend Retry.DEFAULT_ALLOWED_METHODS.

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors

1.26.5

⚠️ IMPORTANT: urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

• Fixed deprecation warnings emitted in Python 3.10.
• Updated vendored six library to 1.16.0.
• Improved performance of URL parser when splitting the authority component.

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors

1.26.4

⚠️ IMPORTANT: urllib3 v2.0 will drop support for Python 2: Read more in the v2.0 Roadmap

• Changed behavior of the default SSLContext when connecting to HTTPS proxy during HTTPS requests. The default SSLContext now sets check_hostname=True.

If you or your organization rely on urllib3 consider supporting us via GitHub Sponsors