HTTPX 是一个功能完整的 Python HTTP 客户端，提供同步和异步两套 API，并支持 HTTP/1.1 与 HTTP/2。本资料以“HTTPX Skill”的形式介绍其快速上手方式、常见用法模式和实用代码片段。
用途 HTTPX 用于在 Python 中发起 HTTP 请求，既适合普通同步脚本，也适合需要并发和异步 IO 的现代应用。它可在同步与异步代码中使用同一套接口风格。
主要能力
- 同步与异步 API：同步与异步接口一致，便于不同编程模型间切换。
- HTTP/2 支持：提供完整的 HTTP/2 支持与多路复用（multiplexing）。
- 连接池：高效的连接管理。
- 流式处理：可流式发送请求与接收响应，无需一次性将内容全部读入内存。
- 认证：内置 Basic、Digest、Bearer token 以及自定义认证支持。
- 超时：可分别为连接（connect）、读取（read）和整体请求配置超时。
- 重定向处理：可配置是否跟随重定向。
- Cookie 处理：自动管理 Cookie。
- 代理支持：支持 HTTP 与 HTTPS 代理。
- SSL/TLS：提供完整的 SSL/TLS 配置选项。
快速开始 基本用法： import httpx response = httpx.get('https://api.example.com/data') print(response.status_code) print(response.json()) response = httpx.post('https://api.example.com/users', json={'name': 'Alice'})
异步用法： import asyncio import httpx async def fetch_data(): async with httpx.AsyncClient() as client: response = await client.get('https://api.example.com/data') return response.json() result = asyncio.run(fetch_data())
常见模式
- 带连接池的异步客户端：在 async with httpx.AsyncClient() 中复用同一个 client 并发发起多个请求（可用 asyncio.gather 汇总）。
- 认证：可用 httpx.BasicAuth 构造基础认证；用 headers 设置 Bearer token；也可在单次请求中传入 auth=('user', 'pass')。
- 流式下载：使用 httpx.stream('GET', url) 并通过 response.iter_bytes() 分块写入文件，避免大文件占用内存；异步版本使用 client.stream 与 response.aiter_bytes()。
- 流式上传：通过生成器产出数据块，作为 content 传给 client.post 进行流式上传。
- 错误处理与超时：用 httpx.Timeout 分别设置整体、连接与读取超时；调用 response.raise_for_status() 在 4XX/5XX 时抛出异常；可捕获 httpx.TimeoutException、httpx.HTTPStatusError、httpx.RequestError。
- 客户端配置：httpx.Client 可统一设置 base_url、headers、timeout、follow_redirects 等，后续请求会复用这些配置并以 base_url 拼接路径。
- 自定义认证：继承 httpx.Auth 并实现 auth_flow，在请求头中写入自定义字段（如 X-API-Key）。
- 进度监控：结合 tqdm，在流式下载时根据 content-length 读取并更新进度。
- 重试逻辑：捕获 httpx.RequestError 并按指数退避（如 2 ** attempt）进行重试，达到最大重试次数后抛出异常。
- WebSocket（借助 httpx-ws）：使用 httpx_ws 的 connect_ws 在 AsyncClient 上建立 WebSocket 连接，发送和接收文本消息。
适用场景
- 需要对 API 发起同步或异步请求的 Python 应用。
- 需要并发请求并复用连接的场景。
- 需要流式下载或上传大文件、避免内存占用过高的场景。
- 需要统一配置 base_url、请求头、超时、重定向以及代理、SSL/TLS 的场景。
- 需要自定义认证流程或对请求进行进度监控、失败重试的场景。
- 需要在客户端中接入 WebSocket 的场景（需 httpx-ws）。
安装与依赖 安装： pip install httpx HTTP/2 支持： pip install httpx[http2] WebSocket 支持： pip install httpx-ws
依赖要求： httpx>=0.24.0 可选依赖：httpx-ws>=0.6.0（WebSocket 支持）、tqdm>=4.65.0（进度条）、anyio>=3.7.0（替代异步运行时）、trio>=0.22.0（替代异步运行时）
限制 资料中未提供关于收费、价格、平台、性能效果或其他未列出功能的说明，这些内容暂未提供。