Lupa: Python Wrapper around Lua and LuaJIT

Common errors

• ModuleNotFoundError: No module named 'lupa'

  cause This error occurs when the `lupa` package or its underlying C extension modules are not correctly installed or Python cannot find them in its search path. It can also happen if you try to import `lupa` from within its source directory before it has been properly installed.
  fix Ensure `lupa` is installed by running `pip install lupa`. If you are developing and running from the source directory, install it via `python setup.py install` or ensure you are running your script from a directory *outside* the `lupa` source folder. If Cython is missing, install it first: `pip install cython`.

• lupa.lua54.LuaError: error loading module '...' from file '...': dynamic libraries not enabled; check your Lua installation.

  cause This error indicates that the Lua runtime embedded by Lupa is configured to prevent loading dynamic C modules (e.g., `.so` or `.dll` files), which is often a security measure or a build-time configuration.
  fix To enable dynamic library loading, you need to set the appropriate `dlopen` flags for CPython before importing `lupa`. Add `import sys, os; sys.setdlopenflags(os.RTLD_NOW | os.RTLD_GLOBAL)` before `import lupa`. Some environments or `lupa` versions might attempt to set this automatically.

• lupa._lupa.LuaError: Failed to initialise Lua runtime

  cause This error typically means that Lupa could not properly initialize the Lua or LuaJIT runtime. This is often due to missing shared libraries (like `libluajit-5.1.so` or `lua51.dll`), an incompatible LuaJIT/Lua version, or incorrect build configuration preventing Lupa from linking with the Lua runtime.
  fix Verify that LuaJIT or Lua (the version Lupa was built against) is correctly installed and its shared libraries are discoverable by your system's linker (e.g., in `LD_LIBRARY_PATH` on Linux). Reinstalling `lupa` after ensuring LuaJIT/Lua development files are present might resolve the issue. If building manually, ensure the `LuaJIT` or `Lua` source is in the correct directory relative to `lupa`'s `setup.py` during compilation.

• error loading code: [string "<python>"]:1: unexpected symbol near 'for'

  cause This specific Lua error occurs when you try to execute Lua *statements* (like a `for` loop, variable assignments, or function definitions) using the `lua.eval()` method. The `eval()` method expects a Lua *expression* that returns a single value.
  fix Use the `lua.execute()` method for executing Lua statements or blocks of code. `lua.execute()` is designed to run arbitrary Lua code that doesn't necessarily return a value, or that may define functions or manipulate the Lua environment. ```python import lupa lua = lupa.LuaRuntime() lua.execute("""for i=1,4 do print(i) end""") ```

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}')