fastapi-conventions/sources/httpx.md

HTTPX source notes for FastAPI conventions

Repo: encode/httpx Local checkout: /home/ubuntu/repos/rodin-sources/httpx

Why this repo was chosen

• FastAPI services often depend on HTTPX both for in-process ASGI testing and for outbound HTTP seams. HTTPX source clarifies where those seams actually live.
• Useful here because the transport layer gives stronger evidence than generic client examples.

Repeated patterns

1) HTTPX supports testing an ASGI app across the HTTP boundary without leaving process

• httpx/_transports/asgi.py:63-83 defines ASGITransport as a transport that sends requests directly to an ASGI app, with explicit knobs for raise_app_exceptions, root_path, and client address.
• httpx/_transports/asgi.py:105-119 shows the transport building a real ASGI scope from the outgoing request, including method, headers, path, query string, server, client, and root_path.

Why chosen:

• This is a concrete framework-aligned seam for FastAPI/Starlette apps; it preserves HTTP/ASGI behavior better than calling route functions directly.

Caveat / counterexample:

• httpx/_transports/asgi.py:79-81 explicitly says app exceptions are raised by default. If you want to inspect a 500 response body instead of crashing the test, you must set raise_app_exceptions=False.

Implication for synthesis:

• Prefer in-process ASGI transport/client tests when you want realistic request/response behavior without network overhead.
• Mention the raise_app_exceptions=False toggle when describing 500-response testing.

2) HTTPX makes outbound substitution a transport concern, not a patching concern

• httpx/_transports/mock.py:15-17 defines MockTransport from a request handler.
• httpx/_transports/mock.py:19-43 routes fully built requests through that handler for both sync and async clients, reading the request body first and requiring/awaiting a real Response.

Why chosen:

• This is a stronger seam than monkeypatching nested client.get(...) call sites; the substitution happens at the client transport boundary.

Caveat / counterexample:

• httpx/_transports/mock.py:25-26 raises a TypeError if a sync client is given an async handler. The sync/async client mode still matters even when mocking.

Implication for synthesis:

• Recommend transport substitution for HTTP integrations instead of monkeypatching internal helper functions or third-party SDK calls.

Strong citation candidates

• ASGI transport is the in-process app test seam: httpx/_transports/asgi.py:63-83
• ASGI scope construction proves tests still exercise HTTP/ASGI boundaries: httpx/_transports/asgi.py:105-119
• 500-response testing requires raise_app_exceptions=False: httpx/_transports/asgi.py:79-81
• Mock transport is request/response substitution at the client boundary: httpx/_transports/mock.py:15-43

Pattern candidates supported by this repo

• prefer in-process ASGI transport tests for HTTP behavior
• use transport-level substitution for outbound HTTP dependencies
• keep sync/async client mode aligned with the transport handler you provide