Add a migration guide from httpx

[Kludex]

Summary

Adds a Migrating from HTTPX docs page (placed right after QuickStart in the nav), aimed at the two audiences that keep asking about this:

• Applications, including huge codebases: the rename is the whole migration for direct users; httpx and httpx2 coexist in one environment, so migration can be incremental and transitive dependencies keep working. Covers the type boundary (isinstance/except don't cross between the two packages) and alias_httpx() (Add alias_httpx() to alias httpx imports to httpx2 #1077) as the application-level escape hatch, with its rules and limits.
• Package maintainers: two battle-tested paths. If a major release is possible, replace httpx with httpx2 outright, as Replace httpx and httpx-sse with httpx2 modelcontextprotocol/python-sdk#2972 did. If not, prefer httpx2 at runtime with an httpx fallback plus deprecation warning while pointing the install extra at httpx2, as Support httpx2 in the test client Kludex/starlette#3291 did (pattern shown inline).

Also documents the visible rename surface (CLI, User-Agent, loggers, httpcore2) and behavior differences (truststore, Python 3.10+, visible deprecation warnings), ends with a pre-ship checklist, and adds alias_httpx to the API reference.

AI Disclaimer

This PR was developed with the assistance of either Claude or Codex. I've reviewed and verified the changes.

[github-actions]

Docs preview: https://a13094b1-httpx2-docs.pydantic.workers.dev

[codspeed-hq]

Merging this PR will not alter performance

✅ 15 untouched benchmarks
⏩ 7 skipped benchmarks¹

---

_{Comparing document-httpx-migration (7248191) with main (e111465)}

Footnotes

1. 7 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 7e30fcc1dd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Don’t promise every deprecation is visible

This overstates the current runtime behavior: several active deprecations still emit the built-in DeprecationWarning (for example verify=<str>/cert=... in src/httpx2/httpx2/_config.py, per-request cookies in _client.py, and raw data= bytes in _content.py), which is ignored by default when raised from library code. Users migrating those call sites therefore will not see the warnings without configuring filters, contrary to this guide.

Useful? React with 👍 / 👎.