Lupa is a Python library that seamlessly integrates the runtimes of Lua or LuaJIT2 into CPython. It enables Python developers to embed Lua code, call Lua functions from Python, and interact with Python objects from within Lua. Key features include separate Lua runtime states, Python coroutine wrappers for Lua coroutines, and robust iteration support between the two languages. Currently at version 2.6, Lupa is actively maintained, with releases focusing on cross-version compatibility and feature enhancements.
pip install lupaVerified import paths — ran on the pinned version, not inferred.
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.
Adjust any code that parses Lua stack traces from Lupa's Python exceptions to account for the reversed order.
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.
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.
For recursive data structure conversion, ensure you are using Lupa 2.1 or newer and explicitly pass `recursive=True` to the appropriate conversion methods.
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.
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`.
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.
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.
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""")
```