PyScript is for scripting Litestep themes. PyScript allows you to do everything mzscript can, including defining bangs, rewriting step.rc and more.
PyScript needs a recent version of Python 2.5 installed. You can get it from here. It also needs MSCV 7.1 runtime DLLs. In the future I hope to streamline the install process but this will probably need changes in NetLoadModule. I might also want to create my own Python installer to reduce downloadsizes for dialup users.
Recompiled against python 2.5
Fixed memory leak
-thegeek
First version by wols
Load it like any other module with LoadModule or *NetLoadModule
*NetLoadModule PyScript-0.3
If you want to do graphical scripts, especially together with wxPython, you need to load it threaded
*NetLoadModule PyScript-0.3, threaded
There are only two step.rc settings right now: *PyScriptPath and *PyScriptFile. The first one designates a directory for PyScript to look for scripts, the second names the filename to load. Example:
*PyScriptPath $themedir$scripts
*PyScriptFile examplescript
Notice how there is NO .py extension on the filename! If you put the extension there, the file won't load! This is the same how the Python keyword import works.
This is not an introduction into Python. Such an endeavour would be a bit too ambitious in a module readme file. There are many free tutorials and whole books on the web for Python. If you are already a programmer, the Python tutorial coming with Python 2.5 itself is probably all you need to start. Other great free books are Dive into Python, Think like a Computer Scientist, and for advanced reading Thinking in Python. These are only the most popular and comprehensive ones. There are many, many other free ressources for learning python including non-english ones at http://www.python.org/doc/
Here, only the specialities of Python in a Litestep setting will be discussed: please look at the file examplebang.py in the scripts folder inside the PyScript archive, it defines a very simple custom bang. I'd suggest to open it with IDLE; a simple Python editor, coming with the Python 2.5 distribution. IDLE has the advantage of Python syntax highlighting out of the box, making it easier for you to see what's going on.The first line of the file is
import LSAPI
This will load all the LSAPI functions into your script for your usage. It allows you to call LSAPI.LSExecute(...) to call a bang or call an external program for example. Notice the LSAPI. in front of the LSExecute: it signifies that LSExecute is part of the LSAPI python module (yes, python also has modules)
Next is the bangfunction
def examplebang (hwnd, command, args):
LSAPI.LSExecute (0, "!alert \"This is a bang, scripted with PyScript\" ", 1)
Any bang is a Python function which starts with the keyword def and has a colon at the end of the line after the parameters. All bang functions have the same parameters of hwnd,command and args. command is the name of the bang, args are the bang parameters, both are a string. The only action inside our custom bang is a single call to LSExecute. It calls another bang !alert with a simple string to show that our custom bang was called. the zero and the one at beginning and are mostly remnants of the old Litestep API, they are rarely used at all. You can look them up in lssdk.chm which is at lssdk.sf.net. It should also be in the same PyScript archive as the file you're reading right now.
Now we're coming to the beginning of any PyScript file: the InitModuleEx function. As any LS module written in C/C++ this is the place where execution starts when the file is loaded.
def InitModuleEx (hwnd, dllinst, szpath):
LSAPI.AddBangCommandEx ("!pybang", examplebang)
return 0
It starts again with def and a colon at the end since it is another function. The parameter hwnd,dllinst and szpath are all important to be there again or PyScript will report an error. The only function call of note is AddBangCommandEx: it registers our earlier bangfunction with Litestep core. Its parameters are the name of the bang ("!pybang") and the name of the bangfunction (examplebang). The return 0 at the end tells Litestep that everything went alright, if it were something other than zero, LS would assume something went wrong and discard our script.
Now we're almost at the end of our little script and so it is fitting to look at the function responsible for cleaning up after us: QuitModule
def QuitModule ():
LSAPI.RemoveBangCommand ("!pybang")
return
QuitModule is called whenever the script quits: when it's unloaded, reloaded, when there is a !recycle, etc.It is good form, not to mention very necessary if you want to have proper !unload support to unregister all bangs of a script in a orderly fashion. Since it's only a single simple line of LSAPI.RemoveBang it's easy to do, so we do it. QuitModule() also doesn't need any special parameters or return values, so the return at the end isn't even necessary.
PyScript supports almost all functions from LSAPI.DLL verbatim: if the function inside LSAPI has 4 parameters, then the PyScript function has all 4 parameters as well and they also have the exact same meaning. The only exceptions are functions dealing with images. There, the Python bindings for the used toolkit (wxpython, tkinter, pygtk, pyQt, ...) will bring their own Image-handling functions and the LS specific ones wouldn't make much sense. If there is demand, it probably could be implemented however. The second omission is LCTokenize() since the way it does things with call by reference is hard to transport over to Python.
Since I don't want to mindlessly transcribe all functions and their parameters, I included lssdk.chm which has a description of all of them for now. In the future I will describe a few of the most used ones (LSExecute, VarExpansion, Bang functions)