`python` is a built-in global object for running Python code from Expr.

It is used directly by name. Do not call `python()`.

Synchronous methods run Python and wait for completion. Asynchronous methods create a `python_task` object.

`python` is a predefined global object. It is not created with a constructor.

value = python.eval('2 + 3 * 5');

`python` currently exposes no public properties.

`clone()` is not supported for `python`.

Evaluates a Python expression string and returns the converted result.

value = python.eval('2 + 3 * 5');
print(value);        // 17

Runs Python code synchronously and returns the Python script result.

The Python code can assign `result` to return a value to Expr.

result = python.run_code('result = 40 + 2');
print(result);       // 42

Runs Python code synchronously with parameters from a `map`.

Each map key becomes a Python variable with the converted Expr value.

result = python.run_code('result = a + b', map('a', 10, 'b', 20));
print(result);       // 30

Runs a Python file synchronously and returns the Python script result.

The file path is resolved by the same host path rules used by Expr file paths.

result = python.run_file('scripts/example.py');

Runs a Python file synchronously with parameters from a `map`.

Each map key becomes a Python variable with the converted Expr value.

result = python.run_file('scripts/example.py', map('a', 10, 'b', 20));

Creates a `python_task` object for asynchronous execution of Python code.

The task is configured first. Call `run()` on the returned object to start it.

task = python.code('result = 7');
task.run();

Creates a `python_task` object for asynchronous execution of Python code with parameters from a `map`.

task = python.code('result = a + b', map('a', 10, 'b', 20));
task.run();

Creates a `python_task` object for asynchronous execution of a Python file.

The task is configured first. Call `run()` on the returned object to start it.

task = python.file('scripts/example.py');
task.run();

Creates a `python_task` object for asynchronous execution of a Python file with parameters from a `map`.

task = python.file('scripts/example.py', map('a', 10, 'b', 20));
task.run();

`python` is a protected built-in global name. The name itself cannot be overwritten.

python = 1;       // error

`python_task` represents asynchronous Python execution.

It is returned by `python.code(…)` and `python.file(…)`. It is configured first, then started once with `run()`.

`python_task` objects are not created with a public constructor.

task = python.code('result = 123');

Properties are read-only. Use methods to configure or control the task.

task = python.code('result = 123');
task.run();
while (!task.completed) {}
print(task.ok, ' ', task.result);

`clone()` is not supported for `python_task`.

Sets a callback called when the task completes.

The callback receives two arguments: `ok` and `result`.

function done(ok, result)
{
    print('done: ', ok, ' ', result);
}
 
task = python.code('result = 123').on_complete(done);
task.run();

Sets a callback called when Python sends an event.

The callback receives two arguments: event name and event value.

function event(name, value)
{
    print(name, ': ', value);
}
 
task = python.code('import planetcnc\nplanetcnc.send_event("status", 10)').on_event(event);
task.run();

Sets whether the task should use a Python sub-interpreter.

This method must be called before `run()`. After the task has started, changing this setting raises an error.

task = python.code('result = 1');
task.use_subinterpreter(false);
task.run();

Starts the task.

A task can be run only once. Calling `run()` again raises an error.

task = python.code('result = 7');
started = task.run();

Reads and removes the next queued event.

Returns a `map` with `name` and `value`, or `none()` if no event is queued. The task keeps a bounded event queue; high-rate events should be read regularly.

task = python.code('import planetcnc\nplanetcnc.send_event("status", 10)');
task.run();
while (!task.completed) {}
 
event = task.read_event();
if (!event.is_none())
{
    print(event.name, ': ', event.value);
}

Sends a command to the running Python script.

Returns `false` if the task has already completed.

task = python.code('import planetcnc\ncmd = planetcnc.read_command()\nresult = cmd["value"] + 1');
task.run();
task.send_command('value', 41);
while (!task.completed) {}
print(task.result);       // 42

Requests termination of the running Python script.

Returns `false` if the task was not started or has already completed.

task = python.code('import planetcnc\nwhile not planetcnc.terminate():\n    pass\nresult = "terminated"');
task.run();
task.terminate();
while (!task.completed) {}
print(task.result);

task = python.code('result = 123');
task.run();
 
while (!task.completed)
{
}
 
if (task.ok)
{
    print(task.result);
}
else
{
    print(task.error);
}

Previous: session

Next: Collections