Client

class clients.Client(url, trailing='', headers=(), auth=None, **attrs)

Bases: requests.sessions.Session

A Session which sends requests to a base url.

Parameters:

• url – base url for requests
• trailing – trailing chars (e.g. /) appended to the url
• headers – additional headers to include in requests
• auth – additional authorization support for {token_type: access_token}, available per request as well
• attrs – additional Session attributes

__truediv__(path: str) → clients.base.Client

Return a cloned client with appended path.

delete(path='', **kwargs)

DELETE request with optional path.

get(path='', **kwargs)

GET request with optional path.

head(path='', allow_redirects=False, **kwargs)

HEAD request with optional path.

options(path='', **kwargs)

OPTIONS request with optional path.

patch(path='', json=None, **kwargs)

PATCH request with optional path and json body.

post(path='', json=None, **kwargs)

POST request with optional path and json body.

put(path='', json=None, **kwargs)

PUT request with optional path and json body.

request(method, path, auth=None, **kwargs)

Send request with relative or absolute path and return response.

Resource

class clients.Resource(url, trailing='', headers=(), auth=None, **attrs)

Bases: clients.base.Client

A Client which returns json content and has syntactic support for requests.

content_type(response)

Return name {json, text,… } of response’s content_type.

__call__(path: str = '', **params)

GET request with params.

__contains__(path: str)

Return whether endpoint exists according to HEAD request.

__delitem__(path='', **kwargs)

DELETE request with optional path.

__getattr__(name: str) → clients.base.Client

Return a cloned client with appended path.

__getitem__(path='', **kwargs)

GET request with optional path.

__iter__(path: str = '', **kwargs) → Iterator[T_co]

Iterate lines or chunks from streamed GET request.

__setitem__(path='', json=None, **kwargs)

PUT request with optional path and json body.

authorize(path: str = '', **kwargs) → dict

Acquire oauth access token and set auth.

client

upcasted Client

content_type = functools.partial(<function content_type>, text='text/', json='application/(\\w|\\.)*\\+?json')

create(path: str = '', json=None, **kwargs) → str

POST request and return location.

download(file, path: str = '', **kwargs)

Output streamed GET request to file.

iter(path: str = '', **kwargs) → Iterator[T_co]

Iterate lines or chunks from streamed GET request.

request(method, path, **kwargs)

Send request with path and return processed content.

update(path: str = '', callback: Callable = None, **json)

PATCH request with json params.

Parameters:callback – optionally update with GET and validated PUT. callback is called on the json result with keyword params, i.e., dict correctly implements the simple update case.

updating(path: str = '', **kwargs)

Provisional context manager to GET and conditionally PUT json data.

Remote

class clients.Remote(url: str, json=(), **kwargs)

Bases: clients.base.Client

A Client which defaults to posts with json bodies, i.e., RPC.

Parameters:

• url – base url for requests
• json – default json body for all calls
• kwargs – same options as Client

__call__(path: str = '', **json)

POST request with json body and check() result.

__getattr__(name: str) → clients.base.Client

Return a cloned client with appended path.

__init__(url: str, json=(), **kwargs)

Initialize self. See help(type(self)) for accurate signature.

static check(result)

Override to return result or raise error, for APIs which don’t use status codes.

client

upcasted Client

Graph

class clients.Graph(url: str, json=(), **kwargs)

Bases: clients.base.Remote

A Remote client which executes GraphQL queries.

Error

alias of requests.exceptions.HTTPError

classmethod check(result: dict)

Return data or raise errors.

execute(query: str, **variables)

Execute query over POST.

Proxy

class clients.Proxy(*urls, **kwargs)

Bases: clients.base.Client

An extensible embedded proxy client to multiple hosts.

The default implementation provides load balancing based on active connections. It does not provide error handling or retrying.

Parameters:

• urls – base urls for requests
• kwargs – same options as Client

class Stats

Bases: collections.Counter

Thread-safe Counter.

Context manager tracks number of active connections and errors.

add(**kwargs)

Atomically add data.

choice(method: str) → str

Return chosen url according to priority.

Parameters:method – placeholder for extensions which distinguish read/write requests

priority(url: str)

Return comparable priority for url.

