API Responses¶

Response Types¶

class civis.response.Response(json_data, snake_case=True, headers=None)[source]¶

Custom Civis response object.

Notes

The main features of this class are that it maps camelCase to snake_case at the top level of the json object and attaches keys as attributes. Nested object keys are not changed.

Attributes

json_datadict | None: This is json_data as it is originally returned to the user without the key names being changed. See Notes. None is used if the original response returned a 204 No Content response.
headersdict: This is the header for the API call without changing the key names.
calls_remainingint: Number of API calls remaining before rate limit is reached.
rate_limitint: Total number of calls per API rate limit period.

Methods

`clear`()
`copy`()
`fromkeys`(iterable[, value])	Create a new dictionary with keys from iterable and values set to value.
`get`(key[, default])	Return the value for key if key is in the dictionary, else default.
`items`()
`keys`()
`pop`(k[,d])	If key is not found, d is returned if given, otherwise KeyError is raised
`popitem`()	2-tuple; but raise KeyError if D is empty.
`setdefault`(key[, default])	Insert key with a value of default if key is not in the dictionary.
`update`([E, ]**F)	If E is present and has a .keys() method, then does: for k in E: D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]
`values`()

class civis.response.PaginatedResponse(path, initial_params, endpoint)[source]¶

A response object which is an iterator

Parameters

pathstr: Make GET requests to this path.
initial_paramsdict: Query params that should be passed along with each request. Note that if initial_params contains the keys page_num or limit, they will be ignored. The given dict is not modified.
endpointcivis.base.Endpoint: An endpoint used to make API requests.

Notes

This response is returned automatically by endpoints which support pagination when the iterator kwarg is specified.

Examples

>>> client = civis.APIClient()
>>> queries = client.queries.list(iterator=True)
>>> for query in queries:
...    print(query['id'])

class civis.futures.CivisFuture(poller, poller_args, polling_interval=None, api_key=None, client=None, poll_on_creation=True)[source]¶

A class for tracking future results.

This is a subclass of concurrent.futures.Future from the Python standard library. See: https://docs.python.org/3/library/concurrent.futures.html

Parameters

pollerfunc: A function which returns an object that has a state attribute.
poller_argstuple: The arguments with which to call the poller function.
polling_intervalint or float, optional: The number of seconds between API requests to check whether a result is ready.
api_keyDEPRECATED str, optional: Your Civis API key. If not given, the CIVIS_API_KEY environment variable will be used.
clientcivis.APIClient, optional
poll_on_creationbool, optional: If True (the default), it will poll upon calling result() the first time. If False, it will wait the number of seconds specified in polling_interval from object creation before polling.

Examples

This example is provided as a function at query_civis().

>>> client = civis.APIClient()
>>> database_id = client.get_database_id("my_database")
>>> cred_id = client.default_credential
>>> sql = "SELECT 1"
>>> preview_rows = 10
>>> response = client.queries.post(database_id, sql, preview_rows,
>>>                                credential=cred_id)
>>>
>>> poller = client.queries.get_runs
>>> poller_args = response.id, response.last_run_id
>>> polling_interval = 10
>>> future = CivisFuture(poller, poller_args, polling_interval)
>>> future.job_id == response.id
True
>>> future.run_id == response.last_run_id
True

Attributes

job_idint: First element of the tuple given to poller_args
run_idint or None: Second element of the tuple given to poller_args (None if the poller function does not require a run ID)

Methods

`add_done_callback`(fn)	Attaches a callable that will be called when the future finishes.
`cancel`()	Not currently implemented.
`cancelled`()	Return True if the future was cancelled.
`done`()	Return True of the future was cancelled or finished executing.
`exception`([timeout])	Return the exception raised by the call that the future represents.
`failed`()	Return `True` if the Civis job failed.
`outputs`()	Block on job completion and return a list of run outputs.
`result`([timeout])	Return the result of the call that the future represents.
`running`()	Return True if the future is currently executing.
`set_exception`(exception)	Sets the result of the future as being the given exception.
`set_result`(result)	Sets the return value of work associated with the future.
`set_running_or_notify_cancel`()	Mark the future as running or process any cancel notifications.
`succeeded`()	Return `True` if the job completed in Civis with no error.

cleanup

outputs()[source]¶

Block on job completion and return a list of run outputs.

The method will only return run outputs for successful jobs. Failed jobs will raise an exception.

Returns

list[dict]: List of run outputs from a successfully completed job.

Raises

civis.base.CivisJobFailure: If the job fails.

Helper Functions¶

civis.find(object_list, filter_func=None, **kwargs)[source]¶

Filter civis.response.Response objects.

Parameters

object_listiterable

An iterable of arbitrary objects, particularly those with attributes that can be targeted by the filters in kwargs. A major use case is an iterable of civis.response.Response objects.

filter_funccallable, optional

A one-argument function. If specified, kwargs are ignored. An object from the input iterable is kept in the returned list if and only if bool(filter_func(object)) is True.

**kwargs

Key-value pairs for more fine-grained filtering; they cannot be used in conjunction with filter_func. All keys must be strings. For an object from the input iterable to be included in the returned list, all the key`s must be attributes of `object, plus any one of the following conditions for a given key:

value is a one-argument function and bool(value(getattr(object, key))) is True
value is True
getattr(object, key) is equal to value

Returns

list