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.

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.

Note the flag unpack_returned_tuples=True that 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 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 operations obj[x] and obj.x both 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 functions
as_attrgetter() and as_itemgetter() that restrict the view on
an object to a certain protocol, both from Python and from inside
Lua:

Iteration 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 like pairs() in Lua.

To iterate over a plain Python iterable, use the python.iter()
function. For example, you can manually copy a Python list into a Lua
table like this:

Note that accessing the d.items method from Lua requires passing
the dict as attrgetter. Otherwise, attribute access in Lua would
use the getitem protocol of Python dicts and look up d['items']
instead.

The only place where this cannot work is during iteration, because Lua
considers a nil value the termination marker of iterators. Therefore,
Lupa special cases None values here and replaces them by a constant
python.none instead of returning nil:

Lupa avoids this value escaping whenever it’s obviously not necessary.
Thus, when unpacking tuples during iteration, only the first value will
be subject to python.none replacement, as Lua does not look at the
other items for loop termination anymore. And on enumerate()
iteration, the first value is known to be always a number and never None,
so no replacement is needed.

Lua 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.

A 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).

A lookup of non-existing keys or indices returns None (actually nil
inside 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']isNoneTrue

Note that len() does the right thing for array tables but does not
work on mappings:

>>>len(table)4>>>len(mapping)0

This is because len() 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 return nil, including
indices outside of the table size. Thus, Lua basically looks for an
index that returns nil and returns the index before that. This
works well for array tables that do not contain nil values, 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:

Lua 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. See
http://lua-users.org/wiki/NamedParameters for more details. Lupa supports
this pattern by providing two decorators: lupa.unpacks_lua_table
for Python functions and lupa.unpacks_lua_table_method for methods
of Python objects.

Python functions/methods wrapped in these decorators can be called from
Lua code as func(foo, bar), func{foo=foo, bar=bar}
or func{foo, bar=bar}. Example:

Avoid using lupa.unpacks_lua_table and lupa.unpacks_lua_table_method
for functions where the first argument can be a Lua table. In this case
py_func{foo=bar} (which is the same as py_func({foo=bar}) in Lua)
becomes ambiguous: it could mean either “call py_func with a named
foo argument” or “call py_func with a positional {foo=bar}
argument”.

One should be careful with passing nil values to callables wrapped in
lupa.unpacks_lua_table or lupa.unpacks_lua_table_method decorators.
Depending on the context, passing nil as a parameter can mean either
“omit a parameter” or “pass None”. This even depends on the Lua version.

It is possible to use python.none instead of nil to pass None values
robustly. Arguments with nil values are also fine when standard braces
func(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.

The 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.

Note how the example creates a separate LuaRuntime for each thread
to enable parallel execution. Each LuaRuntime is 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.

The is_setting flag indicates whether the attribute is being read
or set.

Note that the attributes of Python functions provide access to the
current globals() 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 a LuaRuntime:

This 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
calling sys.setdlopenflags(flag_values). Importing the lupa
module will automatically try to set up the correct dlopen flags
if it can find the platform specific DLFCN Python 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 argument flag_values
must represent the sum of your system’s values for RTLD_NEW and
RTLD_GLOBAL. If RTLD_NEW is 2 and RTLD_GLOBAL is 256, you
need to call sys.setdlopenflags(258).

Assuming that the Lua luaposix (posix) module is available, the
following should work on a Linux system:

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 100000000

You can find additional installation hints for MacOS-X in this
somewhat 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 variable ARCHFLAGS to 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.1

Reportedly, it also works to use Lupa with the standard (non-JIT) Lua
runtime. To that end, install Lua 5.1 instead of LuaJIT2, 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-luajit option
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-luajit option to the
setup.py script in order to ignore the failure you get when neither
LuaJIT2 nor Lua are found automatically.

1.0.1 (2014-10-11)

looking 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 name

1.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 wrapped python.none object into Lua, None
return values are now mapped to nil, making them more straight forward
to handle in Lua code. This makes the behaviour more consistent, as it
was previously somewhat arbitrary where none could appear and where a
nil value was used. The only remaining exception is during iteration,
where the first returned value must not be nil in Lua, or otherwise
the loop terminates prematurely. To prevent this, any None value
that the iterator returns, or any first item in exploded tuples that is
None, is still mapped to python.none. Any further values
returned in the same iteration will be mapped to nil if they are
None, not to none. This means that only the first argument
needs to be manually checked for this special case. For the
enumerate() iterator, the counter is never None and thus the
following unpacked items will never be mapped to python.none.

When unpack_returned_tuples=True, iteration now also unpacks tuple
values, including enumerate() 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 Lua

calling 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 arguments

0.3 (2010-07-13)

0.2 (2010-07-13)

propagate Python exceptions through Lua calls

0.1 (2010-07-12)

first public release

License

Lupa

Copyright (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

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.