REPL Reference

The Repl class is used for executing multiple instructions on a ForeverVM machine.

Each instruction will share any state from previous instructions — just like a real Python REPL. This means you can, for example, define a function with one instruction and call it in the next.

Repl

Instantiate the client with your ForeverVM API token:

Python

from forevervm_sdk import Repl

repl = Repl("your_forevervm_token")

JavaScript

import { Repl } from '@forevervm/sdk'

const repl = new Repl({ token: "your_forevervm_token" });

If you store your API token in the FOREVERVM_TOKEN environment variable, the ForeverVM client will detect it:

Python

from forevervm_sdk import Repl

repl = Repl()

JavaScript

import { Repl } from '@forevervm/sdk'

const repl = new Repl();

Note

If you don’t have a ForeverVM API token yet, check out the getting started guide.

To connect to a specific machine, you can pass the machine name when instantiating a Repl:

Python

from forevervm_sdk import Repl

repl = Repl(machine_name="9kaTDWiKdAvaIZNE")

JavaScript

import { Repl } from '@forevervm/sdk'

const repl = new Repl({ machine: "9kaTDWiKdAvaIZNE" });

Running Code

To run code on the machine, use Repl.exec:

Python

instruction = repl.exec("1 + 1")

JavaScript

const instruction = repl.exec("1 + 1");

Repl.exec synchronously returns an object with the following type definition:

Python

class ExecResultBase(TypedDict):
    runtime_ms: int


class ExecResultValue(ExecResultBase):
    value: Optional[str]
    data: Optional[Dict[str, Any]]


class ExecResultError(ExecResultBase):
    error: str


ExecResult = ExecResultValue | ExecResultError

class StandardOutput(TypedDict):
    stream: Literal["stdout"] | Literal["stderr"]
    data: str


class ReplExecResult:
    result: ExecResult
    output: Generator[StandardOutput, Any, None]

Note

Currently, there is no asynchronous version of the Python Repl.

JavaScript

interface ExecResponse {
  value?: string | null
  data?: { [key: string]: unknown }
  error?: string
  runtime_ms: number
}

interface StandardOutput {
  stream: 'stdout' | 'stderr'
  data: string
  seq: number
}

interface ReplExecResult {
  result: Promise<ExecResponse>;
  output: AsyncIterableIterator<StandardOutput, void, unknown>
}

Getting Results

If the instruction is an expression that evaluates to a value, it will be available as a string on the result property:

Python

instruction = repl.exec("1 + 1")

print(instruction.result["value"]) # "2"

JavaScript

const instruction = repl.exec("1 + 1");

const result = await instruction.result;
console.log(result.value); // "2"

Getting Output

Anything logged to stdout or stderr can be found on the output property:

Python

instruction = repl.exec("for i in range(3): print(i)")

for output in instruction.output:
    print(output["stream"], output["data"])

JavaScript

const instruction = repl.exec("for i in range(3): print(i)");

for await (const output of instruction.output) {
  console.log(output.stream, output.data);
}

output is an iterable, so you can traverse it in a loop.

Handling Errors

If the call to Repl.exec results in a Python exception within the interpreter, it will be available as a string on the result.error property:

Python

instruction = repl.exec("1 / 0")

print(instruction.result["error"])
# """
# Traceback (most recent call last):
#   File "<foreverVM>", line 1, in <module>
#   ZeroDivisionError: division by zero
# """

JavaScript

const instruction = repl.exec("1 / 0");

const result = await instruction.result;
console.log(result.error);
// `
// Traceback (most recent call last):
//   File "<foreverVM>", line 1, in <module>
//   ZeroDivisionError: division by zero
// `

If the call to Repl.exec results in an error communicating with the ForeverVM machine (for example, if you lose your Internet connection) instruction.result will raise an exception.