History

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: 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

  1 
  2 # -*- encoding: iso-8859-2 -*-
  3 
  4 import ekg
  5 import time
  6 
  7 def status_handler(session, uid, status, desc):
  8     for sesja in ekg.sessions():
  9     if sesja.connected():
 10         ekg.echo("sesja '%s' połączona" % (session,))
 11         ekg.echo("status: "+sesja['status'])
 12     else:
 13         ekg.echo("sesja '%s' nie jest połączona" % (session,))
 14     ekg.echo("Dostałem status!")
 15     ekg.echo("Sesja : "+session)
 16     ekg.echo("UID   : "+uid)
 17     ekg.echo("Status: "+status)
 18     if desc:
 19     ekg.echo("Opis  : "+desc)
 20     sesja = ekg.session_get(session)
 21     ekg.echo('Lista userów sesji: '+", ".join(map(str, sesja.users())))
 22     user = sesja.user_get(uid)
 23     if user.last_status:
 24     ekg.echo(str(user.last_status))
 25     stat, des = user.last_status
 26     ekg.echo("Ostatni status: "+stat)
 27     if user.last_statusr1:
 28         ekg.echo("Ostatni opis  : "+des)
 29     else:
 30     ekg.echo("Nie ma poprzedniego stanu - pewnie dopiero się łączymy...")
 31     ekg.echo("IP: "+user.ip)
 32     ekg.echo("Grupy: "+", ".join(map(str, user.groups())))
 33     if status == ekg.STATUS_AWAY:
 34     ekg.echo("Chyba go nie ma...")
 35     if status == ekg.STATUS_XA:
 36     ekg.echo("Chyba bardzo go nie ma, to na grzyb mi taki status?. Połykam. *ślurp*")
 37     return 0
 38     return 1
 39 
 40 def message_handler(session, uid, type, text, sent_time, ignore_level):
 41     ekg.debug("[test script] some debug\n")
 42     ekg.echo("Dostałem wiadomość!")
 43     ekg.echo("Sesja : "+session)
 44     ekg.echo("UID   : "+uid)
 45     if type == ekg.MSGCLASS_MESSAGE:
 46     ekg.echo("Typ   : msg")
 47     elif type == ekg.MSGCLASS_CHAT:
 48     ekg.echo("Typ   : chat")
 49     ekg.echo("Czas  : "+time.strftime("%a, %d %b %Y %H:%M:%S %Z", time.gmtime(sent_time)))
 50     ekg.echo("Ign   : "+str(ignore_level))
 51     ekg.echo("TxtLen: "+str(len(text)))
 52     if len(text) == 13:
 53     ekg.echo("Oj, ale pechowa liczba, nie odbieram")
 54     return 0
 55     return 1
 56 
 57 def own_message_handler(session, target, text):
 58     ekg.debug("[test script] some debug\n")
 59     ekg.echo("Wysyłam wiadomość!")
 60     ekg.echo("Sesja : "+session)
 61     ekg.echo("Target: "+target)
 62     ekg.echo("TxtLen: "+str(len(text)))
 63     return 1
 64 
 65 def connect_handler(session):
 66     ekg.echo("Połączono! Ale super! Można gadać!")
 67     ekg.echo("Sesja : "+session)
 68     if session[:3] == 'irc':
 69     struct = time.gmtime()
 70     if structr3 >= 8 and structr3 < 17:
 71         ekg.echo('Ładnie to tak ircować w pracy? ;)')
 72     sesja = ekg.session_get(session)
 73     if sesja.connected():
 74     ekg.echo('Połączony!')
 75     else:
 76     ekg.echo('W tym miejscu jeszcze nie połączony')
 77     ekg.echo('Lista userów sesji: '+", ".join(map(str, sesja.users())))
 78 
 79 def keypress(key):
 80     ekg.echo("nacisnales #"+ str(key));
 81 
 82 def disconnect_handler(session):
 83     ekg.echo("Ło, sesja %s nam padła" % (session,))
 84     ekg.echo("Wysyłamy smsa że nam cuś padło...")
 85 
 86 def foo_command(name, args):
 87     ekg.echo("Wywołane polecenie foo!")
 88 
 89 def varchange(name, newval):
 90     ekg.echo("Zmienna %s zmieniła wartość na %s" % (name, newval) )
 91 
 92 ekg.command_bind('foo', foo_command)
 93 ekg.handler_bind('protocol-message-received', message_handler)
 94 ekg.handler_bind('protocol-message-sent', own_message_handler)
 95 ekg.handler_bind('protocol-status', status_handler)
 96 ekg.handler_bind('protocol-connected', connect_handler)
 97 ekg.handler_bind('protocol-disconnected', disconnect_handler)
 98 ekg.handler_bind('ui-keypress', keypress)
 99 ekg.variable_add('zmienna_testowa', 'wartość', varchange)