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.
-
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) >>> job_id = response.id >>> >>> poller = client.queries.get >>> poller_args = (job_id, ) # (job_id, run_id) if poller requires run_id >>> polling_interval = 10 >>> future = CivisFuture(poller, poller_args, polling_interval)
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