Lupa: Python Wrapper around Lua and LuaJIT

Warnings

• breaking In Lupa 2.0, Lua stack traces within Python exception messages were reversed to align with Python's stack trace order. If you relied on the previous ordering, your error parsing logic may break.
  Fix: Adjust any code that parses Lua stack traces from Lupa's Python exceptions to account for the reversed order.
• gotcha The behavior of Lua's `#` (length) operator, and thus Lupa's `len()` for wrapped Lua tables, can be unpredictable for tables containing `nil` values ('holes') or primarily acting as mappings. It generally stops at the first `nil` element, making it unsuitable for non-sequence tables. It's best not to rely on `len()` for mappings in Lupa.
  Fix: Avoid using `len()` on Lua tables from Python if they are not strict sequences without `nil` values. Instead, iterate over the table if possible, or ensure Lua-side logic handles table lengths carefully.
• gotcha When passing Python objects to Lua, Lupa employs a heuristic for indexing: if the Python object has a `__getitem__` method, it's preferred for Lua's `obj[x]` and `obj.x` operations. Otherwise, attribute access is used. This can lead to unexpected behavior if an object has both attributes and `__getitem__` and you expect a specific access method from Lua.
  Fix: Be mindful of Python object structure when interacting from Lua. If precise control is needed, you might need to wrap Python objects in Lua with explicit accessors or ensure `__getitem__` is implemented (or not) as desired.
• gotcha Prior to Lupa 2.1, recursive mapping of complex Python data structures (like nested lists/dicts) to Lua tables was not straightforward. Since Lupa 2.1, explicit `recursive=True` is needed in conversion functions (e.g., `LuaRuntime.table_from`) to enable deep conversion.
  Fix: For recursive data structure conversion, ensure you are using Lupa 2.1 or newer and explicitly pass `recursive=True` to the appropriate conversion methods.
• gotcha Importing Lua binary modules (C modules) within a Lupa runtime typically requires CPython to enable global symbol visibility for shared libraries by calling `sys.setdlopenflags`. Lupa attempts to set these flags automatically, but it might fail on some platforms or configurations, leading to module import errors in Lua.
  Fix: If experiencing issues with Lua binary modules, check your system's `dlopen` flags and ensure they are compatible. You might need to manually configure `sys.setdlopenflags` before importing `lupa` if the automatic setup is insufficient. Consult platform-specific documentation for `dlfcn` for correct flag values.

Install

• pip install lupa Basic installation
• pip install lupa --global-option="--with-luajit" Install with LuaJIT (may require LuaJIT dev headers)

Imports

• LuaRuntime

  from lupa import LuaRuntime

• lupa

  import lupa

Quickstart

This quickstart demonstrates basic interoperability: creating a Lua runtime, evaluating Lua code, defining and calling Lua functions from Python, and exposing Python functions and builtins to the Lua environment.

import os
from lupa import LuaRuntime

# Create a Lua runtime instance
lua = LuaRuntime(unpack_returned_tuples=True)

# Evaluate Lua code directly
result_eval = lua.eval('1 + 2')
print(f'Lua eval("1 + 2"): {result_eval}')

# Define a Lua function and call it from Python
lua_add_func = lua.eval('function(x, y) return x + y end')
result_lua_call = lua_add_func(5, 7)
print(f'Called Lua function (5, 7): {result_lua_call}')

# Pass a Python function into Lua and call it
def py_multiply(a, b):
    return a * b

lua.globals().py_multiply = py_multiply
result_python_call_from_lua = lua.eval('py_multiply(3, 4)')
print(f'Called Python function from Lua (3, 4): {result_python_call_from_lua}')

# Access Python builtins from Lua
python_str_from_lua = lua.eval('python.builtins.str(123)')
print(f'Python str from Lua: {python_str_from_lua}')