Package: civis
IntroductionThe Civis Platform API Python client is a Python package that helps analysts
and developers interact with the Civis Platform. The package includes a set of
tools around common workflows as well as a convenient interface to make
requests directly to the Civis API.Please see thefull documentationfor more details.API KeysIn order to make requests to the Civis API,
you will need a Civis Platform API key that is unique to you.
Instructions for creating a new key are foundhere.
API keys have a set expiration date and new keys will need to be created at
least every 30 days. The API client will look for aCIVIS_API_KEYenvironmental variable to access your API key, so after creating a new API key,
follow the steps below for your operating system to set up your environment.Linux / MacOSAdd the following to your shell configuration file (~/.zshrcfor MacOS or~/.bashrcfor Linux, by default):export CIVIS_API_KEY="alphaNumericApiK3y"Source your shell configuration file (or restart your terminal).Windows 10Navigate to “Settings” -> type “environment” in search bar ->
“Edit environment variables for your account”. This can also be found
in “System Properties” -> “Advanced” -> “Environment Variables…”.In the user variables section, ifCIVIS_API_KEYalready exists in
the list of environment variables, click on it and press “Edit…”.
Otherwise, click “New..”.Enter CIVIS_API_KEY as the “Variable name”.Enter your API key as the “Variable value”.  Your API key should look
like a long string of letters and numbers.InstallationAfter creating an API key and setting theCIVIS_API_KEYenvironmental
variable, install the Python packageciviswith the recommended method viapip:pip install civisAlternatively, if you are interested in the latest functionality not yet released throughpip,
you may clone the code from GitHub and build from source:gitclonehttps://github.com/civisanalytics/civis-python.gitcdcivis-pythonpythonsetup.pyinstallYou can test your installation by runningimportcivisclient=civis.APIClient()print(client.users.list_me()['username'])Ifciviswas installed correctly, this will print your Civis
Platform username.The client has a soft dependency onpandasto support features such as
data type parsing.  If you are using theionamespace to read or write
data from Civis, it is highly recommended that you installpandasand
setuse_pandas=Truein functions that accept that parameter.  To installpandas:pipinstallpandasMachine learning features in themlnamespace have a soft dependency onscikit-learnandpandas. Installscikit-learnto
export your trained models from the Civis Platform or to
provide your own custom models. Usepandasto download model predictions
from the Civis Platform. Thecivis.mlcode
optionally uses thefeatherformat to transfer data from your local computer to Civis
Platform. Install these dependencies withpipinstallscikit-learnpipinstallpandaspipinstallfeather-formatSome CivisML models have open-source dependencies in
addition toscikit-learn, which you may need if you want to
download the model object. These dependencies arecivisml-extensions,glmnet, andmuffnn. Install these
dependencies withpipinstallcivisml-extensionspipinstallglmnetpipinstallmuffnnUsagecivisincludes a number of wrappers around the Civis API for
common workflows.importcivisdf=civis.io.read_civis(table="my_schema.my_table",database="database",use_pandas=True)The Civis API may also be directly accessed via theAPIClientclass.importcivisclient=civis.APIClient()database=client.databases.list()See thedocumentationfor a more
complete user guide.RetriesThe API client will automatically retry for certain API error responses.If the error is one of [413, 429, 503] and the API client is told how long it needs
to wait before it’s safe to retry (this is always the case with 429s, which are
rate limit errors), then the client will wait the specified amount of time
before retrying the request.If the error is one of [429, 502, 503, 504] and the request is not apatch*orpost*method, then the API client will retry the request several times, with an exponential delay,
to see if it will succeed. If the request is of typepost*it will retry with the same parameters
for error codes [429, 503].Build Documentation LocallyTo install dependencies for building the documentation:pip install Sphinx
pip install sphinx_rtd_theme
pip install numpydocTo build the API documentation locally:cd docs
make htmlThen opendocs/build/html/index.html.Note that this will use your API key in theCIVIS_API_KEYenvironment
variable so it will generate documentation for all the endpoints that you have access to.Command-line Interface (CLI)After installing the Python package, you’ll also have aciviscommand accessible from your shell. It surfaces a commandline interface to all of the regular Civis API endpoints, plus a few helpers. To get started, runcivis--help.
Please see theCLI documentationfor more details.ContributingSeeCONTRIBUTING.mdfor information about contributing to this project.LicenseBSD-3SeeLICENSE.mdfor details.For MaintainersThetoolsdirectory contains scripts that civis-python maintainers can
use (and maintain…). Please see their docstrings for usage.
Non-public information can be found by searching the internal documentation system
or consulting the current maintainers.