Responses

A Civis API call from client.<endpoint>.<method> returns one of the “response” objects:

civis.PaginatedResponse if <method> is a “list” call with iterator=True,
civis.ListResponse if <method> is a “list” call that either doesn’t have an iterator argument or has iterator=False, or
civis.Response.

>>> 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 object, use the attribute syntax:

>>> response.id
12345
>>> response.name
'some script name'
>>> response.author
Response({'id': 67890,
          'name': 'Platform User Name',
          'username': 'platformusername',
          'initials': 'PUN',
          'online': False})
>>> response.author.username
'platformusername'

civis.APIClient is type-annotated for the returned civis.Response object of a given Civis API endpoint’s method, including the expected attributes. These type annotations facilitate code development and testing:

If your IDE has auto-complete support, typing response. from the example above prompts possible attributes {id, name, author, ...}.
Type checking (by tools such as mypy) in test suites and continuous integration helps to catch issues such as typos and unexpected attributes.

Alternatively, the “getitem” syntax can also be used:

>>> response['id']
12345
>>> response['author']
Response({'id': 67890,
          'name': 'Platform User Name',
          'username': 'platformusername',
          'initials': 'PUN',
          'online': False})

Although the “getitem” syntax would lose the benefits of the attribute syntax listed above, the “getitem” syntax is more user-friendly when an attribute name is available programmatically, e.g., response[foo] versus getattr(response, foo).

Note that civis.Response objects are read-only. If you need to modify information from a response object, call civis.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(json_data: dict[str, Any] | None, *, headers: dict | None = None, snake_case: bool = True, from_json_values: bool = False)[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.

get(key, default=None)[source]: Get the value for the given key.

items()[source]: Return an iterator of the key-value pairs in the response.

json(snake_case: bool = True) → dict[str, Any][source]

Return the JSON data.

Parameters:

snake_casebool, optional: If True (the default), return the keys in snake case. If False, return the keys in camel case.

Returns:

dict

class civis.PaginatedResponse(path: str, initial_params: dict[str, Any], endpoint)[source]

A generator of civis.Response objects, for paginated API calls.

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 key page_num, it will be ignored. The given dict is not modified.
endpointcivis.base.Endpoint: An endpoint used to make API requests.

Methods

json([snake_case])

Return the JSON data of all responses.

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'])

json(snake_case: bool = True) → list[dict[str, Any]][source]

Return the JSON data of all responses.

Parameters:

snake_casebool, optional: If True (the default), return the keys in snake case. If False, return the keys in camel case.

Returns:

list[dict]

class civis.ListResponse(responses: list[T_Response], headers: dict | None = None)[source]

A list of civis.Response objects.

Parameters:

responseslist[civis.Response]: A list of response objects to be stored in this list.
headersdict, optional: Headers to be attached to the list response. The headers info is available as an attribute, so that it can be accessed even when the list is empty.

Methods

json([snake_case])

Return the JSON data of all responses in the list.

json(snake_case: bool = True) → list[dict[str, Any]][source]

Return the JSON data of all responses in the list.

Parameters:

snake_casebool, optional: If True (the default), return the keys in snake case. If False, return the keys in camel case.

Returns:

list[dict]

class civis.futures.CivisFuture(poller: Callable, poller_args: Sequence, polling_interval: int | float | None = None, client: APIClient | None = None, poll_on_creation: bool = 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.
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.

Attributes:

job_id: The job ID for the Civis Platform job that this future is tracking.
job_run_url: The URL for the run of the Civis Platform job that this future is tracking.
job_url: The URL for the Civis Platform job that this future is tracking.
run_id: The run ID for the Civis Platform job that this future is tracking.

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_database_credential_id
>>> 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: int

The job ID for the Civis Platform job that this future is tracking.

Returns:

int

property job_run_url: str | None

The URL for the run of the Civis Platform job that this future is tracking.

Returns:

str | None

property job_url: str

The URL for the Civis Platform job that this future is tracking.

Returns:

str

outputs() → list[Response][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[civis.Response]: List of run outputs from a successfully completed job.

Raises:

civis.base.CivisJobFailure: If the job fails.

property run_id: int | None

The run ID for the Civis Platform job that this future is tracking.

Returns:

int | None

Helper Functions

civis.find(object_list: Iterable[Response], filter_func: Callable | None = None, **kwargs) → list[Response][source]

Filter civis.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 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 obj from the input iterable to be included in the returned list, all the keys must be attributes of obj, plus any one of the following conditions for a given key:

value is a one-argument function and bool(value(getattr(obj, key))) is equal to True
value is either True or False, and getattr(obj, key) is value is True
getattr(obj, key) == value is True

Returns:

list