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
- … for more see Services section
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
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.
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.
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
library in a file called
#!/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
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
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.
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.
The Installation walked through setting up a brand new space from scratch and creating services.
You may have noticed methods such as
create_timeseries(). The following diagram depicts the process flow for what
these create methods execute:
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.
- create service is similar to running
cf create-servicebut has sensible defaults to get going quickly
- create service key is similar to running
cf create-service-keyand avoids needing to create an initial app
- get service key is similar to
cf get-service-keyto fetch details about the service such as a URI endpoint, Predix-Zone-Ids, etc.
- grant client is similar to
uaacin that it will use the service key details to setup the needed scopes and authorities for the client id used in the app
- write manifest persists the environment variables in the manifest for later use
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:
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.
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:
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.
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.
See the Predix Volcano App for a full demonstration of the SDK used in a Python Flask App.