Python SDK

Note: This page explains using The Ops Platform SDK in Python. The SDK can also be used in other programming languages such as Node.js.

The Python version of The Ops Platform SDK works in conjunction with our Docker base images. The SDK allows the development of automations with rich user interfaces, that run in both the local terminal and in our Slack App as Slack Ops. Other than The Ops Platform itself, this SDK depends on:

  • Python 3.6+
  • The requests library, version 2+

The Python SDK is an open-source project which can be found on GitHub here: https://github.com/cto-ai/sdk-python

Install

The Python installer can be found on PyPi here: https://pypi.org/project/cto-ai

It can be installed with this command:

pip install cto-ai

sdk.get_host_os

sdk.get_host_os(): string

Returns the Operating System the host is running on. For remote ops, will return "unknown" as no host is accessible in the remote environment.

Output:

Host's os is: darwin

sdk.home_dir

sdk.home_dir(): string

Returns the home directory of the host machine.

Output:

Host's home directory is: /root

sdk.log

sdk.log(...args: any[]): void

Logs to the console in in a standardized way. Will not be relayed to
the user in a remote environment (use ux.print for that).

Output:

I am a log!
I am too!

sdk.get_state_path

sdk.get_state_path(): string

Returns the path of the state directory. The contents of this directory are persistent through a workflow, including on remote.

Output:

The state path is: /root/.config/@cto.ai/ops/superman/test-op/00000000-1111-2222-3333-444444444444

sdk.get_config_path

sdk.get_config_path(): string

Returns the path of the config directory. This directory is persistent across multiple runs of the op if the mountHome option in ops.yml is set to true.

Output:

The config path is: /root/.config/@cto.ai/ops/superman/test-op

sdk.state.set

sdk.state.set(key: string, value: any): Promise<void>

Stores a key-value pair in the workflow-local state. If the key is already present, the value will be replaced with the one provided.

Output:

Initial state undefined
Inserted state Value one
Updated state Value two

sdk.state.get

sdk.state.get(key: string): Promise<any>

Gets the value that is saved under the given key in the workflow-local state, or undefined if the key is not set.

sdk.get_config

sdk.get_config(key: string): Promise<any>

Gets the value that is saved under the given key in the persistent configuration, or undefined if the key is not set.

sdk.track

sdk.track(tags, metadata): Promise<any>

Send an analytics tracking event to the Ops Platform.

  • tags: (String || String[]) Tags for the event you want to track
  • metaData: (Object) Data you want to be tracked

Terminology

Config

The SDK provides persistent config so that your op can store data on the host between executions. This can be accessed with the sdk.state.set and sdk.state.get functions.

  • The config is stored in a JSON file at the host path ~/.config/@cto.ai/ops/${username}/${opName}/config.json
  • Configs are persisted if the code is executed multiple times
  • Each Op has its own config, and cannot affect any other Op's config

State

The SDK provides a mechanism for maintaining state through the different steps of a workflow. Anything stored in the state directory (found with sdk.get_state_path) will be available in later steps. Additionally, the SDK provides key/value storage in the state similar to the config.

  • Locally, the state is stored in the following directory: ~/.config/@cto.ai/ops/${username}/${opName}/${runId}, with the key/value store saved in `state.json therein.
  • Each execution of a workflow is a different run and will have a different state, which will initially be blank.