Responses
A Civis API call from client.<endpoint>.<method>
returns a civis.response.Response
object
(or a civis.response.PaginatedResponse
object, if <method>
is a “list” call):
>>> import civis
>>> client = civis.APIClient()
>>> response = client.scripts.get(12345)
>>> response
Response(id=12345,
name='some script name',
created_at='2018-06-11T20:43:07.000Z',
updated_at='2018-06-11T20:43:19.000Z',
author=Response(id=67890,
name='Platform User Name',
username='platformusername',
initials='PUN',
online=False),
...
To retrieve information from a civis.response.Response
object,
either the “getattr” or “getitem” syntax can be used:
>>> response.id
12345
>>> response['id']
12345
>>> response['name']
'some script name'
>>> response.name
'some script name'
Nested response objects can be accessed using the same syntax:
>>> response.author['name']
'Platform User Name'
>>> response.author.name
'Platform User Name'
Note that civis.response.Response
objects are read-only.
If you need to modify information from a response object,
call civis.response.Response.json()
to get a dictionary representation of the response object.
You can then modify this dictionary as needed:
>>> response.arguments = ... # !!! Raises CivisImmutableResponseError
>>> response['arguments'] = ... # !!! Raises CivisImmutableResponseError
>>>
>>> response_json = response.json()
>>> response_json['arguments'] = {'new_arg_for_a_similar_script': 'some_value'}
>>> # use response_json downstream, e.g., to create a new Civis Platform script
Response Types
- class civis.response.Response(json_data, *, headers=None, snake_case=True)[source]
Custom Civis response object.
- Attributes:
- json_datadict | None
This is json_data as it is originally returned to the user without the key names being changed. 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
get
(key[, default])Get the value for the given key.
items
()Return an iterator of the key-value pairs in the response.
json
([snake_case])Return the JSON data.
- 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
>>> import civis >>> 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, 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. If an integer or float is provided, this number will be used as the polling interval. If
None
(the default), the polling interval will start at 1 second and increase geometrically up to 15 seconds. The ratio of the increase is 1.2, resulting in polling intervals in seconds of 1, 1.2, 1.44, 1.728, etc. This default behavior allows for a faster return for a short-running job and a capped polling interval for longer-running jobs.- client
civis.APIClient
, optional - poll_on_creationbool, 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.
- Attributes:
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 if 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
Examples
This example is provided as a function at
query_civis()
.>>> import 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
- property job_id
The job ID for the Civis Platform job that this future is tracking.
- Returns:
- int
- property job_url
The URL for the Civis Platform job that this future is tracking.
- Returns:
- str
- 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.
- property run_id
The run ID for the Civis Platform job that this future is tracking.
- Returns:
- int | None
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))
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 objectobj
from the input iterable to be included in the returned list, all the keys must be attributes ofobj
, plus any one of the following conditions for a given key:value
is a one-argument function andbool(value(getattr(obj, key)))
is equal toTrue
value
is eitherTrue
orFalse
, andgetattr(obj, key) is value
isTrue
getattr(obj, key) == value
isTrue
- 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