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_data : dict | 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.
- headers : dict
This is the header for the API call without changing the key names.
- calls_remaining : int
Number of API calls remaining before rate limit is reached.
- rate_limit : int
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
(self, key[, default])Return the value for key if key is in the dictionary, else default. items
()keys
()pop
()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
(self, key[, default])Insert key with a value of default if key is not in the dictionary. update
()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: - path : str
Make GET requests to this path.
- initial_params : dict
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.
- endpoint : civis.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 class will attempt to subscribe to a Pubnub channel to listen for job completion events. If you don’t have access to Pubnub channels, then it will fallback to polling.
This is a subclass of
concurrent.futures.Future
from the Python standard library. See: https://docs.python.org/3/library/concurrent.futures.htmlParameters: - poller : func
A function which returns an object that has a
state
attribute.- poller_args : tuple
The arguments with which to call the poller function.
- polling_interval : int or float, optional
The number of seconds between API requests to check whether a result is ready.
- api_key : DEPRECATED str, optional
Your Civis API key. If not given, the
CIVIS_API_KEY
environment variable will be used.- client :
civis.APIClient
, optional - poll_on_creation : bool, optional
If
True
(the default), it will poll upon callingresult()
the first time. IfFalse
, 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_id : int
First element of the tuple given to poller_args
- run_id : int 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
(self, fn)Attaches a callable that will be called when the future finishes. cancel
(self)Not currently implemented. cancelled
(self)Return True if the future was cancelled. done
(self)Return True of the future was cancelled or finished executing. exception
(self[, timeout])Return the exception raised by the call that the future represents. failed
(self)Return True
if the Civis job failed.outputs
(self)Block on job completion and return a list of run outputs. result
(self[, timeout])Return the result of the call that the future represents. running
(self)Return True if the future is currently executing. set_exception
(self, exception)Sets the result of the future as being the given exception. set_result
(self, result)Sets the return value of work associated with the future. set_running_or_notify_cancel
(self)Mark the future as running or process any cancel notifications. succeeded
(self)Return True
if the job completed in Civis with no error.cleanup -
outputs
(self)[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_list : iterable
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_func : callable, 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))
isTrue
.- **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)))
isTrue
- value is
True
getattr(object, key)
is equal tovalue
- value is a one-argument function and
Returns: - list
See also
Examples
>>> import civis >>> client = civis.APIClient() >>> # creds is a list of civis.response.Response objects >>> creds = client.credentials.list() >>> # target_creds contains civis.response.Response objects >>> # with the attribute 'name' == 'username' >>> target_creds = find(creds, name='username')
-
civis.
find_one
(object_list, filter_func=None, **kwargs)[source]¶ Return one satisfying
civis.response.Response
object.The arguments are the same as those for
civis.find()
. If more than one object satisfies the filtering criteria, the first one is returned. If no satisfying objects are found,None
is returned.Returns: - object or None
See also