httpx Client实例

提示
如果您是来自Requests的用户，则可以使用 ​httpx.Client()​代替​requests.Session()​。

为什么要使用Client？

总结：
如果您做的不仅仅是实验、一次性脚本或原型，那么您应该使用​Client​实例。

更高效地利用网络资源

使用快速入门指南中所述的顶级 API 发出请求时，HTTPX 必须为每个请求建立新连接（不会重用连接）。随着对主机的请求数量的增加，这很快就会变得低效。

另一方面，​Client​实例使用 HTTP 连接池。这意味着，当您向同一主机发出多个请求时，​Client​将重用底层 TCP 连接，而不是为每个请求重新创建一个连接。

与使用顶级 API 相比，这可以带来显著的性能改进，包括：

• 减少跨请求的延迟（无握手）。
• 降低了 CPU 使用率和往返行程。
• 减少网络拥塞。

额外功能

Client实例还支持顶级 API 中不可用的功能，例如：

• 跨请求的 Cookie 持久性。
• 对所有传出请求应用配置。
• 通过 HTTP 代理发送请求。
• 使用 HTTP/2。

本章节的其他部分将更详细地介绍您可以对Client实例执行的操作。

用法

推荐使用​Client​的方法是作为上下文管理器。这将确保在离开​with​块时正确清理连接：

with httpx.Client() as client:
    ...

或者，您可以使用.close()明确关闭连接池而不使用with块：

client = httpx.Client()
try:
    ...
finally:
    client.close()

构造请求

一旦你有了 ​Client​，你可以使用​.get() ​、​.post()​ 等发送请求。例如：

>>> with httpx.Client() as client:
...     r = client.get('https://example.com')
...
>>> r
<Response [200 OK]>

这些方法接受与​httpx.get() ​、​httpx.post()​ 等相同的参数。这意味着快速入门指南中记录的所有功能在​Client​级别也可用。

例如，要发送带有自定义标头的请求，请执行以下操作：

>>> with httpx.Client() as client:
...     headers = {'X-Custom': 'value'}
...     r = client.get('https://example.com', headers=headers)
...
>>> r.request.headers['X-Custom']
'value'

跨请求共享配置

​Clients​允许您通过将参数传递给​Client​构造函数，将配置应用于所有传出请求。

例如，要对每个请求应用一组自定义标头，请执行以下操作：

>>> url = 'http://httpbin.org/headers'
>>> headers = {'user-agent': 'my-app/0.0.1'}
>>> with httpx.Client(headers=headers) as client:
...     r = client.get(url)
...
>>> r.json()['headers']['User-Agent']
'my-app/0.0.1'

合并配置

在client-level和request-level同时提供配置选项时，可能会发生以下两种情况之一：

• 对于标头、查询参数和 Cookie，这些值将组合在一起。例如：

  >>> headers = {'X-Auth': 'from-client'}
  >>> params = {'client_id': 'client1'}
  >>> with httpx.Client(headers=headers, params=params) as client:
  ...     headers = {'X-Custom': 'from-request'}
  ...     params = {'request_id': 'request1'}
  ...     r = client.get('https://example.com', headers=headers, params=params)
  ...
  >>> r.request.url
  URL('https://example.com?client_id=client1&request_id=request1')
  >>> r.request.headers['X-Auth']
  'from-client'
  >>> r.request.headers['X-Custom']
  'from-request'

• 对于所有其他参数，request级值优先。例如：

  >>> with httpx.Client(auth=('tom', 'mot123')) as client:
  ...     r = client.get('https://example.com', auth=('alice', 'ecila123'))
  ...
  >>> _, _, auth = r.request.headers['Authorization'].partition(' ')
  >>> import base64
  >>> base64.b64decode(auth)
  b'alice:ecila123'

如果您需要对client级和request级参数的合并进行更精细的控制，请参阅请求实例。

其他Client专用配置选项

此外，Client接受一些在请求级别不可用的配置选项。

例如，​base_url​允许您为所有传出请求预先添加URL：

>>> with httpx.Client(base_url='http://httpbin.org') as client:
...     r = client.get('/headers')
...
>>> r.request.url
URL('http://httpbin.org/headers')

有关所有可用Client参数的列表，请参阅Client API 参考。