docs/

Python Executor Documentation

Remote Python code execution service with client libraries for Python, Go, and CLI.

Quick Links

Getting Started

Choose Your Interface

For AI Agents / Simple Integrations: Use the JSON-based /api/v1/eval endpoint:

curl -X POST http://pyexec.cluster:9999/api/v1/eval \
  -H "Content-Type: application/json" \
  -d '{"code": "print(2 + 2)"}'

For Python Applications:

from python_executor_client import PythonExecutorClient

client = PythonExecutorClient("http://pyexec.cluster:9999/")
result = client.execute_sync(
    files={"main.py": "print('Hello!')"},
    entrypoint="main.py"
)
print(result.stdout)

For Go Applications:

c := client.New("http://pyexec.cluster:9999/")
tarData, _ := client.TarFromMap(map[string]string{
    "main.py": `print("Hello!")`,
})
result, _ := c.ExecuteSync(ctx, tarData, &client.Metadata{
    Entrypoint: "main.py",
})
fmt.Println(result.Stdout)

For Shell Scripts / CLI:

echo 'print("Hello")' | python-executor --server http://pyexec.cluster:9999/ run

Installation

Python Client

pip install git+https://github.com/geraldthewes/python-executor.git#subdirectory=python

Go Client

go get github.com/geraldthewes/python-executor/pkg/client

CLI

# Build from source
make build-cli
sudo cp bin/python-executor /usr/local/bin/

Server

Running the Server

# Build
make build-server

# Run locally
./bin/python-executor-server

Docker

docker run -p 8080:8080 -v /var/run/docker.sock:/var/run/docker.sock \
  registry.cluster:5000/python-executor:latest

API Overview

See HTTP API Reference for full details.

Documentation Generation

This documentation is partially auto-generated from source code:

# Generate all docs
make docs-generate

# Test examples against deployed server
make docs-test

# Full pipeline (generate + test)
make docs