[HowTo] Import user defined Python modules in Sikuli

Created by Tsung-Hsiang Chang on on 2010-05-20
Keywords:
import module
Last updated by:
RaiMan on on 2011-06-24

You should read this, if
--- you want to use code written in Python language saved in other files (no copy/paste ;-)
--- you want to use available Python modules in your Sikuli script

If your other code is in other .sikuli or .skl, you should decide to use Sikuli X and read
http://sikuli.org/docx/globals.html#importing-other-sikuli-scripts-reuse-code-and-images
and there is no need to read further ;-)

--- General prerequisite: The code we are talking about can be run using the Jython interpreter (which is used inside Sikuli to run your scripts). So every plain Python script, that conforms with the standard (language and built-in's, current level Python 2.6/Jython 2.5.1) will run when used with Sikuli.

--- Python/Jython modules (self written or downloaded from the net) will run, if they are supported by Jython 2.5.1. If it is a module for the standard Python interpreter (C-Python), then it will run, if it is written in Python language only. If external libraries are used, then it depends on the used integration technique. Again in general: modules that use the so called C-type interface (inline C code and/or direct access to C/C++ libraries, e.g. PIL) will not run in Sikuli (because they are not supported by Jython). In some cases there might be a port to Jython or an equivalent solution - have a look around.

--- Java Runtime Environment (JRE): Sikuli needs access to the original JRE provided by Sun/Oracle. So even if your Jython module might run as such, in combination with Sikuli there might be problems, when using a third party JRE.

--- A basic Solution for running external Python code:
If it is just plain python code, that can be run standalone without errors, you may use the Python function execfile(), that runs the code from a given file in the same way, as if it was written in your calling script.

aScript = "path-to-your-file-containing-python-code"
execfile(aScript)

and every time, the execfile() statement is executed again, the contained code is executed again.

--- using Python import
As a general difference to execfile() the imported code is only executed once the first time the import statement is processed. So usually imported code mainly contains other modules, classes and functions, that you want to use in your calling script. Besides the Jython compatibility the only prerequisite is, that it can be found in the Python path (sys.path) (it is not possible to import a module using it's location in the file system like with execfile()). A file containing a Python module must have the ending .py.

recommended approach in a Sikuli script:
# supposing you have path-to-your-modules/someModule.py
if not "path-to-your-modules" in sys.path: sys.path.append("path-to-your-modules")
import someModule

The if construct avoids double entries in sys.path, if the script is run more than once in the Sikuli IDE, since the environment is only reset when starting the IDE and not on rerun of a script.

This is the reason, why you have to restart the IDE, if you have done some changes in the imported modules.

In general we recommend to use Sikuli X, because the options to use things from outside are evolving ;-)