Quick Start

This tutorial walks through the process of setting up the TruSTAR Python SDK and running a simple program to establish that the setup succeeded.

Step 1: Install Python

To use the SDK, you must first have Python installed on your system. You can easily download and install it from https://www.python.org/. Once that is done, you can test that the installation was successful by opening a terminal and running the command

python -c "print('Hello, world!')"

If the installation was successful, this should print the text Hello, World! on the line below.

Step 2: Install the TruSTAR Package

To install the TruSTAR Python SDK, you will need to have pip installed. Run pip to check that it is installed. You should see the pip help screen. Usually, pip comes preinstalled with Python, but in some special cases you might need to install it manually. If your console does not recognize the pip command when you run it, please follow the instructions at https://packaging.python.org/tutorials/installing-packages/#ensure-you-can-run-pip-from-the-command-line to install it.

Once you have pip, you can simply run pip install trustar. If you need to install a specific version of the SDK, you can simply run pip install trustar==0.2.4, for example, to install version 0.2.4 of the TruSTAR SDK.

To ensure that the SDK was installed successfully, run

python -c "import trustar; print(trustar.__version__)"

and the version of the TruSTAR SDK that you have installed should be printed out on your screen.

Step 3: Generate an API Key and Secret

Since the SDK is a tool for interacting with the TruSTAR API, it requires you to provide it with your API credentials. The TruSTAR API uses OAuth2, a secure authorization protocol. To generate credentials, visit https://station.trustar.co/settings/api, check the box next to the text “I have read and agree to the Terms Of Use Policy.”, and click the button to generate your credentials.

Step 4: Configure the SDK

The SDK requires some configuration values in order to talk to the TruSTAR REST API. These should be stored in a file called trustar.conf. Your configuration file should look something like this:

[trustar]
auth_endpoint = https://api.trustar.co/oauth/token
api_endpoint = https://api.trustar.co/api/1.3
user_api_key = 45d175fc-1b7c-480d-ae46-bf203c0344b6
user_api_secret = v2i2kpfuAt3wp9bW0FcimbJt
enclave_ids = 4dfb66f8-1dfc-406d-a0ed-b517ff043053,291af346-dbd1-4bc0-9c69-be20af157fb0

The api key and secret shown here, as well as the enclave IDs, are fake. Replace them with the key and secret you just generated, and any IDs of enclaves you want to use (the enclave IDs are not required).

Note

If this file is in your working directory when you use the SDK, it will automatically be found and used. This behavior can be overridden by passing the path to a config file, if you need to. See the detailed documentation for the TruStar class to learn how to do this.

Step 5: Run a Script

The simplest script that can be written using the SDK is one that simply “pings” the API to establish that it can connect and pass authorization. Place the following file, titled ping.py, in the same directory as your trustar.conf file:

from trustar import TruStar

ts = TruStar()

print(ts.ping())

Finally, execute the script by entering the directory and running

python ping.py

If successful, you should be happily greeted by our API with the response pong printed out on your screen. If the API is in an especially good mood, it may even add some exclamation points.

Please do not be alarmed if the “ping” endpoint responds in complete sentences. It is a very social API. TruSTAR’s data science team is always hard at work implementing fascinating machine-learning models, and there is no telling what sorts of life-like behaviors our platform may begin to exhibit.