Add httpx.SSLContext configuration.

[karpetrosyan]

Discussed in #3007

TODO:

• Add changelog
• Add more migration examples

Migration examples

Enabling and disabling verification

import httpx

# instead of 
httpx.Client(verify=False)

# do
context = httpx.SSLContext(verify=False)
httpx.Client(ssl_context=context)

Use a different set of certificates

import httpx

# instead of
httpx.Client(verify="path/to/certs.pem")

# do
context = httpx.SSLContext(verify="path/to/certs.pem")
httpx.Client(ssl_context=context)

Client side certificates

import httpx

# instead of
httpx.Client(cert="path/to/client.pem")

# do
context = httpx.SSLContext(cert="path/to/client.pem")
httpx.Client(ssl_context=context)

Using alternate SSL contexts

import ssl
import httpx

context = ssl.create_default_context()

# instead of
client = httpx.Client(verify=context)

# do
client = httpx.Client(ssl_context=context)

[karpetrosyan]

Yes, I agree that removing them completely is not what the user expects.
However, I believe migration is simple enough to skip that stage in order to avoid making that part of the code overly complicated.

Or should we deprecate them anyway? Not obvious to me.

[tomchristie]

Looking good.

Update documentation

I'd suggest you don't spin time on that until we've had a clear discussion around the "API finessing" and "Documentation refresh" areas mentioned in #947 (comment). I like this change, but we'll want to make it as part of a coherent & consistent 1.0 refresh.

[tomchristie]

Okay, shall we take the docs from this comment... #3007 (comment) and include them in the PR?

[karpetrosyan]

Okay, shall we take the docs from this comment... #3007 (comment) and include them in the PR?

I like it

[karpetrosyan]

Have we decided to remove or deprecate the old arguments?

[tomchristie]

Thanks so much @karpetrosyan - going to merge this into "version-1.0" now, and then apply remaining changes incrementally. Fantastic work!! 😎

[karpetrosyan]

Sorry, I couldn't find time to finish all the tidy-ups.
Thank you for the help! 🙏 @T-256 @tomchristie

[tomchristie]

Thank you so much for your time & dedication @karpetrosyan. 🙌