clients 1.0

HTTP for humanitarians.

Clients provide requests and aiohttp wrappers which encourage best practices, particularly always using Sessions to connect to the same host or api endpoint.

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')

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'}):
    ...

Resource

Resources also implement syntactic support for methods such as getattr and call, providing most of the benefits of custom clients with no further defintion.

for repo in github.user.repos(visibility='public'):
    ...

Being session based, Clients work seamlessly with other requests adapters, such as CacheControl. Asynchronous variants of all client types are provided in Python 3, using aiohttp instead of requests. Additional clients for RPC, GraphQL, and proxies also provided.

Installation

$ pip install clients

Dependencies

• requests >=2.4.2
• aiohttp (if Python 3)

Tests

100% branch coverage.

$ pytest [--cov]

Changes

1.0

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

0.5

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

0.4

• Asynchronous clients and resources

0.3

• singleton decorator

0.2

• 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