Add a migration guide from httpx
Merged
KL
3mo ago+235+235+012345678901234567890123456789-0-0-0123456789
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;
httpxandhttpx2coexist in one environment, so migration can be incremental and transitive dependencies keep working. Covers the type boundary (isinstance/exceptdon't cross between the two packages) andalias_httpx()(#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
httpxwithhttpx2outright, as modelcontextprotocol/python-sdk#2972 did. If not, preferhttpx2at runtime with anhttpxfallback plus deprecation warning while pointing the install extra athttpx2, as encode/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.