High-level HTTP clients for Python.
Project description
Clients originally provided requests wrappers to encourage best practices, particularly always using Sessions to connect to the same host or api endpoint. The primary goals were:
- provide a
Client
object with a convenient constructor - support a base url so that requests can provide a relative path
- provide the same interface for asyncio
Since then httpx has emerged as the successor to requests
, and supports the above features natively. So clients.Client
can be replaced with httpx.Client
for most use cases. The project will continue to be maintained for additional features, such as the Resource
object.
Usage
Typical requests
usage is redundant and inefficient, by not taking advantage of connection pooling.
r = requests.get('https://api.github.com/user', headers={'authorization': token})
r = requests.get('https://api.github.com/user/repos', headers={'authorization': token})
Using sessions is the better approach, but more verbose and in practice requires manual url joining.
s = requests.Session()
s.headers['authorization'] = token
r = s.get('https://api.github.com/user')
r = s.get('https://api.github.com/user/repos')
Client
Clients make using sessions easier, with implicit url joining.
client = clients.Client('https://api.github.com/', headers={'authorization': token})
r = client.get('user')
r = client.get('user/repos')
Resource
Resources extend Clients to implicitly handle response content, with proper checking of status_code and content-type.
github = clients.Resource('https://api.github.com/', headers={'authorization': token})
for repo in github.get('user/repos', params={'visibility': 'public'}):
...
Resources also implement syntactic support for methods such as getattr and call, providing most of the benefits of custom clients as is.
for repo in github.user.repos(visibility='public'):
...
Asynchronous variants of all client types are provided, e.g., AsyncClient
. Additional clients for RPC, GraphQL, and proxies also provided.
Installation
% pip install clients
Dependencies
- httpx
Tests
100% branch coverage.
% pytest [--cov]