Add opt-in httpx import alias helper

[jonathan343]

Summary

Hey team! I'm interested in this project and saw in #963 that there was a need for aliasing httpx2 as httpx. I also saw that a Pydantic maintainer reacted to one suggested approach, indicating this is something the team may be open to adding.

In this PR, I've added a httpx2.enable_httpx_alias(), which users can opt in to when they need import httpx to resolve to httpx2.

This is useful for staged migrations where an application or dependency tree still contains existing httpx imports, but the environment is moving to httpx2.

The helper is intentionally explicit and conservative. It fails if the real httpx package is installed or if an httpx module has already been imported.

If you want to see this take a different approach, I'm open to updating this PR, just let me know.

Thanks!

Checklist

• I understand that this PR may be closed in case there was no previous discussion. (This doesn't apply to typos!)
• I've added a test for each change that was introduced, and I tried as much as possible to make a single atomic change.
• I've updated the documentation accordingly.

[codspeed-hq]

Merging this PR will not alter performance

✅ 7 untouched benchmarks

---

_{Comparing jonathan343:httpx-alias (2d0fe19) with main (c1d3d95)}

[jonathan343]

Interesting. I'm still new to this and taking a look, but I can't reproduce the coverage failure locally:

(httpx2) $ ./scripts/coverage
+ uv run coverage report --show-missing --skip-covered --fail-under=100
No data to report.

Update: I'm an idiot and forgot to run with coverage. I'll get this updated in a bit

[jonathan343]

Hey @Kludex, friendly ping. Can you take a look at this PR when you get a chance?

Happy to make any updates if you think they're necessary.

[mattmess1221]

Is this check needed? Assuming this gets run only once, existing_httpx_module will be None. If it's run twice, it prevents the next check from running.

[mattmess1221]

Don't forget about httpcore2, otherwise vcrpy will break.

[Kilo59]

Why was this closed?

[jonathan343]

Hey @Kilo59, apologies for closing without a comment.

I closed this PR since I haven't noticed any interest from the maintainers in the past two months and I also don't have the time right now to move this forward. Additionally, I need an HTTP client that supports full-duplex streaming and more performant, so httpx2 isn't the best choice (at least not right now, I have high hopes for the future🤞).

Anyone is more than welcome to build on top of these changes in the same or separate PR.