Getting Started

The following services are supported.

  • User Account and Authentication (UAA)
  • Predix Access Control (ACS)
  • Predix Asset
  • Predix Time Series
  • Predix Blob Store
  • Predix Cache
  • Predix Database as a Service
  • Predix Event Hub
  • Logging
  • … for more see Services section

Installation

Install it from PyPI:

pip install predix

If that isn’t working for you, we highly recommend The Hitchiker’s Guide to Properly Installing Python to learn about installing python, pip, and virtualenv for your environment. For industrial environments, you may also need to learn how to set your proxies.

If you run into trouble installing check out the Installation Recipes for more help.

First Steps

The Predix Python SDK helps you (1) create services in your space, (2) configure your app to work with those services, and (3) communicate with those services.

Important

In order to use the Predix Python SDK to communicate with services it must be configured to know how to find the ones provisioned in your space. This is accomplished with environment variables. For example, PREDIX_SECURITY_UAA_URI is expected to be set for your UAA instance.

Fortunately, the SDK can help with that.

Before we begin, we need to log into a Predix API endpoint and create a space for us to experiment in.

cf login
cf create-space predixpy-demo
cf target -s predixpy-demo

It is often helpful to be able to completely reproduce a space with all of the services and initial data for it to work – a dev, qa, and prod environment for example. By using the Python SDK we can generate a script that will do this replication for us.

Let’s start by initializing some services using the predix.admin.app library in a file called initialize-space.py.

#!/bin/env python

import predix.admin.app
admin = predix.admin.app.Manifest()

admin.create_uaa('admin-secret')
admin.create_client('client-id', 'client-secret')

admin.create_timeseries()

This simple admin script would be run only once at the beginning of a project to:

  • create an instance of UAA
  • create a client for your application
  • create an instance of Predix Time Series
  • grant the client the authorities and scopes for Predix Time Series
  • stores environment variables in manifest.yml so you can work both locally or the cloud

Run the script and you should be able to see services in your space such as predix-timeseries and predix-uaa.

python initialize-space.py
cf services

Warning

You don’t want to deploy admin scripts to a Cloud Foundry environment. Their purpose is to set up your environment in the first place.

You should also avoid checking your manifest.yml into a public revision control system unless you’ve encrypted your secrets.

Now that you’ve created services and configured your manifest.yml you can begin sending data to these services. Create a new script called app.py to do the following:

#!/bin/env python

import predix.app

app = predix.app.Manifest()
ts = app.get_timeseries()

ts.send('TEMP', 70.1)
for val in ts.get_values('TEMP'):
    print(val)

Once you understand how the Predix Python SDK works this simple script is all you need to send data to Predix Time Series. The SDK takes care of many details for you:

  • generating a uaa token
  • constructing request headers and the json body
  • establishing a websocket connection
  • making the service calls
  • handling failures and retries

This simple demonstration was for Time Series but the basic pattern follows for any of the services currently supported by the SDK with more on the way.

Concepts

Manifest Apps

The primary usage for the SDK is an application framework that persists configuration details in the Cloud Foundry manifest.yml. This is not strictly necessary to make use of the SDK, but it is helpful as any environment variables the SDK needs to interact with services are loaded.

To understand how the SDK works we’ll explore its various behaviors while logged into Cloud Foundry.

Creating Services

The Installation walked through setting up a brand new space from scratch and creating services.

You may have noticed methods such as create_uaa() and create_timeseries(). The following diagram depicts the process flow for what these create methods execute:

../_images/predixpy-create.png

The SDK makes REST calls against the Cloud Foundry API endpoint to handle setup operations. The output is a manifest.yml written to disk with configuration settings for accessing that service.

  1. create service is similar to running cf create-service but has sensible defaults to get going quickly
  2. create service key is similar to running cf create-service-key and avoids needing to create an initial app
  3. get service key is similar to cf get-service-key to fetch details about the service such as a URI endpoint, Predix-Zone-Ids, etc.
  4. grant client is similar to uaac in that it will use the service key details to setup the needed scopes and authorities for the client id used in the app
  5. write manifest persists the environment variables in the manifest for later use

Consuming Services

By using the SDK for Creating Services, consuming those services will be straightforward and symmetrical across runtime environments. See the following diagram to represent the process flow:

../_images/predixpy-get.png

The previous step saw the creation of services and service keys which are stored in the manifest.yml. When we start consuming services, the manifest.yml is read and all the environment variables loaded whether running locally or in a Cloud Foundry envrionment. This allows methods like get_timeseries() to know which time series instance to use.

For example, PREDIX_SECURITY_UAA_URI will contain the endpoint for your UAA service instance and PREDIX_DATA_TIMESERIES_INGEST_ZONE_ID will have the Predix-Zone-Id for ingesting into Predix Time Series.

If you don’t want to use the SDK to create the services or persist the details in your manifest.yml you can use any means you prefer to initialize these envrionment variables. The SDK will raise an error if you try to use predix.data.timeseries.TimeSeries but have not yet defined the UAA and Predix Time Series environment variables.

Opinionated

The predix.admin.app framework is opinionated in naming and choosing service plans to use. These will not work for all cases so you exchange some flexibility for ease of use.

For new developers on Predix, reducing the cognitive overhead of making these decisions may be an acceptable trade-off. As you become more experienced, you can override these with your own service names, different plans, or pass any arbitrary parameters.

For example, instead of:

app.create_timeseries()

you could view the source-code and call the underlying library directly:

import predix.admin.app
import predix.admin.timeseries

# Create the service with new name and plan
ts = predix.admin.timeseries.TimeSeries(name='my-timeseries', plan_name='Tiered')
ts.create()

# Use App Framework to persist environment and setup client grants
admin = predix.admin.app.Manifest()
ts.add_to_manifest(admin)
ts.grant_client(admin.get_client_id())

Now that you have the basics under your belt, you can start using Predix Python SDK to work with Services.

Building Apps

The SDK is a client library for service calls and its purpose is to help developers build many different types of apps.

  • CLI tools
  • Data engineering tasks
  • Standalone GUIs
  • Web applications with Flask, Django, Turbogears, etc.
  • Microservices

See the Predix Volcano App for a full demonstration of the SDK used in a Python Flask App.