API Client¶
APIClient
is a class for handling requests to the Civis API.
An instantiated APIClient
contains a set of resources
(listed below) where each resource is an object with methods. By convention,
an instantiated APIClient
object is named client
and API
requests are made with the following syntax:
client = civis.APIClient()
response = client.resource.method(params)
The methods on APIClient
are created dynamically at runtime
by parsing an collections.OrderedDict
representation of the
Civis API specification. By default, this specification is downloaded from
the /endpoints
endpoint the first time APIClient
is
instantiated (and cached in memory for the remainder of the program’s run).
In some circumstances, it may be useful to use a local cache of the API
specification rather than downloading the spec. This can be done by passing
the specification to the client through the parameter local_api_spec
as
either the collections.OrderedDict
or a filename where the
specification has been saved.
api_key = os.environ['CIVIS_API_KEY']
spec = civis.resources.get_api_spec(api_key)
# From OrderedDict
client = civis.APIClient(local_api_spec=spec)
# From file
with open('local_api_spec.json', 'w') as f:
json.dump(spec, f)
client = civis.APIClient(local_api_spec='local_api_spec.json')
-
class
civis.
APIClient
(api_key=None, return_type='snake', retry_total=6, api_version='1.0', resources='all', local_api_spec=None)[source]¶ The Civis API client.
Parameters: - api_key : str, optional
Your API key obtained from the Civis Platform. If not given, the client will use the
CIVIS_API_KEY
environment variable.- return_type : str, optional
The following types are implemented:
'raw'
Returns the rawrequests.Response
object.'snake'
Returns acivis.response.Response
object for the json-encoded content of a response. This maps the top-level json keys to snake_case.'pandas'
Returns apandas.DataFrame
for list-like responses and apandas.Series
for single a json response.
- retry_total : int, optional
A number indicating the maximum number of retries for 429, 502, 503, or 504 errors.
- api_version : string, optional
The version of endpoints to call. May instantiate multiple client objects with different versions. Currently only “1.0” is supported.
- resources : string, optional
When set to “base”, only the default endpoints will be exposed in the client object. Set to “all” to include all endpoints available for a given user, including those that may be in development and subject to breaking changes at a later date. This will be removed in a future version of the API client.
- local_api_spec : collections.OrderedDict or string, optional
The methods on this class are dynamically built from the Civis API specification, which can be retrieved from the /endpoints endpoint. When local_api_spec is None, the default, this specification is downloaded the first time APIClient is instantiated. Alternatively, a local cache of the specification may be passed as either an OrderedDict or a filename which points to a json file.
Attributes: - announcements
An instance of the
Announcements
endpoint- apps
An instance of the
Apps
endpoint- clusters
An instance of the
Clusters
endpoint- credentials
An instance of the
Credentials
endpoint- databases
An instance of the
Databases
endpoint- endpoints
An instance of the
Endpoints
endpoint- enhancements
An instance of the
Enhancements
endpoint- exports
An instance of the
Exports
endpoint- files
An instance of the
Files
endpoint- groups
An instance of the
Groups
endpoint- imports
An instance of the
Imports
endpoint- jobs
An instance of the
Jobs
endpoint- match_targets
An instance of the
Match_Targets
endpoint- media
An instance of the
Media
endpoint- models
An instance of the
Models
endpoint- notebooks
An instance of the
Notebooks
endpoint- notifications
An instance of the
Notifications
endpoint- ontology
An instance of the
Ontology
endpoint- predictions
An instance of the
Predictions
endpoint- projects
An instance of the
Projects
endpoint- queries
An instance of the
Queries
endpoint- remote_hosts
An instance of the
Remote_Hosts
endpoint- reports
An instance of the
Reports
endpoint- scripts
An instance of the
Scripts
endpoint- search
An instance of the
Search
endpoint- tables
An instance of the
Tables
endpoint- templates
An instance of the
Templates
endpoint- users
An instance of the
Users
endpoint- workflows
An instance of the
Workflows
endpoint
-
default_credential
¶ The current user’s default credential.
-
get_aws_credential_id
(self, cred_name, owner=None)¶ Find an AWS credential ID.
Parameters: - cred_name : str or int
If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the AWS credential with that name.
- owner : str, optional
Return the credential with this owner. If not provided, search for credentials under your username to disambiguate multiple credentials with the same name. Note that this function cannot return credentials which are not associated with an owner.
Returns: - aws_credential_id : int
The ID number of the AWS credentials.
Raises: - ValueError
If the AWS credential can’t be found.
Examples
>>> import civis >>> client = civis.APIClient() >>> client.get_aws_credential_id('jsmith') 1234
>>> client.get_aws_credential_id(1111) 1111
>>> client.get_aws_credential_id('shared-cred', ... owner='research-group') 99
-
get_database_credential_id
(self, username, database_name)¶ Return the credential ID for a given username in a given database.
Parameters: - username : str or int
If an integer ID is given, this passes through directly. If a str is given, return the ID corresponding to the database credential with that username.
- database_name : str or int
Return the ID of the database credential with username username for this database name or ID.
Returns: - database_credential_id : int
The ID of the database credentials.
Raises: - ValueError
If the credential can’t be found.
Examples
>>> import civis >>> client = civis.APIClient() >>> client.get_database_credential_id('jsmith', 'redshift-general') 1234
>>> client.get_database_credential_id(1111, 'redshift-general') 1111
-
get_database_id
(self, database)¶ Return the database ID for a given database name.
Parameters: - database : str or int
If an integer ID is given, passes through. If a str is given the database ID corresponding to that database name is returned.
Returns: - database_id : int
The ID of the database.
Raises: - ValueError
If the database can’t be found.
-
get_storage_host_id
(self, storage_host)¶ Return the storage host ID for a given storage host name.
Parameters: - storage_host : str or int
If an integer ID is given, passes through. If a str is given the storage host ID corresponding to that storage host is returned.
Returns: - storage_host_id : int
The ID of the storage host.
Raises: - ValueError
If the storage host can’t be found.
Examples
>>> import civis >>> client = civis.APIClient() >>> client.get_storage_host_id('test host') 1234
>>> client.get_storage_host_id(1111) 1111
-
get_table_id
(self, table, database)¶ Return the table ID for a given database and table name.
Parameters: - table : str
The name of the table in format schema.tablename. Either schema or tablename, or both, can be double-quoted to correctly parse special characters (such as ‘.’).
- database : str or int
The name or ID of the database.
Returns: - table_id : int
The ID of the table.
Raises: - ValueError
If a table match can’t be found.
Examples
>>> import civis >>> client = civis.APIClient() >>> client.get_table_id('foo.bar', 'redshift-general') 123 >>> client.get_table_id('"schema.has.periods".bar', 'redshift-general') 456
-
username
¶ The current user’s username.