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.