Add a migration guide from httpx

Merged
KL
3mo ago
+235-0

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() (#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 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 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.