Python plugin

python en english version, wersja angielska

ładowanie i konfiguracja

do wykonywania skryptów konieczne jest załadowanie:

/plugin +python

skrypty powinny mieć rozszerzenie .py i należy je umieścić w jednym z katalogów:

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

dostępne polecenia

• python:eval kod_do_wykonania

wykonuje kod pythona podany jako parametr

• python:list

wyświetla listę załadowanych skryptów

• python:load <nazwa_skryptu | nazwa_pliku>

ładuje skrypt, jeżeli skrypt był już załadowany - przeładowuje go.

• python:run <nazwa_pliku>

wywołuje skrypt znajdujący się w podanej lokalizacji

• python:unload <nazwa_skryptu | nazwa_pliku>

"wyładowuje" skrypt ;-)

nazwa_skryptu - to nazwa pliku .py znajdującego się w .ekg2/scripts/ może zostać podana bez rozszerzenia

nazwa_pliku - to ścierzka do pliku ze skryptem

Interfejs od strony interpretera

command( str )

Wywołanie polecenia ekg2

printf( format, args ...)

Wyświetlenie tekstu w podanym formacie.

echo( str )

Wyświetlenie tekstu w formacie generic

debug( format, args ... )

Zapisanie danych debugowych w podanym formacie (notacja printf).

sessions()

Zwraca listę obiektów typu session(session object) zawierającą dostępne sesje.

session_get( nazwa )

Zwraca obiekt sesyjny sesji o podanej nazwie. Podnosi wyjątek RuntimeException? jeśli takiej sesji nie ma.

session_current()

Zwraca obiekt reprezentujący bieżącą sesję.

plugins()

Zwraca listę zawierająca załadowane pluginy.

timer_bind( czas, callback )

Wykonuje funkcję callback co podany czas. Funkcja ta nie może przyjmować argumentów.

handler_bind( nazwa_sygnału, callback )

Łączy funkcję callback z sygnałem o podanej nazwie. Funkcja musi przyjmować argumenty takie, jakie przesyłane są z sygnałem.

command_bind( nazwa_polecenia, callback )

Łączy funkcję callback z reakcją na wykonanie polecenia. Funkcja musi przyjmować dwa argumenty: nazwę wpisanego polecenia i argumenty mu przekazane.

variable_add( nazwa_zmiennej, początkowa_wartość [, callback ])

Dodaje zmienną skryptową, która będzie zapisywana w pliku konfiguracyjnym ekg2. Opcjonalny parametr callback może zawierać funkcję, która będzie wykonywana przy każdej zmianie wartości dodawanej zmiennej. Funkcja musi przyjmować dwa argumenty: nazwę zmiennej i jej nową wartość.

Zmienne dodane metodą variable_add można odczytywać tak, jak wszystkie inne ustawienia konfiguracyjne, tj. za pomocą słownika ekg.config

window_current()

Zwraca obiekt window reprezentujący bieżące okno

window_get( nazwa )

Zwraca obiekt window reprezentujący okno o podanej nazwie. Funkcja rozpoznaje także nazwy current i status.

config

Słownik zawierający opcję konfiguracji ekg (odczyt i zapis)

MSGCLASS_MESSAGE

typ wiadomości. wiadomość

MSGCLASS_CHAT

typ wiadomości. rozmowa ciągła

MSGCLASS_SENT

typ wiadomości. wysłana wiadomość

MSGCLASS_SENT_CHAT

typ wiadomości. wysłana wiadomość w ramach rozmowy ciągłej

MSGCLASS_SYSTEM

typ wiadomości. wiadomość systemowa

STATUS_NA

stan. Not Available (rozłączony)

STATUS_AVAIL

stan. Available (dostępny)

STATUS_AWAY

stan. Away (z dala od klawiatury)

STATUS_AUTOAWAY

stan. Auto Away (automatyczny stan bezczynności)

STATUS_INVISIBLE

