Drop urllib3 in favor of public gist

[florimondmanca]

Fixes #1143

This PR removes the URLLib3Transport from HTTPX, and moves it to a public gist that we're now pointing to in the "Custom transports" docs.

Also adds a small additional section to the Requests compatibility guide, so that people know this option exists if they're migrating from Requests to HTTPX.

[jcugat]

Changes look good. We can remove the --omit=httpx/_transports/urllib3.py from scripts/coverage now.

[lovelydinosaur]

Fantastic! Let's hold off on pulling in API changes until we're ready to roll a major release. We could consider maintaining a release branch?

[lovelydinosaur]

The only other tiny tweak I can think of here in the gist would be changing from this:

        except (urllib3.exceptions.SSLError, socket.error) as exc:
            tb = exc.__traceback__
            raise httpcore.NetworkError(exc).with_traceback(tb) from None

To this:

        except (urllib3.exceptions.SSLError, socket.error) as exc:
            raise httpcore.NetworkError(exc) from exc

Which I think gets us the traceback behaviour we actually.

https://gist.github.com/florimondmanca/d56764d78d748eb9f73165da388e546e#file-urllib3_transport-py-L101

[lovelydinosaur]

Okay, it's got a do-not-merge label on, which makes sense, but otherwise yup this is ace.
So, approved.

Do we think we ought to be maintaining a version branch so that we can pull this in, and then maintain the version branch until we're ready to go?

[lovelydinosaur]

In the gist, let's just use raise httpcore.NetworkError(exc) from exc styles, instead of .with_traceback(tb), in these two cases:

• https://gist.github.com/florimondmanca/d56764d78d748eb9f73165da388e546e#file-urllib3_transport-py-L18-L19
• https://gist.github.com/florimondmanca/d56764d78d748eb9f73165da388e546e#file-urllib3_transport-py-L100-L101

Once that's tweaked let's get this merged!

[lovelydinosaur]

I'd suggest we also include a link in the "third party packages" docs.

[florimondmanca]

let's just use raise httpcore.NetworkError(exc) from exc styles, instead of .with_traceback(tb), in these two cases

✅

I'd suggest we also include a link in the "third party packages" docs.

✅

Also dropped the recommendation to use urllib3-transport while migrating — I reckon that's not something even I might not actually do if I were to migrate a Requests-based project to use HTTPX.

Edit: also updated the README and docs home page to not mention urllib3 as an optional dependency anymore (da4a456).

[florimondmanca]

Not too keen to put this under "Plugins", since it's not really an installable package, but then also not keen on the existing "Plugins" section — perhaps we ought to just list everything as h2-level headers. We can address this as a follow-up.

[lovelydinosaur]

Fantastic. 🌟