Context Navigation

Python plugin

python polish version, wersja polska

loading and configurating

For runing scripts writed in python it is necessarly to load module:

/plugin +python

Files should be put to one of those folders and has ".py" extension

$DATADIR/scripts/
.ekg2/scripts
.ekg2/profil/scripts #dotyczy używania profili :D

available commands

python:eval source_to_eval

source_to_eval will be evaluate as a python source

python:list

it lists all loaded scripts

python:load <script_name | file_name>

example:

/python:load script
/python:load /usr/share/python/my_script.py

loads script, if this script had been loaded before it will be reloaded

python:run <file_name>

it call script from specified localozation

python:unload <script_name | file_name>

Use is similar to python:load. Command unloads script.

script_name - It is name of file without extension which is put to one of default folders( see "loading and configurating")

script_file - It is full path to script.

Parser interface

command( str )

It calls internal ekg2 command.

printf( format, args ...)

prints text on screen in defined format

echo( str )

prints text in generic format

debug( format, args ... )

It prints data for debug output in defined format(like printf).

sessions()

returns list of (session object) consists of available sessions.

session_get( name )

returns particular session object. Throws RuntimeException? if there is no session with this name.

session_current()

returns current session object

plugins()

returns list of available(loaded) plugins.

timer_bind( time, callback )

Call a callback function once in time secounds. Callback function can not get arguments.

handler_bind( sigg_name, callback )

binds function to signal. Function has to get all signal arguments.

command_bind( command_name, callback )

bind command(avaible in ekg2 console) to function in script. Function has to get two arguments the exactly typed commend as first and remaining arguments as second.

variable_add( variable_name, default_value [, callback ])

Define variable in ekg2. This variable will be store in configuration file. The "callback" parameter can define function, calls after each value change of variable. Function has to get two parameters name of variable and new value.

Variables added by this method can be read as normal configuration values. It means read by the ekg.config

window_current()

return current window object.(TODO)

window_get( name )

return window object with specified name. Function recognize two special names "current" and "status".

config

This is dictionary readable and writable to set or get configuration values.

MSGCLASS_MESSAGE

message type: normal message

MSGCLASS_CHAT

message type: conversation

MSGCLASS_SENT

message type: sent message

MSGCLASS_SENT_CHAT

message type: sent message in conversation

MSGCLASS_SYSTEM

message type: system notification

STATUS_NA

User status: Not Available

STATUS_AVAIL

User status: Available

STATUS_AWAY

User status: Away

STATUS_AUTOAWAY

User status: Auto Away

STATUS_INVISIBLE

User status: Invisible

STATUS_XA

User status: Extended Away

STATUS_DND

User status: Do Not Disturb

STATUS_FREE_FOR_CHAT

User status: Free for Chat

STATUS_BLOCKED

User status: Blocked

STATUS_UNKNOWN

User status: Unknown

STATUS_ERROR

User status: Error

IGNORE_STATUS

ignore: status change

IGNORE_STATUS_DESCR

ignore: status description

IGNORE_MSG

ignore: all messages

IGNORE_DCC

ignore: direct conections (DCC)

IGNORE_EVENTS

ignore: events (TODO)

IGNORE_NOTIFY

ignore: notifies

IGNORE_ALL

ignore: all (TODO)

//// TODO /// WATCH_READ

watch: read

WATCH_READ_LINE

watch: read line

WATCH_WRITE

watch: write

self

dictionary access to session variables

connect()

connect session

connected()

return true if session is connected false if not

disconnect()

disconnect session

users()

Returns list of (user object). Those object represent users on contact list.

user_get(identifier)

Returns (user object) specified by the identifier (f.e. gg:123, jid:test@example.com etc.)

status()

return pair (status, description), status is one of stauts constants(describe class of status), description is a string or None.

status_set( status [, description ] )

Set session status and description. Status have to be one of status constants.

switch_to() TODO

Swich to particular window.

echo( str )

print string in current window

echo_format( format, str )

print string in current window with formating

next()

Return window object of next window. Method called from last window return object of first window.

prev()

Similar to next. Return previous window object. Method called from first window return object of last window.

kill()

Close window. After that window object is useless and should be destroyed.

Signals and commands

Script in python can be bind to several events. It could be periodic calling(timer_bind), call defined command by user (command_bind) or get a signal from ekg2(handler_bind) In all of this functions, second parameter is a function (a callback, see: example) not name of function. The first parameter define period, command name and signal name. Below there is list of implemented signals. Each signal has a parameters which are send to functions. Functions have to get all of this parameters.

protocol-message-received

Arguments: session, id, class, text, time, ignore_level

It occurs when message is received.

protocol-message-sent

Arguments: session, rcpts, text

