Create BaseHTTPConnection APIs

[sethmlarson]

Closes #1985

Started by taking apart and documenting the HTTP connection (+pool) lifecycle and what would be necessary at every stage. Decided it might be good to document these in notes that we can keep up to date once we settle on an API.

In general I'd like to fix up a bit of our super complicated proxy situation (cc @jalopezsilva) since we technically "own" the HTTPConnection API. Timeouts are similarly complicated but done in multiple ways.

There's some more features I want to dig into and document like HTTPConnection.auto_open which appears to be to do with whether a connection is reusable.

I have some local work creating a BaseHTTPConnection protocol and trying it with type hints but that's not quite ready yet.

[pquentin]

This is great, and I love how this highlights improvements that we could carry on today.

The internal property usage is a big problem.

Have you studied HTTP1Connection from the v2 branch and hip? https://github.com/python-trio/hip/blob/e198149c677edbeec023aeb934758c9195a4d2e3/src/ahip/connection.py#L317-L565? I think there are valuable lessons there.

Finally, I think those notes stand on their own, and I would happy to merge them as-is.

[sethmlarson]

Noting this down for future me because I have to leave: default port when specifying a scheme in HTTPConnection.set_tunnel().

[pquentin]

Awesome work. 👏

[pquentin]

This looks good to me, thank you! I've left a few comments, but this does not need another round of review. 🎉

[vEpiphyte]

For reference this did not document the removal of the VerifiedHTTPSConnection class ( despite its rename in #1805 ) from the connectionpool module.

edit: noted the module detail.

[pquentin]

@vEpiphyte VerifiedHTTPSConnection is still here in urllib3 2.0, we just stopped importing it from connectionpool.py. If this is where you were importing it from, your code was only working by accident.

You can use from urllib3.connection import VerifiedHTTPSConnection instead but of course at this point it would be better to use the new name with from urllib3.connection import HTTPSConnection.

Why did you need this?

[vEpiphyte]

@pquentin Looking into this issue in vcrpy ( which you commented on, thank you very much! ) kevin1024/vcrpy#688 since that has caused an immediate outage for myself and my downstream users.

Almost more so a note for myself, since git bisect & github's compare feature didn't quickly tell me where the removal of the import came from. For example, 2.0.1...1.26.15 does not show the removal of the import from connection.py.