Add httpx.SSLContext configuration.

[karpetrosyan]

Discussed in #3007

TODO:

• Add changelog
• Add more migration examples

Migration examples

Enabling and disabling verification

importhttpx# instead of httpx.Client(verify=False)
# docontext=httpx.SSLContext(verify=False)
httpx.Client(ssl_context=context)

Use a different set of certificates

importhttpx# instead ofhttpx.Client(verify="path/to/certs.pem")
# docontext=httpx.SSLContext(verify="path/to/certs.pem")
httpx.Client(ssl_context=context)

Client side certificates

importhttpx# instead ofhttpx.Client(cert="path/to/client.pem")
# docontext=httpx.SSLContext(cert="path/to/client.pem")
httpx.Client(ssl_context=context)

Using alternate SSL contexts

importsslimporthttpxcontext=ssl.create_default_context()
# instead ofclient=httpx.Client(verify=context)
# doclient=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.

[lovelydinosaur]

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 https://github.com/encode/httpx/issues/947#issuecomment-1727389402. I like this change, but we'll want to make it as part of a coherent & consistent 1.0 refresh.

[lovelydinosaur]

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?

[lovelydinosaur]

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

[lovelydinosaur]

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