Package: randovania-lupa
Randovania-LupaThis is a fork of Lupahttps://github.com/scoder/lupaIntended to be used with Randovania projects.See the following for the original Readme and authorship. (Slightly modified to pass doctest)LupaLupa integrates the runtimes ofLuaorLuaJIT2into CPython.
It is a partial rewrite ofLunaticPythoninCythonwith some
additional features such as proper coroutine support.For questions not answered here, please contact theLupa mailing list.Major featuresWhy the name?Why use it?Which Lua version?ExamplesPython objects in LuaIteration in LuaNone vs. nilLua TablesPython CallablesLua CoroutinesThreadingRestricting Lua access to Python objectsRestricting Lua Memory UsageImporting Lua binary modulesBuilding with different Lua versionsMajor featuresseparate Lua runtime states through aLuaRuntimeclassPython coroutine wrapper for Lua coroutinesiteration support for Python objects in Lua and Lua objects in
Pythonproper encoding and decoding of strings (configurable per runtime,
UTF-8 by default)frees the GIL and supports threading in separate runtimes when
calling into Luatested with Python 2.7/3.5 and laterships with Lua 5.3 and 5.4 (works with Lua 5.1 and later)
as well as LuaJIT 2.0 and 2.1 on systems that support it.easy to hack on and extend as it is written in Cython, not CWhy the name?In Latin, “lupa” is a female wolf, as elegant and wild as it sounds.
If you don’t like this kind of straight forward allegory to an
endangered species, you may also happily assume it’s just an
amalgamation of the phonetic sounds that start the words “Lua” and
“Python”, two from each to keep the balance.Why use it?It complements Python very well.  Lua is a language as dynamic as
Python, but LuaJIT compiles it to very fast machine code, sometimes
faster than many statically compiled languages for computational code.
The language runtime is very small and carefully designed for
embedding.  The complete binary module of Lupa, including a statically
linked LuaJIT2 runtime, only weighs some 700KB on a 64 bit machine.
With standard Lua 5.1, it’s less than 400KB.However, the Lua ecosystem lacks many of the batteries that Python
readily includes, either directly in its standard library or as third
party packages. This makes real-world Lua applications harder to write
than equivalent Python applications. Lua is therefore not commonly
used as primary language for large applications, but it makes for a
fast, high-level and resource-friendly backup language inside of
Python when raw speed is required and the edit-compile-run cycle of
binary extension modules is too heavy and too static for agile
development or hot-deployment.Lupa is a very fast and thin wrapper around Lua or LuaJIT.  It makes it
easy to write dynamic Lua code that accompanies dynamic Python code by
switching between the two languages at runtime, based on the tradeoff
between simplicity and speed.Which Lua version?The binary wheels include different Lua versions as well as LuaJIT, if supported.
By default,import lupauses the latest Lua version, but you can choose
a specific one via import:try:importlupa.luajit20aslupaexceptImportError:try:importlupa.lua54aslupaexceptImportError:try:importlupa.lua53aslupaexceptImportError:importlupaprint(f"Using{lupa.LuaRuntime().lua_implementation}(compiled with{lupa.LUA_VERSION})")Note that LuaJIT 2.1 may also be included (asluajit21) but is currently in Alpha state.Examples>>>importrandovania_lupaaslupa>>>fromrandovania_lupaimportLuaRuntime>>>lua=LuaRuntime(unpack_returned_tuples=True)>>>lua.eval('1+1')2>>>lua_func=lua.eval('function(f, n) return f(n) end')>>>defpy_add1(n):returnn+1>>>lua_func(py_add1,2)3>>>lua.eval('python.eval(" 2 ** 2 ")')==4True>>>lua.eval('python.builtins.str(4)')=='4'TrueThe functionlua_type(obj)can be used to find out the type of a
wrapped Lua object in Python code, as provided by Lua’stype()function:>>>lupa.lua_type(lua_func)'function'>>>lupa.lua_type(lua.eval('{}'))'table'To help in distinguishing between wrapped Lua objects and normal
Python objects, it returnsNonefor the latter:>>>lupa.lua_type(123)isNoneTrue>>>lupa.lua_type('abc')isNoneTrue>>>lupa.lua_type({})isNoneTrueNote the flagunpack_returned_tuples=Truethat is passed to create
the Lua runtime.  It is new in Lupa 0.21 and changes the behaviour of
tuples that get returned by Python functions.  With this flag, they
explode into separate Lua values:>>>lua.execute('a,b,c = python.eval("(1,2)")')>>>g=lua.globals()>>>g.a1>>>g.b2>>>g.cisNoneTrueWhen set to False, functions that return a tuple pass it through to the
Lua code:>>>non_explode_lua=lupa.LuaRuntime(unpack_returned_tuples=False)>>>non_explode_lua.execute('a,b,c = python.eval("(1,2)")')>>>g=non_explode_lua.globals()>>>g.a(1,2)>>>g.bisNoneTrue>>>g.cisNoneTrueSince the default behaviour (to not explode tuples) might change in a
later version of Lupa, it is best to always pass this flag explicitly.Python objects in LuaPython objects are either converted when passed into Lua (e.g.
numbers and strings) or passed as wrapped object references.>>>wrapped_type=lua.globals().type# Lua's own type() function>>>wrapped_type(1)=='number'True>>>wrapped_type('abc')=='string'TrueWrapped Lua objects get unwrapped when they are passed back into Lua,
and arbitrary Python objects get wrapped in different ways:>>>wrapped_type(wrapped_type)=='function'# unwrapped Lua functionTrue>>>wrapped_type(len)=='userdata'# wrapped Python functionTrue>>>wrapped_type([])=='userdata'# wrapped Python objectTrueLua supports two main protocols on objects: calling and indexing.  It
does not distinguish between attribute access and item access like
Python does, so the Lua operationsobj[x]andobj.xboth map
to indexing.  To decide which Python protocol to use for Lua wrapped
objects, Lupa employs a simple heuristic.Pratically all Python objects allow attribute access, so if the object
also has a__getitem__method, it is preferred when turning it
into an indexable Lua object.  Otherwise, it becomes a simple object
that uses attribute access for indexing from inside Lua.Obviously, this heuristic will fail to provide the required behaviour
in many cases, e.g. when attribute access is required to an object
that happens to support item access.  To be explicit about the
protocol that should be used, Lupa provides the helper functionsas_attrgetter()andas_itemgetter()that restrict the view on
an object to a certain protocol, both from Python and from inside
Lua:>>>lua_func=lua.eval('function(obj) return obj["get"] end')>>>d={'get':'value'}>>>value=lua_func(d)>>>value==d['get']=='value'True>>>value=lua_func(lupa.as_itemgetter(d))>>>value==d['get']=='value'True>>>dict_get=lua_func(lupa.as_attrgetter(d))>>>dict_get==d.getTrue>>>dict_get('get')==d.get('get')=='value'True>>>lua_func=lua.eval(...'function(obj) return python.as_attrgetter(obj)["get"] end')>>>dict_get=lua_func(d)>>>dict_get('get')==d.get('get')=='value'TrueNote that unlike Lua function objects, callable Python objects support
indexing in Lua:>>>defpy_func():pass>>>py_func.ATTR=2>>>lua_func=lua.eval('function(obj) return obj.ATTR end')>>>lua_func(py_func)2>>>lua_func=lua.eval(...'function(obj) return python.as_attrgetter(obj).ATTR end')>>>lua_func(py_func)2>>>lua_func=lua.eval(...'function(obj) return python.as_attrgetter(obj)["ATTR"] end')>>>lua_func(py_func)2Iteration in LuaIteration over Python objects from Lua’s for-loop is fully supported.
However, Python iterables need to be converted using one of the
utility functions which are described here.  This is similar to the
functions likepairs()in Lua.To iterate over a plain Python iterable, use thepython.iter()function.  For example, you can manually copy a Python list into a Lua
table like this:>>>lua_copy=lua.eval('''
...     function(L)
...         local t, i ={}, 1
...         for item in python.iter(L) do
...             t[i] = item
...             i = i + 1
...         end
...         return t
...     end
... ''')>>>table=lua_copy([1,2,3,4])>>>len(table)4>>>table[1]# Lua indexing1Python’senumerate()function is also supported, so the above
could be simplified to:>>>lua_copy=lua.eval('''
...     function(L)
...         local t ={}...         for index, item in python.enumerate(L) do
...             t[ index+1 ] = item
...         end
...         return t
...     end
... ''')>>>table=lua_copy([1,2,3,4])>>>len(table)4>>>table[1]# Lua indexing1For iterators that return tuples, such asdict.iteritems(), it is
convenient to use the specialpython.iterex()function that
automatically explodes the tuple items into separate Lua arguments:>>>lua_copy=lua.eval('''
...     function(d)
...         local t ={}...         for key, value in python.iterex(d.items()) do
...             t[key] = value
...         end
...         return t
...     end
... ''')>>>d=dict(a=1,b=2,c=3)>>>table=lua_copy(lupa.as_attrgetter(d))>>>table['b']2Note that accessing thed.itemsmethod from Lua requires passing
the dict asattrgetter.  Otherwise, attribute access in Lua would
use thegetitemprotocol of Python dicts and look upd['items']instead.None vs. nilWhileNonein Python andnilin Lua differ in their semantics, they
usually just mean the same thing: no value.  Lupa therefore tries to map one
directly to the other whenever possible:>>>lua.eval('nil')isNoneTrue>>>is_nil=lua.eval('function(x) return x == nil end')>>>is_nil(None)TrueThe only place where this cannot work is during iteration, because Lua
considers anilvalue the termination marker of iterators.  Therefore,
Lupa special casesNonevalues here and replaces them by a constantpython.noneinstead of returningnil:>>>_=lua.require("table")>>>func=lua.eval('''
...     function(items)
...         local t ={}...         for value in python.iter(items) do
...             table.insert(t, value == python.none)
...         end
...         return t
...     end
... ''')>>>items=[1,None,2]>>>list(func(items).values())[False,True,False]Lupa avoids this value escaping whenever it’s obviously not necessary.
Thus, when unpacking tuples during iteration, only the first value will
be subject topython.nonereplacement, as Lua does not look at the
other items for loop termination anymore.  And onenumerate()iteration, the first value is known to be always a number and never None,
so no replacement is needed.>>>func=lua.eval('''
...     function(items)
...         for a, b, c, d in python.iterex(items) do
...             return {a == python.none, a == nil,   -->  a == python.none
...                     b == python.none, b == nil,   -->  b == nil
...                     c == python.none, c == nil,   -->  c == nil
...                     d == python.none, d == nil}   -->  d == nil ...
...         end
...     end
... ''')>>>items=[(None,None,None,None)]>>>list(func(items).values())[True,False,False,True,False,True,False,True]>>>items=[(None,None)]# note: no values for c/d => nil in Lua>>>list(func(items).values())[True,False,False,True,False,True,False,True]Note that this behaviour changed in Lupa 1.0.  Previously, thepython.nonereplacement was done in more places, which made it not always very predictable.Lua TablesLua tables mimic Python’s mapping protocol.  For the special case of
array tables, Lua automatically inserts integer indices as keys into
the table.  Therefore, indexing starts from 1 as in Lua instead of 0
as in Python.  For the same reason, negative indexing does not work.
It is best to think of Lua tables as mappings rather than arrays, even
for plain array tables.>>>table=lua.eval('{10,20,30,40}')>>>table[1]10>>>table[4]40>>>list(table)[1,2,3,4]>>>list(table.values())[10,20,30,40]>>>len(table)4>>>mapping=lua.eval('{ [1] = -1 }')>>>list(mapping)[1]>>>mapping=lua.eval('{ [20] = -20; [3] = -3 }')>>>mapping[20]-20>>>mapping[3]-3>>>sorted(mapping.values())[-20,-3]>>>sorted(mapping.items())[(3,-3),(20,-20)]>>>mapping[-3]=3# -3 used as key, not index!>>>mapping[-3]3>>>sorted(mapping)[-3,3,20]>>>sorted(mapping.items())[(-3,3),(3,-3),(20,-20)]To simplify the table creation from Python, theLuaRuntimecomes with
a helper method that creates a Lua table from Python arguments:>>>t=lua.table(1,2,3,4)>>>lupa.lua_type(t)'table'>>>list(t)[1,2,3,4]>>>t=lua.table(1,2,3,4,a=1,b=2)>>>t[3]3>>>t['b']2A second helper method,.table_from(), is new in Lupa 1.1 and accepts
any number of mappings and sequences/iterables as arguments.  It collects
all values and key-value pairs and builds a single Lua table from them.
Any keys that appear in multiple mappings get overwritten with their last
value (going from left to right).>>>t=lua.table_from([1,2,3],{'a':1,'b':2},(4,5),{'b':42})>>>t['b']42>>>t[5]5A lookup of non-existing keys or indices returns None (actuallynilinside of Lua).  A lookup is therefore more similar to the.get()method of Python dicts than to a mapping lookup in Python.>>>table[1000000]isNoneTrue>>>table['no such key']isNoneTrue>>>mapping['no such key']isNoneTrueNote thatlen()does the right thing for array tables but does not
work on mappings:>>>len(table)4>>>len(mapping)0This is becauselen()is based on the#(length) operator in
Lua and because of the way Lua defines the length of a table.
Remember that unset table indices always returnnil, including
indices outside of the table size.  Thus, Lua basically looks for an
index that returnsniland returns the index before that.  This
works well for array tables that do not containnilvalues, gives
barely predictable results for tables with ‘holes’ and does not work
at all for mapping tables.  For tables with both sequential and
mapping content, this ignores the mapping part completely.Note that it is best not to rely on the behaviour of len() for
mappings.  It might change in a later version of Lupa.Similar to the table interface provided by Lua, Lupa also supports
attribute access to table members:>>>table=lua.eval('{ a=1, b=2 }')>>>table.a,table.b(1,2)>>>table.a==table['a']TrueThis enables access to Lua ‘methods’ that are associated with a table,
as used by the standard library modules:>>>string=lua.eval('string')# get the 'string' library table>>>print(string.lower('A'))aPython CallablesAs discussed earlier, Lupa allows Lua scripts to call Python functions
and methods:>>>defadd_one(num):...returnnum+1>>>lua_func=lua.eval('function(num, py_func) return py_func(num) end')>>>lua_func(48,add_one)49>>>classMyClass():...defmy_method(self):...return345>>>obj=MyClass()>>>lua_func=lua.eval('function(py_obj) return py_obj:my_method() end')>>>lua_func(obj)345Lua doesn’t have a dedicated syntax for named arguments, so by default
Python callables can only be called using positional arguments.A common pattern for implementing named arguments in Lua is passing them
in a table as the first and only function argument.  Seehttp://lua-users.org/wiki/NamedParametersfor more details.  Lupa supports
this pattern by providing two decorators:lupa.unpacks_lua_tablefor Python functions andlupa.unpacks_lua_table_methodfor methods
of Python objects.Python functions/methods wrapped in these decorators can be called from
Lua code asfunc(foo, bar),func{foo=foo, bar=bar}orfunc{foo, bar=bar}.  Example:>>>@lupa.unpacks_lua_table...defadd(a,b):...returna+b>>>lua_func=lua.eval('function(a, b, py_func) return py_func{a=a, b=b} end')>>>lua_func(5,6,add)11>>>lua_func=lua.eval('function(a, b, py_func) return py_func{a, b=b} end')>>>lua_func(5,6,add)11If you do not control the function implementation, you can also just
manually wrap a callable object when passing it into Lupa:>>>importoperator>>>wrapped_py_add=lupa.unpacks_lua_table(operator.add)>>>lua_func=lua.eval('function(a, b, py_func) return py_func{a, b} end')>>>lua_func(5,6,wrapped_py_add)11There are some limitations:Avoid usinglupa.unpacks_lua_tableandlupa.unpacks_lua_table_methodfor functions where the first argument can be a Lua table.  In this casepy_func{foo=bar}(which is the same aspy_func({foo=bar})in Lua)
becomes ambiguous: it could mean either “callpy_funcwith a namedfooargument” or “callpy_funcwith a positional{foo=bar}argument”.One should be careful with passingnilvalues to callables wrapped inlupa.unpacks_lua_tableorlupa.unpacks_lua_table_methoddecorators.
Depending on the context, passingnilas a parameter can mean either
“omit a parameter” or “pass None”.  This even depends on the Lua version.It is possible to usepython.noneinstead ofnilto pass None values
robustly.  Arguments withnilvalues are also fine when standard bracesfunc(a, b, c)syntax is used.Because of these limitations lupa doesn’t enable named arguments for all
Python callables automatically.  Decorators allow to enable named arguments
on a per-callable basis.Lua CoroutinesThe next is an example of Lua coroutines.  A wrapped Lua coroutine
behaves exactly like a Python coroutine.  It needs to get created at
the beginning, either by using the.coroutine()method of a
function or by creating it in Lua code.  Then, values can be sent into
it using the.send()method or it can be iterated over.  Note that
the.throw()method is not supported, though.>>>lua_code='''\...     function(N)
...         for i=0,N do
...             coroutine.yield( i%2 )
...         end
...     end
... '''>>>lua=LuaRuntime()>>>f=lua.eval(lua_code)>>>gen=f.coroutine(4)>>>list(enumerate(gen))[(0,0),(1,1),(2,0),(3,1),(4,0)]An example where values are passed into the coroutine using its.send()method:>>>lua_code='''\...     function()
...         local t,i ={},0
...         local value = coroutine.yield()
...         while value do
...             t[i] = value
...             i = i + 1
...             value = coroutine.yield()
...         end
...         return t
...     end
... '''>>>f=lua.eval(lua_code)>>>co=f.coroutine()# create coroutine>>>co.send(None)# start coroutine (stops at first yield)>>>foriinrange(3):...co.send(i*2)>>>mapping=co.send(None)# loop termination signal>>>sorted(mapping.items())[(0,0),(1,2),(2,4)]It also works to create coroutines in Lua and to pass them back into
Python space:>>>lua_code='''\...   function f(N)
...         for i=0,N do
...             coroutine.yield( i%2 )
...         end
...   end ;
...   co1 = coroutine.create(f) ;
...   co2 = coroutine.create(f) ;
...
...   status, first_result = coroutine.resume(co2, 2) ;   -- starting!
...
...   return f, co1, co2, status, first_result
... '''>>>lua=LuaRuntime()>>>f,co,lua_gen,status,first_result=lua.execute(lua_code)>>># a running coroutine:>>>statusTrue>>>first_result0>>>list(lua_gen)[1,0]>>>list(lua_gen)[]>>># an uninitialised coroutine:>>>gen=co(4)>>>list(enumerate(gen))[(0,0),(1,1),(2,0),(3,1),(4,0)]>>>gen=co(2)>>>list(enumerate(gen))[(0,0),(1,1),(2,0)]>>># a plain function:>>>gen=f.coroutine(4)>>>list(enumerate(gen))[(0,0),(1,1),(2,0),(3,1),(4,0)]ThreadingThe following example calculates a mandelbrot image in parallel
threads and displays the result in PIL. It is based on abenchmark
implementationfor theComputer Language Benchmarks Game.lua_code='''\function(N, i, total)
        local char, unpack = string.char, table.unpack
        local result = ""
        local M, ba, bb, buf = 2/N, 2^(N%8+1)-1, 2^(8-N%8),{}local start_line, end_line = N/total * (i-1), N/total * i - 1
        for y=start_line,end_line do
            local Ci, b, p = y*M-1, 1, 0
            for x=0,N-1 do
                local Cr = x*M-1.5
                local Zr, Zi, Zrq, Ziq = Cr, Ci, Cr*Cr, Ci*Ci
                b = b + b
                for i=1,49 do
                    Zi = Zr*Zi*2 + Ci
                    Zr = Zrq-Ziq + Cr
                    Ziq = Zi*Zi
                    Zrq = Zr*Zr
                    if Zrq+Ziq > 4.0 then b = b + 1; break; end
                end
                if b >= 256 then p = p + 1; buf[p] = 511 - b; b = 1; end
            end
            if b ~= 1 then p = p + 1; buf[p] = (ba-b)*bb; end
            result = result .. char(unpack(buf, 1, p))
        end
        return result
    end
'''image_size=1280# == 1280 x 1280thread_count=8fromrandovania_lupaimportLuaRuntimelua_funcs=[LuaRuntime(encoding=None).eval(lua_code)for_inrange(thread_count)]results=[None]*thread_countdefmandelbrot(i,lua_func):results[i]=lua_func(image_size,i+1,thread_count)importthreadingthreads=[threading.Thread(target=mandelbrot,args=(i,lua_func))fori,lua_funcinenumerate(lua_funcs)]forthreadinthreads:thread.start()forthreadinthreads:thread.join()result_buffer=b''.join(results)# use Pillow to display the imagefromPILimportImageimage=Image.frombytes('1',(image_size,image_size),result_buffer)image.show()Note how the example creates a separateLuaRuntimefor each thread
to enable parallel execution.  EachLuaRuntimeis protected by a
global lock that prevents concurrent access to it.  The low memory
footprint of Lua makes it reasonable to use multiple runtimes, but
this setup also means that values cannot easily be exchanged between
threads inside of Lua.  They must either get copied through Python
space (passing table references will not work, either) or use some Lua
mechanism for explicit communication, such as a pipe or some kind of
shared memory setup.Restricting Lua access to Python objectsLupa provides a simple mechanism to control access to Python objects.
Each attribute access can be passed through a filter function as
follows:>>>deffilter_attribute_access(obj,attr_name,is_setting):...ifisinstance(attr_name,unicode):...ifnotattr_name.startswith('_'):...returnattr_name...raiseAttributeError('access denied')>>>lua=lupa.LuaRuntime(...register_eval=False,...attribute_filter=filter_attribute_access)>>>func=lua.eval('function(x) return x.__class__ end')>>>func(lua)Traceback(mostrecentcalllast):...AttributeError:accessdeniedTheis_settingflag indicates whether the attribute is being read
or set.Note that the attributes of Python functions provide access to the
currentglobals()and therefore to the builtins etc.  If you want
to safely restrict access to a known set of Python objects, it is best
to work with a whitelist of safe attribute names.  One way to do that
could be to use a well selected list of dedicated API objects that you
provide to Lua code, and to only allow Python attribute access to the
set of public attribute/method names of these objects.Since Lupa 1.0, you can alternatively provide dedicated getter and
setter function implementations for aLuaRuntime:>>>defgetter(obj,attr_name):...ifattr_name=='yes':...returngetattr(obj,attr_name)...raiseAttributeError(...'not allowed to read attribute "%s"'%attr_name)>>>defsetter(obj,attr_name,value):...ifattr_name=='put':...setattr(obj,attr_name,value)...return...raiseAttributeError(...'not allowed to write attribute "%s"'%attr_name)>>>classX(object):...yes=123...put='abc'...noway=2.1>>>x=X()>>>lua=lupa.LuaRuntime(attribute_handlers=(getter,setter))>>>func=lua.eval('function(x) return x.yes end')>>>func(x)# getting 'yes'123>>>func=lua.eval('function(x) x.put = "ABC"; end')>>>func(x)# setting 'put'>>>print(x.put)ABC>>>func=lua.eval('function(x) x.noway = 42; end')>>>func(x)# setting 'noway'Traceback(mostrecentcalllast):...AttributeError:notallowedtowriteattribute"noway"Restricting Lua Memory UsageLupa provides a simple mechanism to control the maximum memory
usage of the Lua Runtime since version 2.0.
By default Lupa does not interfere with Lua’s memory allocation, to opt-in
you must set themax_memorywhen creating the LuaRuntime.TheLuaRuntimeprovides three methods for controlling and reading the
memory usage:get_memory_used(total=False)to get the current memory
usage of the LuaRuntime.get_max_memory(total=False)to get the current memory limit.0means there is no memory limitation.set_max_memory(max_memory, total=False)to change the memory limit.
Values below or equal to 0 mean no limit.There is always some memory used by the LuaRuntime itself (around ~20KiB,
depending on your lua version and other factors) which is excluded from all
calculations unless you specifytotal=True.>>>lua=LuaRuntime(max_memory=0)# 0 for unlimited, default is None>>>lua.get_memory_used()# memory used by your code0>>>total_lua_memory=lua.get_memory_used(total=True)# includes memory used by the runtime itself>>>asserttotal_lua_memory>0# exact amount depends on your lua version and other factorsLua code hitting the memory limit will receive memory errors:>>>lua.set_max_memory(100)>>>lua.eval("string.rep('a', 1000)")# doctest: +IGNORE_EXCEPTION_DETAILTraceback(mostrecentcalllast):...lupa.LuaMemoryError:notenoughmemoryLuaMemoryErrorinherits fromLuaErrorandMemoryError.Importing Lua binary modulesThis will usually work as is, but here are the details, in case
anything goes wrong for you.To use binary modules in Lua, you need to compile them against the
header files of the LuaJIT sources that you used to build Lupa, but do
not link them against the LuaJIT library.Furthermore, CPython needs to enable global symbol visibility for
shared libraries before loading the Lupa module.  This can be done by
callingsys.setdlopenflags(flag_values).  Importing thelupamodule will automatically try to set up the correctdlopenflags
if it can find the platform specificDLFCNPython module that
defines the necessary flag constants.  In that case, using binary
modules in Lua should work out of the box.If this setup fails, however, you have to set the flags manually.
When using the above configuration call, the argumentflag_valuesmust represent the sum of your system’s values forRTLD_NEWandRTLD_GLOBAL.  IfRTLD_NEWis 2 andRTLD_GLOBALis 256, you
need to callsys.setdlopenflags(258).Assuming that the Lualuaposix(posix) module is available, the
following should work on a Linux system:>>>importsys>>>orig_dlflags=sys.getdlopenflags()>>>sys.setdlopenflags(258)>>>importlupa>>>sys.setdlopenflags(orig_dlflags)>>>lua=lupa.LuaRuntime()>>>posix_module=lua.require('posix')# doctest: +SKIPBuilding with different Lua versionsThe build is configured to automatically search for an installed version
of first LuaJIT and then Lua, and failing to find either, to use the bundled
LuaJIT or Lua version.If you wish to build Lupa with a specific version of Lua, you can
configure the following options on setup:OptionDescription--lua-lib<libfile>Lua library file path, e.g.--lua-lib/usr/local/lib/lualib.a--lua-includes<incdir>Lua include directory, e.g.--lua-includes/usr/local/include--use-bundleUse bundled LuaJIT or Lua instead of searching for an installed version.--no-bundleDon’t use the bundled LuaJIT/Lua, search for an installed version of LuaJIT or Lua,
e.g. usingpkg-config.--no-lua-jitDon’t use or search for LuaJIT, only use or search Lua instead.Installing lupaBuilding with LuaJIT2Download and unpack lupahttp://pypi.python.org/pypi/lupaDownload LuaJIT2http://luajit.org/download.htmlUnpack the archive into the lupa base directory, e.g.:.../lupa-0.1/LuaJIT-2.0.2Build LuaJIT:cd LuaJIT-2.0.2
make
cd ..If you need specific C compiler flags, pass them tomakeas follows:make CFLAGS="..."For trickier target platforms like Windows and MacOS-X, please see
the officialinstallation instructions for LuaJIT.NOTE: When building on Windows, make sure that lua51.lib is made in addition
to lua51.dll. The MSVC build produces this file, MinGW does NOT.Build lupa:python setup.py build_ext -iOr any other distutils target of your choice, such asbuildor one of thebdisttargets.  See thedistutils
documentationfor help, also thehints on building extension
modules.Note that on 64bit MacOS-X installations, the following additional
compiler flags are reportedly required due to the embedded LuaJIT:-pagezero_size 10000 -image_base 100000000You can find additional installation hints for MacOS-X in thissomewhat unclear blog post, which may or may not tell you at
which point in the installation process to provide these flags.Also, on 64bit MacOS-X, you will typically have to set the
environment variableARCHFLAGSto make sure it only builds
for your system instead of trying to generate a fat binary with
both 32bit and 64bit support:export ARCHFLAGS="-arch x86_64"Note that this applies to both LuaJIT and Lupa, so make sure
you try a clean build of everything if you forgot to set it
initially.Building with Lua 5.xIt also works to use Lupa with the standard (non-JIT) Lua
runtime. The easiest way is to use the bundled lua submodule:Clone the submodule:$ git submodule update --init third-party/luaBuild Lupa:$ python3 setup.py bdist_wheel --use-bundle --with-cythonYou can also build it by installing a Lua 5.x package, including
any development packages (header files etc.). On systems that
use the “pkg-config” configuration mechanism, Lupa’s
setup.py will pick up either LuaJIT2 or Lua automatically, with a
preference for LuaJIT2 if it is found.  Pass the--no-luajitoption
to the setup.py script if you have both installed but do not want to
use LuaJIT2.On other systems, you may have to supply the build parameters
externally, e.g. using environment variables or by changing the
setup.py script manually.  Pass the--no-luajitoption to the
setup.py script in order to ignore the failure you get when neither
LuaJIT2 nor Lua are found automatically.For further information, read this mailing list post:https://www.freelists.org/post/lupa-dev/Lupa-with-normal-Lua-interpreter-Lua-51,2Installing lupa from packagesDebian/Ubuntu + Lua 5.2Install Lua 5.2 development package:$ apt-get install liblua5.2-devInstall lupa:$ pip install lupaDebian/Ubuntu + LuaJIT2Install LuaJIT2 development package:$ apt-get install libluajit-5.1-devInstall lupa:$ pip install lupaDepending on OS version, you might get an older LuaJIT2 version.OS X + Lua 5.2 + HomebrewInstall Lua:$ brew install luaInstall pkg-config:$ brew install pkg-configInstall lupa:$ pip install lupaLupa change log2.1 (2023-??-??)GH#248: The LuaRuntime methods “eval”, “execute” and “compile” gained new
keyword optionsmodeandnamethat allow constraining the input type
and modifying the (chunk) name shown in error messages, following similar
arguments in the Luaload()function.
Seehttps://www.lua.org/manual/5.4/manual.html#pdf-loadGH#246: Loading Lua modules did not work for the version specific Lua modules
introduced in Lupa 2.0.  It turned out that it can only be enabled for
one of them in a given Python run, so it is now left to users to enable it
explicitly at need.
(original patch by Richard Connon)The bundled Lua 5.1 was updated to 5.1.5 and Lua 5.2 to 5.2.4.
(patch by xxyzz)Built with Cython 3.0.6 for improved support of Python 3.12.2.0 (2023-04-03)GH#217: Lua stack traces in Python exception messages are now reversed to
match the order of Python stack traces.GH#196: Lupa now ships separate extension modules built with Lua 5.3,
Lua 5.4, LuaJIT 2.0 and LuaJIT 2.1 beta.  Note that this is build specific
and may depend on the platform.  A normal Python import cascade can be used.GH#211: A new optionmax_memoryallows to limit the memory usage of Lua code.
(patch by Leo Developer)GH#171: Python references in Lua are now more safely reference counted
to prevent garbage collection glitches.
(patch by Guilherme Dantas)GH#146: Lua integers in Lua 5.3+ are converted from and to Python integers.
(patch by Guilherme Dantas)GH#180: Thepython.enumerate()function now returns indices as integers
if supported by Lua.
(patch by Guilherme Dantas)GH#178: The Lua integer limits can be read from the module asLUA_MAXINTEGERandLUA_MININTEGER.
(patch by Guilherme Dantas)GH#174: Failures while calling the__indexmethod in Lua during a
table index lookup from Python could crash Python.
(patch by Guilherme Dantas)GH#137: PassingNoneas a dict key intotable_from()crashed.
(patch by Leo Developer)GH#176: A new functionpython.args(*args,**kwargs)was added
to help with building Python argument tuples and keyword argument dicts
for Python function calls from Lua code.GH#177: Tables that are not sequences raiseIndexErrorwhen unpacking
them.  Previously, non-sequential items were simply ignored.GH#179: Resolve some C compiler warnings about signed/unsigned comparisons.
(patch by Guilherme Dantas)Built with Cython 0.29.34.1.14.1 (2022-11-16)Rebuild with Cython 0.29.32 to support Python 3.11.1.13 (2022-03-01)Bundled Lua source files were missing in the source distribution.1.12 (2022-02-24)GH#197: Some binary wheels in the last releases were not correctly linked with Lua.GH#194: An absolute file path appeared in theSOURCES.txtmetadata
of the source distribution.1.11 (2022-02-23)Use Lua 5.4.4 in binary wheels and as bundled Lua.Built with Cython 0.29.28 to support Python 3.10/11.1.10 (2021-09-02)GH#147: Lua 5.4 is supported.
(patch by Russel Davis)The runtime version of the Lua library as a tuple (e.g.(5,3))
is provided vialupa.LUA_VERSIONandLuaRuntime.lua_version.The Lua implementation name and version string is provided asLuaRuntime.lua_implementation.setup.pyaccepts new command line arguments--lua-liband--lua-includesto specify theUse Lua 5.4.3 in binary wheels and as bundled Lua.Built with Cython 0.29.24 to support Python 3.9.1.9 (2019-12-21)Build against Lua 5.3 if available.Use Lua 5.3.5 in binary wheels and as bundled Lua.GH#129: Fix Lua module loading in Python 3.x.GH#126: Fix build on Linux systems that install Lua as “lua52” package.Built with Cython 0.29.14 for better Py3.8 compatibility.1.8 (2019-02-01)GH#107: Fix a deprecated import in Py3.Built with Cython 0.29.3 for better Py3.7 compatibility.1.7 (2018-08-06)GH#103: Provide wheels for MS Windows and fix MSVC build on Py2.7.1.6 (2017-12-15)GH#95: Improved compatibility with Lua 5.3.
(patch by TitanSnow)1.5 (2017-09-16)GH#93: New methodLuaRuntime.compile()to compile Lua code
without executing it.
(patch by TitanSnow)GH#91: Lua 5.3 is bundled in the source distribution to simplify
one-shot installs.
(patch by TitanSnow)GH#87: Lua stack trace is included in output in debug mode.
(patch by aaiyer)GH#78: Allow Lua code to intercept Python exceptions.
(patch by Sergey Dobrov)Built with Cython 0.26.1.1.4 (2016-12-10)GH#82: Lua coroutines were using the wrong runtime state
(patch by Sergey Dobrov)GH#81: copy locally provided Lua DLL into installed package on Windows
(patch by Gareth Coles)built with Cython 0.25.21.3 (2016-04-12)GH#70:eval()andexecute()accept optional positional arguments
(patch by John Vandenberg)GH#65: callingstr()on a Python object from Lua could fail if theLuaRuntimeis set up without auto-encoding (patch by Mikhail Korobov)GH#63: attribute/keyword names were not properly encoded if theLuaRuntimeis set up without auto-encoding (patch by Mikhail Korobov)built with Cython 0.241.2 (2015-10-10)callbacks returned from Lua coroutines were incorrectly mixing
coroutine state with global Lua state (patch by Mikhail Korobov)availability ofpython.builtinsin Lua can be disabled viaLuaRuntimeoption.built with Cython 0.23.41.1 (2014-11-21)new module functionlupa.lua_type()that returns the Lua type of
a wrapped object as string, orNonefor normal Python objectsnew helper methodLuaRuntime.table_from(...)that creates a Lua
table from one or more Python mappings and/or sequencesnewlupa.unpacks_lua_tableandlupa.unpacks_lua_table_methoddecorators to allow calling Python functions from Lua using named
argumentsfix a hang on shutdown where the LuaRuntime failed to deallocate due
to reference cyclesLupa now plays more nicely with other Lua extensions that create
userdata objects1.0.1 (2014-10-11)fix a crash when requesting attributes of wrapped Lua coroutine objectslooking up attributes on Lua objects that do not support it now always
raises an AttributeError instead of sometimes raising a TypeError depending
on the attribute name1.0 (2014-09-28)NOTE: this release includes the major backwards incompatible changes listed
below.  It is believed that they simplify the interaction between Python code
and Lua code by more strongly following idiomatic Lua on the Lua side.Instead of passing a wrappedpython.noneobject into Lua,Nonereturn values are now mapped tonil, making them more straight forward
to handle in Lua code.  This makes the behaviour more consistent, as it
was previously somewhat arbitrary wherenonecould appear and where anilvalue was used.  The only remaining exception is during iteration,
where the first returned value must not benilin Lua, or otherwise
the loop terminates prematurely.  To prevent this, anyNonevalue
that the iterator returns, or any first item in exploded tuples that isNone, is still mapped topython.none. Any further values
returned in the same iteration will be mapped tonilif they areNone, not tonone.  This means that only the first argument
needs to be manually checked for this special case.  For theenumerate()iterator, the counter is neverNoneand thus the
following unpacked items will never be mapped topython.none.Whenunpack_returned_tuples=True, iteration now also unpacks tuple
values, includingenumerate()iteration, which yields a flat sequence
of counter and unpacked values.When calling bound Python methods from Lua as “obj:meth()”, Lupa now
prevents Python from prepending the self argument a second time, so that
the Python method is now called as “obj.meth()”.  Previously, it was called
as “obj.meth(obj)”.  Note that this can be undesired when the object itself
is explicitly passed as first argument from Lua, e.g. when calling
“func(obj)” where “func” is “obj.meth”, but these constellations should be
rare.  As a work-around for this case, user code can wrap the bound method
in another function so that the final call comes from Python.garbage collection works for reference cycles that span both runtimes,
Python and Luacalling from Python into Lua and back into Python did not clean up the
Lua call arguments before the innermost call, so that they could leak
into the nested Python call or its return argumentssupport for Lua 5.2 (in addition to Lua 5.1 and LuaJIT 2.0)Lua tables support Python’s “del” statement for item deletion
(patch by Jason Fried)Attribute lookup can use a more fine-grained control mechanism by
implementing explicit getter and setter functions for a LuaRuntime
(attribute_handlersargument).  Patch by Brian Moe.item assignments/lookups on Lua objects from Python no longer
special case double underscore names (as opposed to attribute lookups)0.21 (2014-02-12)some garbage collection issues were cleaned up using new Cython featuresnewLuaRuntimeoptionunpack_returned_tupleswhich automatically
unpacks tuples returned from Python functions into separate Lua objects
(instead of returning a single Python tuple object)some internal wrapper classes were removed from the module APIWindows build fixesPy3.x build fixessupport for building with Lua 5.1 instead of LuaJIT (setup.py –no-luajit)no longer uses Cython by default when building from released sources (pass--with-cythonto explicitly request a rebuild)requires Cython 0.20+ when building from unreleased sourcesbuilt with Cython 0.20.10.20 (2011-05-22)fix “deallocating None” crash while iterating over Lua tables in
Python codesupport for filtering attribute access to Python objects for Lua
codefix: setting source encoding for Lua code was broken0.19 (2011-03-06)fix serious resource leak when creating multiple LuaRuntime instancesportability fix for binary module importing0.18 (2010-11-06)fix iteration by returningPy_Noneobject forNoneinstead
ofnil, which would terminate the iterationwhen converting Python values to Lua, representNoneas aPy_Noneobject in places wherenilhas a special meaning,
but leave it asnilwhere it doesn’t hurtsupport for counter start value inpython.enumerate()native implementation forpython.enumerate()that is several
times fastermuch faster Lua iteration over Python objects0.17 (2010-11-05)new helper functionpython.enumerate()in Lua that returns a Lua
iterator for a Python object and adds the 0-based index to each
item.new helper functionpython.iterex()in Lua that returns a Lua
iterator for a Python object and unpacks any tuples that the
iterator yields.new helper functionpython.iter()in Lua that returns a Lua
iterator for a Python object.reestablished thepython.as_function()helper function for Lua
code as it can be needed in cases where Lua cannot determine how to
run a Python function.0.16 (2010-09-03)droppedpython.as_function()helper function for Lua as all
Python objects are callable from Lua now (potentially raising aTypeErrorat call time if they are not callable)fix regression in 0.13 and later where ordinary Lua functions failed
to print due to an accidentally used meta tablefix crash when callingstr()on wrapped Lua objects without
metatable0.15 (2010-09-02)support for loading binary Lua modules on systems that support it0.14 (2010-08-31)relicensed to the MIT license used by LuaJIT2 to simplify licensing
considerations0.13.1 (2010-08-30)fix Cython generated C file using Cython 0.130.13 (2010-08-29)fixed undefined behaviour onstr(lua_object)when the object’s__tostring()meta method failsremoved redundant “error:” prefix fromLuaErrormessagesaccess to Python’spython.builtinsfrom Lua codemore generic wrapping rules for Python objects based on supported
protocols (callable, getitem, getattr)new helper functionsas_attrgetter()andas_itemgetter()to
specify the Python object protocol used by Lua indexing when
wrapping Python objects in Python codenew helper functionspython.as_attrgetter(),python.as_itemgetter()andpython.as_function()to specify
the Python object protocol used by Lua indexing of Python objects in
Lua codeitem and attribute access for Python objects from Lua code0.12 (2010-08-16)fix Lua stack leak during table iterationfix lost Lua object reference after iteration0.11 (2010-08-07)error reporting on Lua syntax errors failed to clean up the stack so
that errors could leak into the next Lua runLua error messages were not properly decoded0.10 (2010-07-27)much faster locking of the LuaRuntime, especially in the single
threaded case (seehttp://code.activestate.com/recipes/577336-fast-re-entrant-optimistic-lock-implemented-in-cyt/)fixed several error handling problems when executing Python code
inside of Lua0.9 (2010-07-23)fixed Python special double-underscore method access on LuaObject
instancesLua coroutine support through dedicated wrapper classes, including
Python iteration support.  In Python space, Lua coroutines behave
exactly like Python generators.0.8 (2010-07-21)support for returning multiple values from Lua evaluationrepr()support for Lua objectsLuaRuntime.table()method for creating Lua tables from Python
spaceencoding fix forstr(LuaObject)0.7 (2010-07-18)LuaRuntime.require()andLuaRuntime.globals()methodsrenamedLuaRuntime.run()toLuaRuntime.execute()support forlen(),setattr()and subscripting of Lua objectsprovide all built-in Lua libraries inLuaRuntime, including
support for library loadingfixed a thread locking issuefix passing Lua objects back into the runtime from Python space0.6 (2010-07-18)Python iteration support for Lua objects (e.g. tables)threading fixesfix compile warnings0.5 (2010-07-14)explicit encoding options per LuaRuntime instance to decode/encode
strings and Lua code0.4 (2010-07-14)attribute read access on Lua objects, e.g. to read Lua table values
from Pythonstr() on Lua objectsinclude .hg repository in source downloadsadded missing files to source distribution0.3 (2010-07-13)fix several threading issuessafely free the GIL when calling into Lua0.2 (2010-07-13)propagate Python exceptions through Lua calls0.1 (2010-07-12)first public releaseLicenseLupaCopyright (c) 2010-2017 Stefan Behnel.  All rights reserved.Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.Lua(Seehttps://www.lua.org/license.html)Copyright © 1994–2017 Lua.org, PUC-Rio.Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.