Minimizes errors, failures (500s), and active connections. None may be used to eliminate from consideration.

request(method, path, **kwargs)

Send request with relative or absolute path and return response.

AsyncClient

class clients.AsyncClient(url: str, *, trailing: str = '', auth=None, **attrs)

Bases: httpx.client.AsyncClient

An asynchronous Client which sends requests to a base url.

Parameters:

• url – base url for requests
• trailing – trailing chars (e.g. /) appended to the url
• params – default query params
• auth – additional authorization support for {token_type: access_token}, available per request as well
• attrs – additional AsyncClient options

__truediv__(path: str) → clients.base.Client

Return a cloned client with appended path.

delete(path='', **kwargs)

DELETE request with optional path.

get(path='', **kwargs)

GET request with optional path.

head(path='', allow_redirects=False, **kwargs)

HEAD request with optional path.

options(path='', **kwargs)

OPTIONS request with optional path.

patch(path='', json=None, **kwargs)

PATCH request with optional path and json body.

post(path='', json=None, **kwargs)

POST request with optional path and json body.

put(path='', json=None, **kwargs)

PUT request with optional path and json body.

request(method, path, auth=None, **kwargs)

Send request with relative or absolute path and return response.

run(name: str, *args, **kwargs)

Synchronously call method and run coroutine.

AsyncResource

class clients.AsyncResource(url: str, *, trailing: str = '', auth=None, **attrs)

Bases: clients.aio.AsyncClient

An AsyncClient which returns json content and has syntactic support for requests.

__call__(path: str = '', **params)

GET request with params.

__getattr__(path: str) → clients.base.Client

Return a cloned client with appended path.

__getitem__(path='', **kwargs)

GET request with optional path.

authorize(path: str = '', **kwargs) → dict

Acquire oauth access token and set auth.

client

upcasted AsyncClient

content_type = functools.partial(<function content_type>, text='text/', json='application/(\\w|\\.)*\\+?json')

request(method, path, **kwargs)

Send request with path and return processed content.

update(path='', callback=None, **json)

PATCH request with json params.

Parameters:callback – optionally update with GET and validated PUT. callback is called on the json result with keyword params, i.e., dict correctly implements the simple update case.

updating(path: str = '', **kwargs)

Provisional context manager to GET and conditionally PUT json data.

AsyncRemote

class clients.AsyncRemote(url: str, json=(), **kwargs)

Bases: clients.aio.AsyncClient

An AsyncClient which defaults to posts with json bodies, i.e., RPC.

Parameters:

• url – base url for requests
• json – default json body for all calls
• kwargs – same options as AsyncClient

__call__(path='', **json)

POST request with json body and check result.

__getattr__(path: str) → clients.base.Client

Return a cloned client with appended path.

__init__(url: str, json=(), **kwargs)

Initialize self. See help(type(self)) for accurate signature.

static check(result)

Override to return result or raise error, for APIs which don’t use status codes.

client

upcasted AsyncClient

AsyncGraph

class clients.AsyncGraph(url: str, json=(), **kwargs)

Bases: clients.aio.AsyncRemote

An AsyncRemote client which executes GraphQL queries.

Error

alias of httpx.exceptions.HTTPError

classmethod check(result: dict)

Return data or raise errors.

execute(query: str, **variables)

Execute query over POST.

AsyncProxy

class clients.AsyncProxy(*urls, **kwargs)

Bases: clients.aio.AsyncClient

An extensible embedded proxy client to multiple hosts.

The default implementation provides load balancing based on active connections. It does not provide error handling or retrying.

Parameters:

• urls – base urls for requests
• kwargs – same options as AsyncClient

class Stats

Bases: collections.Counter

Thread-safe Counter.

Context manager tracks number of active connections and errors.

add(**kwargs)

Atomically add data.

choice(method: str) → str

Return chosen url according to priority.

Parameters:method – placeholder for extensions which distinguish read/write requests

priority(url: str)

Return comparable priority for url.

Minimizes errors, failures (500s), and active connections. None may be used to eliminate from consideration.

request(method, path, **kwargs)

Send request with relative or absolute path and return response.

singleton

clients.singleton(*args, **kwargs)

Return a decorator for singleton class instances.