Service client

class apiron.client.Timeout(connection_timeout, read_timeout)

Bases: tuple

Create new instance of Timeout(connection_timeout, read_timeout)

property connection_timeout

Alias for field number 0

property 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.

  • host (str) – An HTTP host like ''

  • path (str) – The path to an endpoint on the host like '/some-resource/'


The properly-joined URL of host and path, e.g. ''

Return type

str, 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=None, **kwargs)
  • 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


The result of endpoint’s format_response()

Return type

The type returned by endpoint’s format_response()

  • 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


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


adapter – A requests.adapters.HTTPAdapter instance


The adapted requests.Session instance

apiron.client.get_required_headers(service, endpoint)
  • service (Service) – The service being called

  • endpoint (Endpoint) – The endpoint being called


Headers required by the service and the endpoint being called

Return type