urllib3 is a user-friendly HTTP client library for Python
PoolManager
with many distinct origins would cause connection pools to be closed while requests are in progress (#2954)HTTPResponse.stream()
to continue yielding bytes if buffered decompressed data was still available to be read even if the underlying socket is closed. This prevents a compressed response from being truncated. (https://github.com/urllib3/urllib3/issues/3009)HTTPResponse.read(0)
was the first read
call or when the internal response body buffer was otherwise empty. (#2998)Read the v2.0 migration guide for help upgrading to the latest version of urllib3.
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).ssl
module compiled with LibreSSL, CiscoSSL, wolfSSL, and all other OpenSSL alternatives. Python is moving to require OpenSSL with PEP 644 (#2168).ImportError
is raised (#2168).urllib3.contrib.appengine.AppEngineManager
and support for Google App Engine Standard Environment (#2044).Retry
options method_whitelist
, DEFAULT_REDIRECT_HEADERS_BLACKLIST
(#2086).urllib3.HTTPResponse.from_httplib
(#2648).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).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).urllib3.contrib.pyopenssl
even when support is available from the compiled OpenSSL library (#2233).urllib3.contrib.ntlmpool
module (#2339).DEFAULT_CIPHERS
, HAS_SNI
, USE_DEFAULT_SSLCONTEXT_CIPHERS
, from the private module urllib3.util.ssl_
(#2168).urllib3.exceptions.SNIMissingWarning
(#2168)._prepare_conn
method from HTTPConnectionPool
. Previously this was only used to call HTTPSConnection.set_cert()
by HTTPSConnectionPool
(#1985).tls_in_tls_required
property from HTTPSConnection
. This is now determined from the scheme
parameter in HTTPConnection.set_tunnel()
(#1985).HTTPResponse.getheaders()
and HTTPResponse.getheader()
which will be removed in urllib3 v2.1.0. Instead use HTTPResponse.headers
and HTTPResponse.headers.get(name, default)
. (#1543, #2814).urllib3.contrib.pyopenssl
module which will be removed in urllib3 v2.1.0 (#2691).urllib3.contrib.securetransport
module which will be removed in urllib3 v2.1.0 (#2692).ssl_version
option in favor of ssl_minimum_version
. ssl_version
will be removed in urllib3 v2.1.0 (#2110).strict
parameter as it's not longer needed in Python 3.x. It will be removed in urllib3 v2.1.0 (#2267)NewConnectionError.pool
attribute which will be removed in urllib3 v2.1.0 (#2271).format_header_param_html5
and format_header_param
in favor of format_multipart_header_param
(#2257).RequestField.header_formatter
parameter which will be removed in urllib3 v2.1.0 (#2257).HTTPSConnection.set_cert()
method. Instead pass parameters to the HTTPSConnection
constructor (#1985).HTTPConnection.request_chunked()
method which will be removed in urllib3 v2.1.0. Instead pass chunked=True
to HTTPConnection.request()
(#1985).urllib3.request
function which uses a preconfigured module-global PoolManager
instance (#2150).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).urllib3
module (#1897).ssl_minimum_version
and ssl_maximum_version
options which set SSLContext.minimum_version
and SSLContext.maximum_version
(#2110).zstandard
1.18.0 or later is installed. Added the zstd
extra which installs the zstandard
package (#1992).urllib3.response.BaseHTTPResponse
class. All future response classes will be subclasses of BaseHTTPResponse
(#2083).FullPoolError
which is raised when PoolManager(block=True)
and a connection is returned to a full pool (#2197).HTTPHeaderDict
to the top-level urllib3
namespace (#2216).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).NameResolutionError
exception when a DNS error occurs (#2305).proxy_assert_hostname
and proxy_assert_fingerprint
kwargs to ProxyManager
(#2409).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).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).scheme
parameter to HTTPConnection.set_tunnel
to configure the scheme of the origin being tunnelled to (#1985).is_closed
, is_connected
and has_connected_to_proxy
properties to HTTPConnection
(#1985).backoff_jitter
parameter to Retry
. (#2952)urllib3.response.HTTPResponse.read
to respect the semantics of io.BufferedIOBase
regardless of compression. Specifically, this method:
urllib3.response.HTTPResponse.read
call to issue a single system call, you need to disable decompression by setting decode_content=False
(#2128).urllib3.HTTPConnection.getresponse
to return an instance of urllib3.HTTPResponse
instead of http.client.HTTPResponse
(#2648).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).SSLContext.minimum_version
to be TLSVersion.TLSv1_2
in line with Python 3.10 (#2373).ProxyError
to wrap any connection error (timeout, TLS, DNS) that occurs when connecting to the proxy (#2482).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).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).ssl
module isn't available from SSLError
to ImportError
(#2589).HTTPConnection.request()
to always use lowercase chunk boundaries when sending requests with Transfer-Encoding: chunked
(#2515).enforce_content_length
default to True, preventing silent data loss when reading streamed responses (#2514).HTTPHeaderDict
to use dict
instead of collections.OrderedDict
for better performance (#2080).urllib3.contrib.pyopenssl
module to wrap OpenSSL.SSL.Error
with ssl.SSLError
in PyOpenSSLContext.load_cert_chain
(#2628).socket.error
to OSError
(#2120).HTTPConnection
and HTTPSConnection
constructors to be keyword-only except host
and port
(#1985).HTTPConnection.getresponse()
to set the socket timeout from HTTPConnection.timeout
value before reading data from the socket. This previously was done manually by the HTTPConnectionPool
calling HTTPConnection.sock.settimeout(...)
(#1985)._proxy_host
property to _tunnel_host
in HTTPConnectionPool
to more closely match how the property is used (value in HTTPConnection.set_tunnel()
) (#1985).Retry.BACK0FF_MAX
to be Retry.DEFAULT_BACKOFF_MAX
.SSLContext.check_hostname
when possible (#2452).server_hostname
to behave like other parameters only used by HTTPSConnectionPool
(#2537).blocksize
to 16KB to match OpenSSL's default read amounts (#2348).HTTPResponse.read()
to raise an error when calling with decode_content=False
after using decode_content=True
to prevent data loss (#2800).PoolManager
with many distinct origins would cause connection pools to be closed while requests are in progress (#1252).HTTPConnection
instance would erroneously reuse the socket read timeout value from reading the previous response instead of a newly configured connect timeout. Instead now if HTTPConnection.timeout
is updated before sending the next request the new timeout value will be used (#2645).socket.error.errno
when raised from pyOpenSSL's OpenSSL.SSL.SysCallError
(#2118).HTTPSConnection.socket_options
to match HTTPConnection
(#2213).headers
would be modified by the remove_headers_on_redirect
feature (#2272).urllib3.util.connection.create_connection()
(#2277).HTTPConnection.connect()
fails (#2571).urllib3.contrib.pyopenssl.WrappedSocket
and urllib3.contrib.securetransport.WrappedSocket
close methods (#2970)setup.py
shim, python setup.py install
will print [Errno 2] No such file or directory
instead of a warning to use pip (#2975)backoff_jitter
parameter to Retry
(#2952)urllib3.contrib.pyopenssl.WrappedSocket
and urllib3.contrib.securetransport.WrappedSocket
close methods (#2970)HTTPResponse.getheaders()
calls in urllib3.contrib
module.Read the v2.0 migration guide for help upgrading to the latest version of urllib3.
add_stderr_logger
(#2839)PoolKey.key_retries
by adding bool
to the union (#2865)Read the v2.0 migration guide for help upgrading to the latest version of urllib3.
HTTPResponse.read()
to raise an error when calling with decode_content=False
after using decode_content=True
to prevent data loss (https://github.com/urllib3/urllib3/issues/2800).HTTPResponse.getheaders()
and .getheader()
to previous behavior in 1.26.x. Instead we are deprecating these methods in favor of HTTPResponse.headers.items()
and HTTPResponse.headers.get()
. Both deprecated methods will be removed in v2.1.0 (https://github.com/urllib3/urllib3/issues/2814)HTTPResponse.getheaders()
and HTTPResponse.getheader()
methods.<4
in the Requires-Python
packaging metadata field.