.\" generated with Ronn/v0.7.3
.\" http://github.com/rtomayko/ronn/tree/0.7.3
.
.TH "PYTHON\-LUA" "7" "August 2012" "" ""
.
.SH "NAME"
\fBpython\-lua\fR \- using lua scripts from python
.
.SH "SYNOPSIS"
\fBimport lua\fR
.
.P
\fBlua_handle = lua\.lua (debug = False)\fR
.
.P
\fBlua_handle\.run (script = None, var = None, value = None, name = \'python string\')\fR
.
.P
\fBlua_handle\.run_file (\fR\fIscript_file\fR\fB)\fR
.
.P
\fBlua_handle\.module (\fR\fIname\fR, \fImy_module\fR\fB)\fR
.
.P
\fBlua_table\._dict ()\fR
.
.P
\fBlua_table\._list ()\fR
.
.SH "DESCRIPTION"
The lua module interfaces Python code to the Lua library, thus allowing Lua scripts to be run from Python\. For most operations, a \fBlua\.lua\fR 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 \fBdebug\fR set to False (the default), it will automatically run \fBself\.run (\'debug = nil\')\fR, which will disable the debugging library\.
.
.P
\fBlua\.run\fR 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\. \fBscript\fR may be omitted, in which case only the assignment is performed\. If \fBvar\fR 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 \fBlua_handle\.run (\'table\.foo = tmp\', \'tmp\', value)\fR\. The name is used for error reporting\.
.
.P
When using Python objects from Lua, their python operations are used when invoked\. For example, the \fBadd\fR 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\.
.
.P
\fBlua\.run_file\fR is similar to \fBlua\.run\fR, but it takes a filename where the code is located\. It does not support variable assignment, so if that is required, a call to \fBlua\.run\fR should be used first\.
.
.P
\fBlua\.module\fR allows importing an object into lua as a module\. This works reasonably well, but there are some limitations, see \fIBUGS\fR\.
.
.P
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\.
.
.P
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 \fBlua_table\._list ()\fR 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 \fBa[3]\fR in Lua is called \fBa\._list ()[2]\fR in Python\. Second, when using \fB_list\fR on a table which contains non\-integer elements, those elements are not present in the returned list\.
.
.P
The table wrapper supports most Python operations, but it can be useful to copy it to a dict\. This is what \fBlua_table\._dict ()\fR does\. Changes made to this dict are not reflected in the lua table that it was copied from\.
.
.SH "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\.
.
.SH "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\.
.
.P
As a workaround, when changing or creating such variables from Python, you can manually add them to lua as well, using \fBlua\.run (var = \'\fR\fIname\fR\fB\', value =\fR<module\.name>\fB)\fR\. When using variables which may have been changed by lua, instead of using their value directly from the python module, use \fBlua\.run (\fR\fIname\fR\fB)\fR\.
.
.SH "AUTHOR"
Python\-lua was written by \fBBas Wijnen <wijnen@debian\.org>\fR