# pydantic/httpx2 architecture

> Architecture diagram of the GitHub repository pydantic/httpx2, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-08). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pydantic/httpx2
- Repository: https://github.com/pydantic/httpx2

## Overview

HTTPX2 is a Python HTTP client backed by the separate httpcore2 transport package. Its main workflow is to accept a request through the public API or client, prepare request/model and configuration state, dispatch through a transport, and return a decoded response. The README also documents a CLI, WebSockets, WSGI/ASGI transports, and HTTP/1.1 and HTTP/2. Some links below are README-supported; source excerpts and the SOURCE INDEX establish the sampled implementation relationships, but unsampled modules are represented only where their paths are in the tree.

Main entry points: [`src/httpx2/httpx2/_client.py`](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_client.py) (Client orchestration), [`src/httpx2/httpx2/_models.py`](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_models.py) (Requests and responses), [`src/httpcore2/httpcore2/__init__.py`](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/__init__.py) (HTTP core API), [`src/httpcore2/httpcore2/_sync/connection_pool.py`](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/connection_pool.py) (Sync connection pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["HTTPX client"]
  node_api["Top-level API<br/>[_api.py]"]
  node_client_impl["Client orchestration<br/>[_client.py]"]
  node_models["Requests and responses<br/>[_models.py]"]
  node_urls["URL handling<br/>[_urls.py]"]
  node_config["Timeout and TLS config<br/>[_config.py]"]
end

subgraph group_transport["Transport and protocols"]
  node_transport_api["Transport interface<br/>[base.py]"]
  node_default_transport["Default transport<br/>[default.py]"]
  node_app_transports["WSGI and ASGI<br/>[asgi.py]"]
end

subgraph group_runtime["Network runtime"]
  node_httpcore["HTTP core API<br/>[__init__.py]"]
  node_sync_pool["Sync connection pool<br/>[connection_pool.py]"]
  node_async_pool["Async connection pool<br/>[connection_pool.py]"]
  node_sync_protocols["Sync HTTP protocols<br/>[http11.py]"]
  node_async_protocols["Async HTTP protocols<br/>[http11.py]"]
  node_backend["Network backends<br/>[base.py]"]
  node_http2["HTTP/2 protocol<br/>[http2.py]"]
end

subgraph group_features["Client capabilities"]
  node_auth["Authentication<br/>[_auth.py]"]
  node_content["Body encoding and decoding<br/>[_content.py]"]
  node_multipart["Multipart uploads<br/>[_multipart.py]"]
  node_sse["Server-sent events<br/>[_sse.py]"]
  node_websockets["WebSockets<br/>[_api.py]"]
  node_cli["Command-line client<br/>[_main.py]"]
end

node_user(("Python caller"))
node_service(("HTTP server"))

node_user -->|"calls"| node_api
node_api -->|"creates client"| node_client_impl
node_client_impl -->|"builds requests"| node_models
node_client_impl -->|"uses settings"| node_config
node_client_impl -->|"applies auth"| node_auth
node_client_impl -->|"supports SSE"| node_sse
node_client_impl -->|"exposes WebSockets"| node_websockets
node_client_impl -->|"dispatches requests"| node_transport_api
node_models -->|"uses URL types"| node_urls
node_models -->|"encodes bodies"| node_content
node_models -->|"builds multipart"| node_multipart
node_default_transport -->|"implements"| node_transport_api
node_client_impl -->|"uses by default"| node_default_transport
node_client_impl -.->|"supports app transports"| node_app_transports
node_user -.->|"invokes"| node_cli
node_transport_api -->|"uses transport core"| node_httpcore
node_httpcore -->|"offers sync pool"| node_sync_pool
node_httpcore -->|"offers async pool"| node_async_pool
node_sync_pool -.->|"dispatches protocols"| node_sync_protocols
node_async_pool -.->|"dispatches protocols"| node_async_protocols
node_sync_pool -->|"uses backend"| node_backend
node_async_pool -->|"uses backend"| node_backend
node_async_protocols -.->|"supports HTTP/2"| node_http2
node_sync_protocols -.->|"supports HTTP/2"| node_http2
node_backend -.->|"opens network streams"| node_service
node_service -.->|"returns response"| node_default_transport

click node_api "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_api.py"
click node_client_impl "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_client.py"
click node_models "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_models.py"
click node_urls "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_urls.py"
click node_config "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_config.py"
click node_auth "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_auth.py"
click node_content "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_content.py"
click node_multipart "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_multipart.py"
click node_sse "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_sse.py"
click node_websockets "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/websockets/_api.py"
click node_cli "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_main.py"
click node_transport_api "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/base.py"
click node_default_transport "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/default.py"
click node_app_transports "https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/asgi.py"
click node_httpcore "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/__init__.py"
click node_sync_pool "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/connection_pool.py"
click node_async_pool "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/connection_pool.py"
click node_sync_protocols "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/http11.py"
click node_async_protocols "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/http11.py"
click node_backend "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_backends/base.py"
click node_http2 "https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/http2.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api,node_client_impl,node_models,node_urls,node_config toneBlue
class node_transport_api,node_default_transport,node_app_transports toneAmber
class node_httpcore,node_sync_pool,node_async_pool,node_sync_protocols,node_async_protocols,node_backend,node_http2,node_service toneMint
class node_auth,node_content,node_multipart,node_sse,node_websockets,node_cli toneRose
class node_user toneIndigo
```

## Components

### HTTPX client

- [Top-level API](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_api.py): `src/httpx2/httpx2/_api.py`
- [Client orchestration](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_client.py): `src/httpx2/httpx2/_client.py`
- [Requests and responses](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_models.py): `src/httpx2/httpx2/_models.py`
- [URL handling](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_urls.py): `src/httpx2/httpx2/_urls.py`
- [Timeout and TLS config](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_config.py): `src/httpx2/httpx2/_config.py`

### Transport and protocols

- [Transport interface](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/base.py): `src/httpx2/httpx2/_transports/base.py`
- [Default transport](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/default.py): `src/httpx2/httpx2/_transports/default.py`
- [WSGI and ASGI](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_transports/asgi.py): `src/httpx2/httpx2/_transports/asgi.py`

### Network runtime

- [HTTP core API](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/__init__.py): `src/httpcore2/httpcore2/__init__.py`
- [Sync connection pool](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/connection_pool.py): `src/httpcore2/httpcore2/_sync/connection_pool.py`
- [Async connection pool](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/connection_pool.py): `src/httpcore2/httpcore2/_async/connection_pool.py`
- [Sync HTTP protocols](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_sync/http11.py): `src/httpcore2/httpcore2/_sync/http11.py`
- [Async HTTP protocols](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/http11.py): `src/httpcore2/httpcore2/_async/http11.py`
- [Network backends](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_backends/base.py): `src/httpcore2/httpcore2/_backends/base.py`
- [HTTP/2 protocol](https://github.com/pydantic/httpx2/blob/main/src/httpcore2/httpcore2/_async/http2.py): `src/httpcore2/httpcore2/_async/http2.py`

### Client capabilities

- [Authentication](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_auth.py): `src/httpx2/httpx2/_auth.py`
- [Body encoding and decoding](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_content.py): `src/httpx2/httpx2/_content.py`
- [Multipart uploads](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_multipart.py): `src/httpx2/httpx2/_multipart.py`
- [Server-sent events](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_sse.py): `src/httpx2/httpx2/_sse.py`
- [WebSockets](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/websockets/_api.py): `src/httpx2/httpx2/websockets/_api.py`
- [Command-line client](https://github.com/pydantic/httpx2/blob/main/src/httpx2/httpx2/_main.py): `src/httpx2/httpx2/_main.py`

### Other components

- **Python caller**
- **HTTP server**

## Connections

- Python caller → Top-level API: calls
- Top-level API → Client orchestration: creates client
- Client orchestration → Requests and responses: builds requests (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → Timeout and TLS config: uses settings (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → Authentication: applies auth (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → Server-sent events: supports SSE (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → WebSockets: exposes WebSockets (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → Transport interface: dispatches requests (evidence: `src/httpx2/httpx2/_client.py`)
- Requests and responses → URL handling: uses URL types (evidence: `src/httpx2/httpx2/_models.py`)
- Requests and responses → Body encoding and decoding: encodes bodies (evidence: `src/httpx2/httpx2/_models.py`)
- Requests and responses → Multipart uploads: builds multipart (evidence: `src/httpx2/httpx2/_models.py`)
- Default transport → Transport interface: implements (evidence: `src/httpx2/httpx2/_transports/default.py`)
- Client orchestration → Default transport: uses by default (evidence: `src/httpx2/httpx2/_client.py`)
- Client orchestration → WSGI and ASGI: supports app transports (evidence: `README.md`)
- Python caller → Command-line client: invokes (evidence: `README.md`)
- Transport interface → HTTP core API: uses transport core
- HTTP core API → Sync connection pool: offers sync pool (evidence: `src/httpcore2/httpcore2/__init__.py`)
- HTTP core API → Async connection pool: offers async pool (evidence: `src/httpcore2/httpcore2/__init__.py`)
- Sync connection pool → Sync HTTP protocols: dispatches protocols
- Async connection pool → Async HTTP protocols: dispatches protocols
- Sync connection pool → Network backends: uses backend (evidence: `src/httpcore2/httpcore2/_sync/connection_pool.py`)
- Async connection pool → Network backends: uses backend (evidence: `src/httpcore2/httpcore2/_async/connection_pool.py`)
- Async HTTP protocols → HTTP/2 protocol: supports HTTP/2 (evidence: `README.md`)
- Sync HTTP protocols → HTTP/2 protocol: supports HTTP/2 (evidence: `README.md`)
- Network backends → HTTP server: opens network streams
- HTTP server → Default transport: returns response
