Python SDK: sdk

The Python version of CTO.ai 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 docker environment and remotely. This SDK depends on:

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

Python SDK Installation

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

Usage

from cto_ai import sdk, ux

sdk.start

Starts a remote command/pipeline/service that belongs to the same team as the workflow that executes the method.

sdk.start() -> str

Example:

def start(
    workflowName: str
):
    """Start a workflow from the sdk"""
    try:
        daemon_request.start_op(dict(trigger=True, workflowName=workflowName, tags=["trigger"]))

sdk.get_host_os

sdk.get_host_os() -> str

Returns the Operating System the host is running on when ran locally. For remote pipelines, commands, and services, it will return "unknown" as no host is accessible in the remote environment.

Output:

Host's os is: darwin

sdk.home_dir

sdk.home_dir() -> str

Returns the home directory of the host machine.

Output:

Host's home directory is: /root

sdk.log

sdk.log(args)

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() -> str

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.config.get

sdk.config.get(key: str) -> str

Gets the value that is saved under the given key in the team configuration store, or None if the key is not set.

sdk.config.set

sdk.config.set(key: str, value: str)

Sets the given value in the team configuration store under the provided key.

sdk.config.delete

sdk.config.delete(key: str) -> bool

Deletes a key-value pair in the persistent team configuration. Returns True if the key exists and the deletion is successful, or False if the key cannot be found.

sdk.config.get_all

sdk.config.get_all() -> dict

Gets all of the keys and values in the team configuration store.

sdk.get_secret

sdk.get_secret(key: str, hidden: Optional[bool] = False) -> str

Requests a secret from the secret store with the given key.

If the secret exists, it is returned. A notification is printed to the user that the secret has been accessed, unless the hidden argument is true.

If the secret does not exist, the user is prompted to provide a replacement, either from the secret store or by direct entry through their interface.

Example

from cto_ai import sdk

secret = sdk.get_secret('SECRET')
# `ux.print` hides secret values but `sdk.log` does not.
sdk.log(f'my secret is {secret}')

Output

my secret is SUPER_SECRET_VALUE

sdk.set_secret

sdk.set_secret(key: str, value: str) -> str

Sets a particular value into the secret store.

If the secret already exists, the user is prompted on whether to overwrite it.

Returns the key that the secret is set to, or null if the user declines to overwrite the existing value.

Example

from cto_ai import sdk, ux

key = sdk.set_secret("secret1", "it's a secret to everybody")
ux.print(key)

Output

secret1

sdk.team

Allows a command to request the basic team information like team id and team name.

Example

from cto_ai import sdk

if __name__ == 'main':
    team = sdk.team()
    sdk.log(team)

Output

{"id": "example-team-uuid", "name": "example"}

sdk.track

The track function allows you to store and retrieve custom analytic data.

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

• (DEPRECATED) tags: (String || String[]) This field has been deprecated, please do not use
• event: (String || String[]) Name of the event you want to track
• metaData: (Object) Data you want to be tracked

Using Track to generate Events for Insights

Tracking Events using CTO.ai can give deep insight into your team’s activity.

To use track to send an Event, place your event data in the metaData field like so:

from cto_ai import sdk

def main():
    event = {
        "event_name": "deployment",
        "event_action": "succeeded",
        "commit": "956b425e5bee",
        "branch": "main",
        "repo": "web"
    }
    sdk.track([], "", event)

if __name__ == "__main__":
    main()

The first two arguments for sdk.track are left blank in this example because they are not used by the metrics dashboard, but they are required by the sdk.track function.

NOTE: currenlty the supported values forevent_action are succeeded or failure.

More information about Insights can be found on the Insights page.

sdk.events

sdk.events(team, filters): Promise<any>

Retrieve workflow events from CTO.ai.

• team: (String || String[]) The team you want to retrieve events for
• filters: (Object) Filters for the events you want to retrieve

sdk.user

User allows an Command to get information about the CTO.ai user running it such as: id, username, & email. For example, you can set the username or email for a text field that corresponds with who created a ticket or flagged an incident.

Example

from cto_ai import sdk

if __name__ == 'main':
    user = sdk.user()
    sdk.log(user)

Output

{"id": "example-user-uuid", "username": "example", "email": "[email protected]"}