poema cloud

Python SDK

poema is a client of poema's API for Python 3.9 or later, standard library only; the quickstart installs it. Poema() takes the API's URL and your key from the environment, and your namespace from the key:

export POEMA_URL=https://127.0.0.1:7070
export POEMA_API_KEY=poema_ns_...

An instance, start to end

from poema import Poema

p = Poema()
t = p.create_task("work", ["sleep", "infinity"], gateway="default", debug=True)

box = t.connect()                      # its commands and files, as it was made with debug=True
box.run("git clone --depth 1 https://github.com/octocat/Hello-World repo", cwd="/workspace")
box.write("/workspace/repo/NOTES.md", "look at the README first")
print(box.run("ls -la", cwd="/workspace/repo").stdout)

t.suspend()                            # it stops, its memory and files kept
t.wait("Suspended")
forks = t.fork("try-a", "try-b")       # each runs its command again on a copy of its /workspace
t.resume()                             # it carries on where it stopped
for x in [t, *forks]:
    x.delete()

Calls

  • create_task(name, command, image=, env=, workspaces=, gateway=, model=, timeout_seconds=, debug=, wait=, **spec) creates or updates an instance and waits until it runs. image= names the image it runs, one of the runtimes (Deploy from git); without it, the base image. debug=True lets connect reach into it.
  • task(name) is an instance by name.
  • Task.get(), .wait(phase), .wait_exit(), .logs(follow=) and .events() read it. logs(follow=True) streams for as long as the instance runs, so break out when done.
  • Task.suspend(), .resume(), .set_timeout(seconds) and .delete() act on it.
  • Task.fork(*names, memory=) forks a suspended instance into a new one of each name, each running its command again on a copy of its workspace, or with memory=True going on from a copy of its memory too, and returns them.
  • Task.connect() reaches into the instance: run(cmd, cwd=, env=, timeout=), read(path), write(path, data) and list(path). A command gets no stdin, and one still running at its timeout is killed and returns its output so far, with timed_out set.
  • apply(manifest), get(kind, name), list(kind) and delete(kind, name) handle Tasks, Workspaces, Gateways and Models as manifests (Concepts).
  • set_secret(name, data) stores provider keys; nothing reads them back.
  • usage(start, end) is what your namespace used, by day: compute and model spend.

Every error, a server that does not answer included, is PoemaError, with .status (0 without an answer), .code and .message.