PyCKt — Python 3 bindings for GoKt

Python 3 bindings for the GoKt LittleKt interpreter. API follows PyKt — "everything is a variable".

Install

pip install git+https://github.com/LittleKt-Lang/PyCKt.git

Build the GoKt shared library first:

cd GoKt && CGO_ENABLED=1 go build -tags cshared -buildmode=c-shared -o gokt.dll ./ffi/

Then tell PyCKt where to find it:

import pyckt
rt = pyckt.create_runtime("/path/to/gokt.dll")
# or: export PYCKT_DLL_PATH=/path/to/gokt.dll

Quick Start

import pyckt

rt = pyckt.create_runtime("/path/to/gokt.dll")

# Run code — returns self for chaining
rt.run('println("Hello!")')

# Inject values (auto-detected)
rt.inject("PI", 3.14159, mutable=False)
rt.inject("name", "PyCKt")

# Inject functions
rt.inject("add", lambda a, b: a + b)

# Inject classes
class Dog:
    def __init__(self, name, age):
        self.name = name
        self.age = age
    def bark(self):
        return f"{self.name} barks!"

rt.inject("Dog", Dog)

# Use everything from LittleKt
rt.run('''
    val d = Dog("Rex", 5)
    println(d.bark())
    println("PI = " + PI)
    println("add(3, 4) = " + add(3, 4))
''')

# Get values back
print(rt['PI'])        # 3.14159
print(rt.get('name'))  # "PyCKt"

# Error handling
rt.run('val x = 1 / 0')
print(rt.had_error)        # True
print(rt.error_message)    # "[line 1: col 11] Error: Division by zero"
print(rt.traceback)        # full Go stack trace

rt.close()

API

rt = pyckt.create_runtime(dll_path=None, handle=None)

Execution

Method	Description
rt.run(source, filename="\<python\>")	Execute LittleKt code. Returns self.
rt.run_file(filepath)	Execute a .kt file. Returns self.

Unified Injection

rt.inject(name, value, mutable=True) auto-detects the type:

Python type	LittleKt side
int, float, bool, str, None	value
callable (function / lambda)	callable function
type (class)	instantiable class (new / .prop / .method())

Retrieval

Method	Description
rt.get(name) / rt[name]	Get a variable as Python value
rt.get_value(name)	Get a variable as opaque handle
rt.call(name, *args)	Call a named LittleKt function
rt.contains(name) / name in rt	Check existence
rt.variables	List of global variable names

Error API (PyKt-compatible)

Property	Description
rt.had_error	True if the last run encountered an error
rt.error_message	Last error message
rt.traceback	Full Go stack trace for the last error

Lifecycle

Method	Description
rt.close()	Destroy runtime
rt.handle	Raw gokt_handle for direct C ABI use
with rt: / rt.close()	Context manager + manual close

Exceptions from Python

If an injected Python function or class method raises, the exception is converted to a RuntimeException that LittleKt code can catch:

rt.inject("risky", lambda x: 1 / x)
rt.run('''
    try { risky(0) }
    catch (e: RuntimeException) { println("Caught: " + e) }
''')

Requirements

• Python 3.7+
• GoKt shared library

License

MIT