Service client

class apiron.client.Timeout(connection_timeout, read_timeout)

Bases: tuple

Create new instance of Timeout(connection_timeout, read_timeout)

connection_timeout

Alias for field number 0

read_timeout

Alias for field number 1

apiron.client.build_url(host, path)

Builds a valid URL from a host and path which may or may not have slashes in the proper place. Does not conform to IETF RFC 1808 but instead joins the host and path as given. Does not append any additional slashes to the final URL; just joins the host and path properly.

Parameters:
  • host (str) – An HTTP host like 'https://awesome-api.com/v2'
  • path (str) – The path to an endpoint on the host like '/some-resource/'
Returns:

The properly-joined URL of host and path, e.g. 'https://awesome-api.com/v2/some-resource/'

Return type:

str

apiron.client.call(service, endpoint, method=None, session=None, params=None, data=None, files=None, json=None, headers=None, cookies=None, auth=None, encoding=None, retry_spec=Retry(total=1, connect=1, read=1, redirect=None, status=None), timeout_spec=Timeout(connection_timeout=1, read_timeout=3), logger=None, allow_redirects=True, return_raw_response_object=False, **kwargs)
Parameters:
  • service (Service) – The service that hosts the endpoint being called
  • endpoint (Endpoint) – The endpoint being called
  • method (str) – The HTTP method to use for the call
  • session (requests.Session) – (optional) An existing session, useful for making many calls in a single session (default None)
  • params (dict) – (optional) GET parameters to send to the endpoint (default None)
  • data (dict) – (optional) POST data to send to the endpoint. A dict will be form-encoded, while a str will be sent raw (default None)
  • files (dict) – (optional) Dictionary of 'filename': file-like-objects for multipart encoding upload. (default None)
  • json (dict) – (optional) A JSON-serializable dictionary that will be sent as the POST body (default None)
  • headers (dict) – HTTP Headers to send to the endpoint (default None)
  • cookies (dict) – Cookies to send to the endpoint (default None)
  • auth – An object suitable for the requests.Request object’s auth argument
  • encoding (str) – The codec to use when decoding the response. Default behavior is to have requests guess the codec. (default None)
  • retry_spec (urllib3.util.retry.Retry) – (optional) An override of the retry behavior for this call. (default Retry(total=1, connect=1, read=1, status_forcelist=[500-level status codes]))
  • timeout_spec (Timeout) – (optional) An override of the timeout behavior for this call. (default Timeout(connection_timeout=1, read_timeout=3))
  • logger (logging.Logger) – (optional) An existing logger for logging from the proper caller for better correlation
  • allow_redirects (bool) – (optional) Enable/disable GET/OPTIONS/POST/PUT/PATCH/DELETE/HEAD redirection (default True)
  • return_raw_response_object (bool) – Whether to return a requests.Response object or call format_response() on it first. (Default False)
  • **kwargs – Arguments to be formatted into the endpoint argument’s path attribute
Returns:

The result of endpoint’s format_response()

Return type:

The type returned by endpoint’s format_response()

Raises:
  • requests.RetryError – if retry threshold exceeded due to bad HTTP codes (default 500 range)
  • requests.ConnectionError – if retry threshold exceeded due to connection or request timeouts
apiron.client.get_adapted_session(adapter)

Mounts an adapter capable of communication over HTTP or HTTPS to the supplied session.

Parameters:adapter – A requests.adapters.HTTPAdapter instance
Returns:The adapted requests.Session instance
apiron.client.get_required_headers(service, endpoint)
Parameters:
  • service (Service) – The service being called
  • endpoint (Endpoint) – The endpoint being called
Returns:

Headers required by the service and the endpoint being called

Return type:

dict