# 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