Tracking breaking changes for v2.0

[pquentin]

We need to record all noteworthy 2.0 changes as news fragments. Here's the full list: 1.26.x...main. I've listed all relevant changes below. Sorry, this is messy, I sometimes link to the merged commit, and sometimes to the PR. The merged commit is usually a better starting point as Seth usually rewords before merging.

• fbe9620 Remove support for Python 2 and 3.5
• 6af53ac Remove support for Google App Engine Standard
• b6061f0 Remove strict parameter (but tolerate it in 186e7f9)
• 4ff35ef Change inner container of HTTPHeaderDict to 'dict'
• c67c094 Remove deprecated Retry options
• d39d6a6 Add BaseHTTPResponse base class
• cad4850 Change return type of HTTPResponse.getheaders() to match CPython
• c915450 Switch to Brotli C bindings for CPython, brotlicffi for non-CPython (Switch to Brotli C bindings for CPython, brotlicffi for non-CPython #2099)
• 4fadb28 Attach errno to SocketError when raised from OpenSSL.SSL.SysCallError
• 102352a Replace deprecated socket.error with OSError
• fd0c475 + 1bf2f16 Remove commonName support
• 841a727 Use system TLS ciphers if using OpenSSL 1.1.1+ or SecureTransport
• 7d55357 + 1367897 + ddf7361 + fdea284 + 4953f29 Add top-level request() method
• Start shipping our own type stubs #1897 Ship our own types
• 2205771 Add exception wrapper for HTTPS proxy connection failure (wasn't backported to 1.26.x but probably should have)
• 7f56f2e Lean on SSLContext to verify hostnames when possible (currently reverted, see Respect SSLContext.hostname_checks_common_name set manually by users #2192 for the versions where it should be enabled)
• ed23062 Fix None/False confusion in is_connection_dropped
• 3346a2a raise FullPoolError if we try to _put_conn an extra connection in blocking mode
• e208fec Fix default socket_options value for HTTPSConnection
• 066ed76 Expose HTTPHeaderDict to top level
• 8e8272e Align multipart parameter encoding with current WHATWG HTML standard
• Support Python 3.10
• 195b24b Add cycle-breaking logic to create_connection()
• 1831327 + 8a1ac9f Raise NameResolutionError instead of socket.gaierror
• c976e55 Remove urllib3.contrib.ntlmpool module
• ad1712a Drop support for Python 3.6
• a04cb71 Fix remove_headers_on_redirect feature modifying passed-in headers in-place

Original issue below.

---

We just removed two bits of API in 2.x because they're no longer useful in Python 3:

• urllib3.contrib.appengine.AppEngineManager in Drop support for EOL Python 2.7 and 3.5 #2044
• the strict parameter from PoolManager, ConnectionPool and Connection (currently used by requests) in Remove strict parameter #2064

Should we:

1. just put that in the changelog and be done with it?
2. or make AppEngineManager an alias of PoolManager and accept but ignore strict?

I think we said we were aiming for zero API breakage of that sort, and @untitaker has mentioned it would help the Sentry SDK. I'd be in favor of option 2.

[sethmlarson]

• AppEngineManager is good to remove since in theory it's impossible to install urllib3 v2.0 on Python 2.7 and that fixture is only usable from Python 2.7
• strict is different, because code may have been passing strict=True just for the effects on Python 2.7 we should probably just pop it out of **kwargs like we were doing before. I'm not sure there's even value in emitting a warning in this case, we can likely just exclude it from type hints to push users away from it. If we want to be more pushy we can emit a DeprecationWarning but then it becomes a pain for packages supporting Python 2 still.

[sethmlarson]

Unfortunately we'll likely have to handle them on a case-by-case basis. Potentially we can keep this issue open so we can remember how we handled each and that'll help with writing the migration guide.

[pquentin]

Another breaking change that should be mentioned in the changelog is getheaders() return signature changing.

[sethmlarson]

Breaking change: RecentlyUsedContainer.ContainerCls is no longer a class property

[sethmlarson]

Breaking change: Removed urllib3.util.current_time, use time.monotonic instead (#2214)

[sethmlarson]

Multipart header parameters now formatted to modern WHATWG HTML standard: #2257

[pquentin]

We now use towncrier, so I'm going to repurpose that issue to make sure we record all noteworthy v2 changes as news fragments. That way, we won't have to track every change down when we'll actually release 2.0.

[sethmlarson]

@pquentin Agreed, would you be willing to tackle that?

[pquentin]

Yes, I'm on it! I have 167 commits to review.

[pquentin]

I've added 27 potential news fragments to the first comment. Some of them are already in the news fragments, and some of them may turn out to be irrelevant, but that's easier to work with than the original 167 commits :)

[pquentin]

Should we turn this into a good first issue? Anyone can add a few news fragments, once merged we can mark them as done above. See https://github.com/urllib3/urllib3/tree/main/changelog for the related documentation.

Or is this something that we should do ourselves?

[sethmlarson]

@pquentin We should probably do this ourselves, otherwise it'll be a lot for us to manually review anyways.