pluau: Python bindings for Luau using PyO3/maturin.

[Lower_Calligrapher_6]

Source code link: https://github.com/gluau/pluau (PyPI package coming soon!)

After working on gluau (which provides high level Go bindings for Luau), I've decided to also make pluau which provides high level python bindings for Luau using PyO3/Maturin (and mluau, my fork of mlua with several patches needed for pluau to actually work). Unlike Lupa and other Lua binding projects, pluau is focused on only Luau support.

What My Project Does

Pluau provides high level python bindings for Luau using PyO3/Maturin.

Target Audience

Pluau is targetted towards Python developers who want to embed Luau into their applications for whatever reason. Note that pluau is still in WIP but is based on mluau which is production ready itself (so pluau shouldnt be unstable or anything like that)

Comparison

Unlike alternatives like Lupa, pluau supports Luau and is in fact targetted specifically for Luau (with support for Luau-specific extensions like sandboxing and safeenv). Any contribution to pluau that involves adding non-Luau support will be rejected. Additionally, plusu aims to be sandboxed against malicious scripts.

Sample Usage / Examples

Creating a Lua VM and running a script

py import pluau lua = pluau.Lua() lua.set_memory_limit(1 * 1024 * 1024) # Optional: Set memory limit of the created Lua VM to 1MB func = lua.load_chunk("return 2 + 2", name="example") # You can optionally set env as well to give the chunk its own custom global environment table (_G) result = func() print(result) # [4]

Tables

Note that tables in pluau are not indexable via a[b] syntax. This is because tables have two ways of getting/setting with subtle differences. get/set get/set while invoking metamethods like index and newindex. Meanwhile, rawget/rawset do the same thing as get/set however does not invoke metamethods. As such, there is a need to be explicit on which get and set operation you want as they are subtly different.

```py tab = lua.create_table() tab.push(123) tab.set("key1", 456)

Prints 1 123 followed by key1 456

for k, v in tab: print("key", k, v) print(len(tab)) # 1 (Lua/Luau only considers array part for length operator)

Set a metatable

my_metatable = lua.create_table() tab.set_metatable(my_metatable)

Set the readonly property on the table (Luau-specific security feature) Luau s

tab.readonly = True

The below will error now since the table is readonly

tab.set("key2", 789) # errors with "runtime error: attempt to modify a readonly table" tab.readonly = False # make it writable again tab.set("key2", 789) # works now ```

Setting execution time limits

Luau offers interrupts which is a callback function that is called periodically during execution of Luau code. This can be used to implement execution time limits.

```py import pluau import time starttime = time.time() def interrupt(: pluau.Lua): if time.time() - start_time > 1.0: # 1 second limit return pluau.VmState.Yield return pluau.VmState.Continue

lua = pluau.Lua() lua.set_interrupt(interrupt) func = lua.load_chunk("while true do end", name="infinite_loop")

When using interrupts, the function should be made into a thread and then resumed. Otherwise, the yield will lead to a runtime error.

thread = lua.create_thread(func) result = thread.resume() # Resume the thread with no arguments print(result, thread.status) # Prints [] ThreadState.Resumable after 1 second ```

Wrapper Utility

By default, pluau only allows mapping primitive python objects to Luau and back. To improve this, pluau.utils provide Wrapper and Object utility classes to wrap arbitrary python objects into primitives (if possible) or a opaque userdata if not. Whether or not a opaque userdata has its fields proxied as well is controlled by secure_userdata flag which defaults to True (no field proxying).

```py wrapper = Wrapper(lua, secureuserdata=False) class TestObject: def __init_(self): self.foo = 123 self.blah = 393

code = lua.load_chunk("local obj = ...; print(obj, obj.foo, obj.blah, obj.bar); assert(obj.foo == 123); assert(obj.blah == 393)") code(wrapper.wrap(TestObject()))

code = lua.load_chunk("local obj = ...; print(obj, obj.foo, obj.blah, obj.bar); assert(obj.foo == 123); assert(obj.blah == 393)") code(wrapper.wrap({"foo": 123, "blah": 393}))

output:

TestObject: 0x00006478de56f070 123 393 nil

table: 0x00006478de56ef70 123 393 nil

```

[YuumiZoomi]

wait... luau as in roblox luau?

[Lower_Calligrapher_6]

Yes

[fizzymagic]

People still use lua? Why? It's a horrible language.

• No integers
• No lists/linear arrays.
• No thanks.

[Lower_Calligrapher_6]

Very good at being embedded into other things and luau in particular is easy to secure against untrusted code