It occurs when user is sending message. RCPTS is string representing receiver, It is exactly what user typed in ekg2 console (it can be alias or full user id, generally the first argument of /msg, /chat, /query and similar commands)

protocol-status

Arguments: session, from, type, desc

It occurs when somebody change status. If callback function returns 0, change of status will be ignored. Return 2 cause that stats change will not be displayed despite it will take effects. If function returns 4 values with the same types as in input. Data will be changed in ekg2.

protocol-status-own (NFY)

Arguments: status, desc

It occurs on session status change, when returns 0 change will not take place.

ui-keypress

Arguments: char

It occurs when user push button on the keyboard. Argument is a code of pushed button.

It is possible to define two more functions called by ekg2.

init()

Called durning script loading, if return 0 script will not be loaded

deinit()

Called durning script unloading.

Example

# -*- encoding: iso-8859-2 -*-

import ekg
import time

def status_handler(session, uid, status, desc):
    for sesja in ekg.sessions():
        if sesja.connected():
            ekg.echo("session '%s' connected" % (session,))
            ekg.echo("status: "+sesja['status'])
        else:
            ekg.echo("session '%s' is not connectrd" % (session,))
    ekg.echo("I get the status")
    ekg.echo("Session: "+session)
    ekg.echo("UID    : "+uid)
    ekg.echo("Status : "+status)
    if desc:
        ekg.echo("desription  : "+desc)
    sesja = ekg.session_get(session)
    ekg.echo('Session user list: '+", ".join(map(str, sesja.users())))
    user = sesja.user_get(uid)
    if user.last_status:
        ekg.echo(str(user.last_status))
        stat, des = user.last_status
        ekg.echo("last status: "+stat)
        if user.last_status[1]:
            ekg.echo("last description  : "+des)
    else:
        ekg.echo("last status is unavailable - propably we just connected...")
    ekg.echo("IP: "+user.ip)
    ekg.echo("Groups: "+", ".join(map(str, user.groups())))
    if status == ekg.STATUS_AWAY:
        ekg.echo("He is not available...")
    if status == ekg.STATUS_XA:
        ekg.echo("He is not available for shure, so what for is this status? It sounds like a mistake.")
        return 0
    return 1

def message_handler(session, uid, type, text, sent_time, ignore_level):
    ekg.debug("[test script] some debug\n")
    ekg.echo("I get a message")
    ekg.echo("Session : "+session)
    ekg.echo("UID   : "+uid)
    if type == ekg.MSGCLASS_MESSAGE:
        ekg.echo("Type  : msg")
    elif type == ekg.MSGCLASS_CHAT:
        ekg.echo("Type  : chat")
    ekg.echo("Time  : "+time.strftime("%a, %d %b %Y %H:%M:%S %Z", time.gmtime(sent_time)))
    ekg.echo("Ign   : "+str(ignore_level))
    ekg.echo("TxtLen: "+str(len(text)))
    if len(text) == 13:
        ekg.echo("I hate thirteen so I do not accept messages with length of 13")
        return 0
    return 1

def own_message_handler(session, target, text):
    ekg.debug("[test script] some debug\n")
    ekg.echo("I am sending a message!")
    ekg.echo("Session: "+session)
    ekg.echo("Target : "+target)
    ekg.echo("TxtLen : "+str(len(text)))
    return 1

def connect_handler(session):
    ekg.echo("Conencted! It is awesome! It is possible to connect others")
    ekg.echo("Session : "+session)
    if session[:3] == 'irc':
        struct = time.gmtime()
        if struct[3] >= 8 and struct[3] < 17:
            ekg.echo('Hey men. You have to be in work at this time. Haven't you?')
    sesja = ekg.session_get(session)
    if sesja.connected():
        ekg.echo('Connected!')
    else:
        ekg.echo('Here we are not connected yet.')
    ekg.echo('Session user list: '+", ".join(map(str, sesja.users())))

def keypress(key):
    ekg.echo("you pressed #"+ str(key));
    
def disconnect_handler(session):
    ekg.echo("Ups session %s is dead" % (session,))
    ekg.echo("Check if you are able to ping google ;-)")

def foo_command(name, args):
    ekg.echo("You call 'foo' command!")

def varchange(name, newval):
    ekg.echo("Variable %s changed value to: %s" % (name, newval) )
    
ekg.command_bind('foo', foo_command)
ekg.handler_bind('protocol-message-received', message_handler)
ekg.handler_bind('protocol-message-sent', own_message_handler)
ekg.handler_bind('protocol-status', status_handler)
ekg.handler_bind('protocol-connected', connect_handler)
ekg.handler_bind('protocol-disconnected', disconnect_handler)
ekg.handler_bind('ui-keypress', keypress)
ekg.variable_add('test_variable', 'value', varchange)

Download in other formats:

Plain Text