NAME

       python-lua - using lua scripts from python

SYNOPSIS

       import lua

       lua_handle = lua.lua (debug = False)

       lua_handle.run (script = None, var = None, value = None, name = ´python string´)

       lua_handle.run_file (script_file)

       lua_handle.module (name, my_module)

       lua_table._dict ()

       lua_table._list ()

DESCRIPTION

       The  lua module interfaces Python code to the Lua library, thus allowing Lua scripts to be
       run from Python. For most operations, a lua.lua object must be created. This  object  does
       all  the  work.  Creating multiple lua objects from one Python program should work, but is
       untested. When creating a lua instance with debug set to  False  (the  default),  it  will
       automatically run self.run (´debug = nil´), which will disable the debugging library.

       lua.run  is  the  main entry point into lua code. It allows running a script (which may be
       uncompiled or compiled lua code). It can also be used to set the value  of  a  global  lua
       variable  to any Python value. script may be omitted, in which case only the assignment is
       performed. If var is omitted, only the script is run. If both are present, the variable is
       assigned  before  the  script  is  run.  To  assign a variable inside a table, you can use
       lua_handle.run (´table.foo = tmp´, ´tmp´, value). The name is used for error reporting.

       When using Python objects from Lua, their python operations are  used  when  invoked.  For
       example,  the  add  function  will be called when something is added to the object in lua.
       This is particularly useful for functions, which can be called from  lua  this  way.  Note
       that  passing  a  method to Lua works fine, but the library will raise an exception if Lua
       tries to call it with a different object instance. Also, the library may raise  exceptions
       when lua scripts don´t expect them, for example when referencing a nonexistent member.

       lua.run_file  is similar to lua.run, but it takes a filename where the code is located. It
       does not support variable assignment, so if that is required, a call to lua.run should  be
       used first.

       lua.module  allows  importing  an object into lua as a module. This works reasonably well,
       but there are some limitations, see BUGS.

       Lua tables are wrapped in a Python object when they are returned. When changes are made to
       this  Python  object,  the change is passed through to the lua object. In other words, Lua
       remains the owner of the table.

       Lua doesn´t use integers, but only floats. Because it is quite normal to use a  Lua  table
       as  a  list,  there  is  a  function  to  convert  a table wrapper to a list. This is what
       lua_table._list () does. The underscore is to avoid name collisions  with  table  members.
       There  are  two  things  to  remember  when using it. First, Lua starts counting at 1, but
       Python starts at 0. A value called a[3] in Lua is called a._list ()[2] in Python.  Second,
       when  using  _list  on a table which contains non-integer elements, those elements are not
       present in the returned list.

       The table wrapper supports most Python operations, but it can be useful to copy  it  to  a
       dict. This is what lua_table._dict () does. Changes made to this dict are not reflected in
       the lua table that it was copied from.

SECURITY CONSIDERATIONS

       Lua has the ability to load any libraries from the system. This means that Lua should  not
       be used for scripts from untrusted sources.

BUGS

       Lua  only  supports plain tables, not user objects, as module definitions. This means that
       no callbacks can be added for events which happen in the  top  level  of  the  module.  In
       particular, when a Python module is used as a lua module (which is the usual case), a list
       is built at registration time and passed to lua. When  new  variables  are  added  to  the
       Python  module,  or  existing  variables  are  changed  so they link to new objects, those
       changes will not be reflected in lua. Similarly,  such  changes  made  from  lua  are  not
       visible in Python. Changing the contents of variables is not affected by this problem.

       As  a  workaround,  when changing or creating such variables from Python, you can manually
       add them to lua as well, using lua.run (var = ´name´, value  =<module.name>).  When  using
       variables  which  may have been changed by lua, instead of using their value directly from
       the python module, use lua.run (name).

AUTHOR

       Python-lua was written by Bas Wijnen <wijnen@debian.org>

                                           August 2012                              PYTHON-LUA(7)