Skip to main content
Python Software Foundation 20th Year Anniversary Fundraiser  Donate today!

HTTP for humanitarians.

Project description

image image image image image image image image image

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

httpx is on track to reach 1.0 status before requests3 is available, and natively supports a base URL on its client. The next version of clients is planned to use only httpx.

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, using httpx instead of requests. Additional clients for RPC, GraphQL, and proxies also provided.

Installation

% pip install clients

Dependencies

  • requests >=2.23
  • httpx >=0.15

Tests

100% branch coverage.

% pytest [--cov]

Changes

1.3

  • httpx >=0.15 required
  • requests deprecated

1.2

  • Python 3 required
  • httpx >=0.11 required

1.1

  • Async switched to httpx

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

Project details


Download files

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

Files for clients, version 1.3
Filename, size File type Python version Upload date Hashes
Filename, size clients-1.3-py3-none-any.whl (9.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size clients-1.3.tar.gz (12.2 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page