xenial (7) python-lua.7.gz

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)