stan. Invisible (niewidoczny)

STATUS_XA

stan. Extended Away (niedostępny)

STATUS_DND

stan. Do Not Disturb (nie przeszkadzać)

STATUS_FREE_FOR_CHAT

stan. Free for Chat (chętny do rozmowy)

STATUS_BLOCKED

stan. Blocked (zablokowany)

STATUS_UNKNOWN

stan. Unknown (nieznany)

STATUS_ERROR

stan. Error (błąd)

IGNORE_STATUS

ignorowanie. zmian stanu

IGNORE_STATUS_DESCR

ignorowanie. stanów z opisem

IGNORE_MSG

ignorowanie. wiadomości

IGNORE_DCC

ignorowanie. połączeń bezpośrednich (DCC)

IGNORE_EVENTS

ignorowanie. zdarzeń

IGNORE_NOTIFY

ignorowanie. powiadomień

IGNORE_ALL

ignorowanie. wszystkiego

WATCH_READ

watche. odczyt

WATCH_READ_LINE

watche. odczyt po lini

WATCH_WRITE

watche. zapis

self

Słownikowy dostęp do konfiguracji sesji.

connect()

Łączy sesję.

connected()

Zwraca True jeśli sesja jest połączona, False wpp.

disconnect()

Rozłącza sesję.

users()

Zwraca listę obiektów użytkowników(user object) na liście danej sesji.

user_get(nazwa)

Zwraca obiekt klasy user(user object) o danym identyfikatorze (gg:123, jid:test@example.com itp.)

status()

Zwraca tuple ( status, opis ), gdzie status jest jedną ze stałych określających typ stanu. W przypadku braku opisu, drugą wartością będzie None.

status_set( status [, opis ] )

Ustawia status i ewentualnie opis. Status musi być jedną ze stałych opisujących stan.

switch_to()

Przełącza widok na dane okno.

echo( str )

Wyświetla napis w danym oknie.

echo_format( format, str )

Wyświetla napis w podanym formacie

next

Zwraca obiekt reprezentujący następne okno. Lista okien jest "zawijana", tzn. wywołanie metody next() na ostatnim oknie zwróci obiekt pierwszego okna.

prev

Zwraca obiekt reprezentujący poprzednie okno. Lista okien jest "zawijana", tzn. wywołanie metody prev() na pierwszym oknie zwróci obiekt ostatniego okna.

kill

Zamyka okno. W tym momencie obiekt klasy window powinien być usunięty, gdyż nie można już go używać.

Obsługa poleceń i sygnałów

Skrypty w pythonie można "podpinać" do różnych zdarzeń. Może to być wykonanie funkcji co podany okres czasu (metoda timer_bind), poprzez wykonanie polecenia (command_bind) lub reakcja na sygnał wydany przez ekg2 (handler_bind). We wszystkich przypadkach, drugim argumentem jest funkcja (nie nazwa, lecz sama funkcja - por. przykład), która ma być wykonana. Pierwszym natomiast, odpowiednio interwał, nazwa polecenia lub nazwa sygnału. Poniżej zamieszczona jest lista zawierająca obsługiwane obecnie sygnały, oraz argumenty, które musi przyjmować funkcja obsługująca sygnał.

protocol-message-received

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

Wywoływana gdy ekg otrzymuje wiadomość.

protocol-message-sent

Argumenty: session, rcpts, text

Wywoływana gdy użytkownik wysyła wiadomość. rcpts jest tekstową reprezentacją odbiorcy, dokładnie taką jak podał użytkownik (pierwszy argument /msg, /chat, /query itd).

protocol-status

Argumenty: session, from, type, desc

Wywoływana gdy ktoś zmienia stan. nazwy parametrów powinny być zrozumiałe. jeśli zwróci 0, zmiana stanu zostanie zignorowana. jeśli zwróci 2, zmiana stanu nie będzie ignorowana, ale nie zostanie wyświetlona. jeśli zwróci krotkę o takich samych argumentach jak funkcja, dane zostaną zmienione.

