SDKs

Install and import

The command pip install kloudlite installs a different package, the client of the model and dataset hub. It is not this SDK, so copy kloudlite.py into your project instead.

Secret references

An environment value refers to a secret of the owner as ${{ secrets.NAME }}. With a team owner, the secrets calls work on your own secrets in that team; give the scope team for the secrets of the team. The secrets API lists the routes that take a reference.

Pipeline definitions

The definition of pipelines.create and pipelines.update is plain data in the shape of Pipeline definition. Python takes a dict, Ruby a hash and TypeScript an object. Go takes the struct PipelineDefinition, and Java the builder class PipelineDefinition.

The order of jobs, inputs and each matrix is part of the definition. Python, Ruby and TypeScript keep the order that you write. Go keeps the order of its Jobs and Inputs slices, and Java the order of its job and input calls.

A save returns the pipeline with its version. rotate_webhook returns the new URL, which no later call shows.

Authentication and base URL

The SDK uses the login of kloudlite, so a client needs no arguments. It takes the API origin and the CLI token from the first source that has each, adds /v1 to the origin, and sends the token as Authorization: Bearer.

config.json is in KLOUDLITE_CONFIG_DIR, or in ~/.config/kloudlite. With no token, the SDK stops with no Kloudlite login: pass token=, set KLOUDLITE_TOKEN, or run kloudlite login (Go returns it from the first call). For a CI job or a server with no kloudlite, set KLOUDLITE_URL and KLOUDLITE_TOKEN. The token must be a CLI token: an API token does not open /v1. Every request times out after 30 seconds, set with timeout (Python, Ruby), timeoutMs (TypeScript) or Options.Timeout (Go).

Inputs, results and errors

Every input is named. Python takes keyword-only arguments, Ruby keywords, TypeScript one options object, Go one request struct (kloudlite.CreateWorkspace{Workspace: …}) and Java a nested params class (new Kloudlite.CreateWorkspace().workspace(…)).

A workspace, environment or session is "name" for your own or "team/name" for a team's, or its id. Something new made from an existing one is to.

Every method returns the decoded JSON of the route, except the sandbox and pipeline handles below. Java returns the raw JSON string from every method, except those two.

Errors, one per SDK:

• Python: ApiError with status and message; SandboxTerminated, a subclass, when a sandbox that you wait for has ended.
• TypeScript: ApiError with status and message; TimeoutError when a client-side wait runs out. A terminated sandbox is an ApiError with status 409.
• Go: *ApiError with Status and Message; ErrTimeout, tested with errors.Is, when a wait runs out. A terminated sandbox is an *ApiError with status 409.
• Ruby: Kloudlite::ApiError with status and message; SandboxTerminated < ApiError; TimeoutError when a wait runs out.
• Java: Kloudlite.ApiException, an IOException, with public status and message.

A missing required field is refused before anything is sent: ValueError in Python, an IllegalArgumentException in Java.

Methods

Resources hang off the client under these names: workspaces, environments, sessions, volumes, secrets, connectors, sandboxes and pipelines. Java reaches them as a call, kl.workspaces(), and Go as the field kl.Workspaces. The ide, sandbox, process and run rows are on objects that those methods return. workspaces.ide returns the tool-server client. sandboxes.create and get return a sandbox handle, and the exec method of a sandbox returns a process handle. pipelines.run and get_run return a run handle.

Python also has an .aio form of its calls for asyncio. Every cell is the method name in that language.

The tool-server rows call the tool server directly with the workspace's token, so they take the tool's own arguments. The SDKs have no method for these resources: teams, invites, keys, tokens, container images, requests, regions and builders.

Two tool-server tools have no typed method, process_close_stdin and process_wait; call reaches them in every language.