Skip to main content

High-level HTTP clients for Python.

Project description

image image image image image image image image image

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.


Typical requests usage is redundant and inefficient, by not taking advantage of connection pooling.

r = requests.get('', headers={'authorization': token})
r = requests.get('', 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('')
r = s.get('')


Clients make using sessions easier, with implicit url joining.

client = clients.Client('', headers={'authorization': token})
r = client.get('user')
r = client.get('user/repos')


Resources extend Clients to implicitly handle response content, with proper checking of status_code and content-type.

github = clients.Resource('', 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.


% pip install clients


  • httpx >=0.23


100% branch coverage.

% pytest [--cov]



  • requests removed
  • Python >=3.7 required
  • httpx >=0.23 required


  • httpx >=0.15 required
  • requests deprecated


  • Python 3 required
  • httpx >=0.11 required


  • Async switched to httpx


  • Allow missing content-type
  • Oauth access tokens supported in authorization header


  • AsyncClient default params
  • Remote and AsyncRemote procedure calls
  • Graph and AsyncGraph execute GraphQL queries
  • Proxy and AsyncProxy clients


  • Asynchronous clients and resources


  • singleton decorator


  • Resource attribute upcasts back to a client
  • iter and download implement GET requests with streamed content
  • create implements POST request and returns Location header
  • update implements PATCH request with json params
  • __call__ implements GET request with params

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

clients-1.4.tar.gz (9.4 kB view hashes)

Uploaded source

Built Distribution

clients-1.4-py3-none-any.whl (9.4 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page