protocol-status-own (NFY)

Argumenty: status, desc

Wywoływana gdy klient zmienia stan. Jeśli zwróci 0, stan nie zostanie zmieniony.

ui-keypress

Argumenty: char

Wywoływane w momencie wciśnięcia przycisku. Argumentem jest kod wciśniętego klawisza.

Oprócz sygnałów, możliwe jest zdefiniowanie dwóch funkcji, które są rozpoznawane przez ekg2.

init()

Wywoływana gdy skrypt jest ładowany. Jeśli ta funkcja zwróci 0, skrypt nie zostanie załadowanych.

deinit()

Wywoływana gdy skrypt jest usuwany z pamięci.

Przykładowy skrypt

# -*- 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("sesja '%s' połączona" % (session,))
            ekg.echo("status: "+sesja['status'])
        else:
            ekg.echo("sesja '%s' nie jest połączona" % (session,))
    ekg.echo("Dostałem status!")
    ekg.echo("Sesja : "+session)
    ekg.echo("UID   : "+uid)
    ekg.echo("Status: "+status)
    if desc:
        ekg.echo("Opis  : "+desc)
    sesja = ekg.session_get(session)
    ekg.echo('Lista userów sesji: '+", ".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("Ostatni status: "+stat)
        if user.last_status[1]:
            ekg.echo("Ostatni opis  : "+des)
    else:
        ekg.echo("Nie ma poprzedniego stanu - pewnie dopiero się łączymy...")
    ekg.echo("IP: "+user.ip)
    ekg.echo("Grupy: "+", ".join(map(str, user.groups())))
    if status == ekg.STATUS_AWAY:
        ekg.echo("Chyba go nie ma...")
    if status == ekg.STATUS_XA:
        ekg.echo("Chyba bardzo go nie ma, to na grzyb mi taki status?. Połykam. *ślurp*")
        return 0
    return 1

def message_handler(session, uid, type, text, sent_time, ignore_level):
    ekg.debug("[test script] some debug\n")
    ekg.echo("Dostałem wiadomość!")
    ekg.echo("Sesja : "+session)
    ekg.echo("UID   : "+uid)
    if type == ekg.MSGCLASS_MESSAGE:
        ekg.echo("Typ   : msg")
    elif type == ekg.MSGCLASS_CHAT:
        ekg.echo("Typ   : chat")
    ekg.echo("Czas  : "+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("Oj, ale pechowa liczba, nie odbieram")
        return 0
    return 1

def own_message_handler(session, target, text):
    ekg.debug("[test script] some debug\n")
    ekg.echo("Wysyłam wiadomość!")
    ekg.echo("Sesja : "+session)
    ekg.echo("Target: "+target)
    ekg.echo("TxtLen: "+str(len(text)))
    return 1

def connect_handler(session):
    ekg.echo("Połączono! Ale super! Można gadać!")
    ekg.echo("Sesja : "+session)
    if session[:3] == 'irc':
        struct = time.gmtime()
        if struct[3] >= 8 and struct[3] < 17:
            ekg.echo('Ładnie to tak ircować w pracy? ;)')
    sesja = ekg.session_get(session)
    if sesja.connected():
        ekg.echo('Połączony!')
    else:
        ekg.echo('W tym miejscu jeszcze nie połączony')
    ekg.echo('Lista userów sesji: '+", ".join(map(str, sesja.users())))

def keypress(key):
    ekg.echo("nacisnales #"+ str(key));
    
def disconnect_handler(session):
    ekg.echo("Ło, sesja %s nam padła" % (session,))
    ekg.echo("Wysyłamy smsa że nam cuś padło...")

def foo_command(name, args):
    ekg.echo("Wywołane polecenie foo!")

def varchange(name, newval):
    ekg.echo("Zmienna %s zmieniła wartość na %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('zmienna_testowa', 'wartość', varchange)