# Using python from KVS and vice-versa.

How to use python from KVS and KVS from python.

Introduction
Starting from version 4.0.0 you can include python code snippets in KVS code and you can use KVS commands from within python. This feature is present only if a working python installation has been found at build time. The python support is very similar to the perl support present since 3.x. So if you have used perl from kvirc before you'll find the api is almost the same.. otherwise read on :)
Using python from KVS

Using python from KVIrc is really easy: just enclose your python code snippet inside python.begin and python.end.

    python.begin
    <python code goes here>
    python.end

For example:

    python.begin
    f = open('myfile.txt', 'w')
    f.write('This is a test\n')
    f.close()
    python.end

A python code snippet can appear anywhere a KVS code snippet can with the only restriction that i must be enclosed in python.begin and python.end. This means that you can write python code in the commandline, in the aliases, the event handlers, popups...anywhere.
If you have already encountered the KVIrc's eval command that you probably also know how to execute a python code snippet from a file :)

Using KVS from python

KVIrc exports several commands to the python namespace that allow you to invoke KVIrc's functions from inside the python code snippet.
The nicest example is kvirc.echo():

    python.begin
    kvirc.echo("Hello KVIrc world from python!")
    python.end

kvirc.echo() is the counterpart of the echo. The exact syntax is:
kvirc.echo(<text>[,<colorset>[,<windowid>]])
<text> is obviously the text to be printed. <colorset> is the equivalent of the echo -i option and <windowid> is the equivalent of the -w option. Both <colorset> and <windowid> can be omitted (in this case KVIrc will use a default colorset and the current window).

Python execution contexts

The python code snippets are executed by the means of a python interpreter. Each python interpreter has its own context and thus it's own variables, own function namespace etc.
In the example above KVIrc creates an interpreter when python.begin is invoked and destroys it at python.end parsing time. In fact, KVIrc can mantain multiple persistent interpreters that will allow you to preserve your context across python.begin invocations.
You can invoke a specific python context by passing it as parameter to the python.begin command.

    [cmd]python.begin("mycontext")[/cmd]
    myvariable = "mycontext"
    kvirc.echo("This python code is executed from " + myvariable)
    python.end

The nice thing is that at a later time you can invoke this context again and discover that mycontext has preserved its value:

    [cmd]python.begin("mycontext")[/cmd]
    kvirc.echo("myvariable is still equal to " + myvariable)
    python.end

The first time you invoke a named python context it gets automatically created and it persists until KVIrc terminates or the python context is explicitly destroyed by the means of python.destroy.
In fact there is a third possibility to destroy a context: it's when the pythoncore module is forcibly unloaded (by the means of /pythoncore.unload) but this is really a rare case and should be threated just like a KVIrc restart (the user probably WANTS the contexts to be reinitialized).
The nice thing is that not only your variables will get preserved but also any python function or class you declare in a context will persist. It's just like executing a long python script file with pauses inside.
If you omit the python context name in the python.begin command (or if you use an empty string in it's place) then KVIrc will create a temporary context for the snippet execution and will destroy it immediately after python.end has been called.
The major side effect of keeping persistent python contexts is that the python's symbol table will grow and if not used carefully the interpreter may become a memory hog. So if you're going to use persistent contexts either try to keep the symbol table clean or explicitly call python.destroy once in a while to recreate the interpreter.
If you just execute occasional python code snippets and don't need to keep persistent variables then just use the nameless temporary context provided by python.begin("").

Passing parameters to the python script

The easiest way to pass parameters to the python code snippet is to put them as python.begin arguments. In fact the complete syntax of python.begin is:
python.begin(<python context>,<arg0>,<arg1>,...)
Where the <arg0>,<arg1>...<argN> parameters are passed to the python context as elements of the aArgs array.

    python.begin("","Hello world!","Now I CAN",1,2,3)
    for(i=0;i<5;i++)
        kvirc.echo(aArgs,40)
    python.end

Accessing the KVIrc scripting context from python

KVIrc exposes the following functions that manipulate the variables of the KVIrc's current KVS execution context.
kvirc.getLocal(<x>)
Returns the value of the KVIrc's local variable %x.
kvirc.getGlobal(<Y>)
Returns the value of the KVIrc's global variable %Y.
kvirc.setLocal(<x>,<value>)
Sets the KVIrc's global variable %x to <value>
kvirc.setGlobal(<Y>,<value>)
Sets the KVIrc's global variable %Y to <value>
The local variables interested belong to the current KVS exection context while the global variables are visible everywhere.

    %pippo = test
    %Pluto = 12345
    python.begin
    mypippo = kvirc.getLocal("pippo")
    mypippo += " rox"
    mypluto = kvirc.getGlobal("Pluto")
    mypluto += " rox"
    kvirc.setLocal("pippo",mypluto)
    kvirc.setGlobal("Pluto",mypippo)
    python.end
    echo "\%pippo is" %pippo
    echo "\%Pluto is" %Pluto

Executing arbitrary KVIrc commands from python

You can execute arbitrary KVS commands from python by the means of:
kvirc.eval(<code>)
This function behaves exactly like the ${ <code> } KVS construct: it executes <code> in a child context and returns it's evaluation retult.
The following two code snippets have equivalent visible effects:

    echo ${ return "Yeah!"; }

    python.begin
    kvirc.echo(kvirc.eval("return \"Yeah!\""));
    python.end

You can "eval" composite command sequences and variable ones.
Remember that the python code snippet is evaluated in a child KVS context and thus the local variables are NOT visible!. The following code snippets may easily fool you:

    %x = 10
    python.begin
    kvirc.eval("echo \"The value is %x\"")
    python.end

This will print "The value is " since %x is not accessible from the eval's context. If you have tried to write something like this then you probably need to rewrite it as:

    %x = 10
    python.begin
    x = kvirc.getLocal("x")
    kvirc.eval("echo \"The value is ".$x."\"")
    python.end

A shortcut for kvirc.eval("/say...")

Since kvirc.eval("/say...") is a common calling pattern then say has been added to the KVIrc python namespace. You can now call

    kvirc.say("Hi all!")

and that will mimic the behaviour of

    /say Hi all!

The complete syntax for kvirc.say() is:
kvirc.say(<text>[,<windowid>])
and the semantics are obvious (see also /say).

The python script return values
The python.begin command propagates the python code return value to the KVIrc context (just like a setreturn() would do). In fact the python snippet return value is the last "thing" that the interpreter evaluates. In this way you can write python aliases that return values without doing any variable passing equilibrism.
Executing python scripts from files

    alias(pythonexec)
    {
        %tmp = "python.begin(\"\",$1,$2,$3,$4,$5)";
        %tmp .= $file.read($0);
        %tmp .= "python.end";
        eval %tmp;
    }
    pythonexec "/home/pragma/mypythonscript.pl" "param1" "param2" "param3"
    # or even
    echo $pythonexec("/home/pragma/computeprimelargerthan.pl","10000")

Curiosity

The python support in KVIrc is implemented as a master-slave module pair. The python.* module is the master while pythoncore is the slave. When the python support isn't compiled in, the python.* commands print some warnings and exit gracefully while the pythoncore module refuses to be loaded. When python support is compiled in but for some reason the libpython.so can't be found or loaded then pythoncore fails the dynamic loading stage but python.* still fails gracefully with just some warning messages. This trick allows the scripters to check for python support with $python.isavailable and to embed python code snippets in KVS even if the support is missing. The snippets will be just skipped.
Happy python hacking :)

Index, Language Overview

KVIrc 4.2.0.6190 Documentation
Generated by root at Mon Sep 23 13:56:02 2013