Add `httpx.SSLContext` configuration.

[karpetrosyan]

trafficstars

Discussed in https://github.com/encode/httpx/discussions/3007

TODO:

• [ ] Add changelog
• [x] 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)

[T-256]

Removing verify and cert is too aggressive, I'd recommend deprecate them first.

[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.

[T-256]

There are dropping from top-level API, I think deprecation policy should be applied here.

Also, we have other deprecated drops those pending to remove in v1.0.0 (IIUC):

• proxies=
• data= (non-Mapping objects)
• cookies= (per-request)

[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... https://github.com/encode/httpx/discussions/3007#discussioncomment-7872119 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?

[T-256]

Have we decided to remove or deprecate the old arguments?

deprecate warning on 0.27 raise error on 1.0 remove at some point later on 1.x

This is what I can be happy with.

[karpetrosyan]

Is there a reason we should continue to support the old API?

As far as I can tell, the primary reason for deprecating is that we are adding new functionality and fixing bugs in applications that use the old API. Do we want to deprecate them only for 1-2 releases before the 1.0 version?

[T-256]

My contextual reason got from https://astral.sh/blog/ruff-v0.2.0

Do we want to deprecate them only for 1-2 releases before the 1.0 version?

Actually, those releases are for users using version pinning (httpx < 1.0.0) before major migrating. they might be decided that they aren't ready to stop using old api. so, they can cope with warnings and use latest versions of which deprecated apis allowed to use.

[karpetrosyan]

they might be decided that they aren't ready to stop using old api. so, they can cope with warnings and use latest versions of which deprecated apis allowed to use.

Actually, we are very close to HTTPX 1.0, so I believe there will be just 1-2 releases before then, in which we would primarily introduce the new API, so there will be no features that we would want to ship to our users who are still using the old API.

Also, this migration is rather easy, and I don't believe we need to complicate this PR. Client configurations are frequently found in 1-2 places across the source code, therefore let's make this PR concise and avoid dealing with both new and old APIs.

[T-256]

Then, we can merge this PR for v1.0 but not 0.27. (breaking api)

raise error on 1.0 remove at some point later on 1.x

The error could describe the reason for the drop. This could be removed sometimes later. I think it's better than confusing TypeError: 'verify' is an invalid keyword argument for httpx.Client() message.

[lovelydinosaur]

Then, we can merge this PR for v1.0 but not 0.27.

Yep, that's what we'll do.

The error could describe the reason for the drop

We might choose not to handle the error cases for this: it requires leaving dead code across a lot of function calls. I'm okay with us just making this change outright with a 1.0 release, so long as it's clearly documented in the release.

[lovelydinosaur]

Related... https://github.com/encode/httpx/discussions/3126

[lovelydinosaur]

Looks wonderful... some conflicts that need resolving, other than that I think we ought to get this merged.

[karpetrosyan]

Do we have any blockers here?

[lovelydinosaur]

Just a changelog entry I think? And then we figure out what we want to do version-wise.

[karpetrosyan]

Seems like we should merge this directly into 1.0 because we do have breaking changes here. Ready to spend some time this weekend getting PRs for 1.0 ready.