Initial extracted documentation set

2026-06-01 21:42:05 +00:00
commit a23e494026
16 changed files with 1414 additions and 0 deletions
@@ -0,0 +1,48 @@
+# 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