From cd5b47f76cf014c4a81940e0994fba1964b74264 Mon Sep 17 00:00:00 2001 From: Paulina Date: Thu, 27 Feb 2020 16:58:54 +0100 Subject: Eng and pl tutorials added. --- docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst | 1786 +++++++++++++++++++ .../make_plugin_extension_for_message_and_iq.rst | 1820 ++++++++++++++++++++ 2 files changed, 3606 insertions(+) create mode 100644 docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst create mode 100644 docs/howto/make_plugin_extension_for_message_and_iq.rst (limited to 'docs/howto') diff --git a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst new file mode 100644 index 00000000..a679f62c --- /dev/null +++ b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst @@ -0,0 +1,1786 @@ +Jak stworzyć własny plugin rozszerzający obiekty Message i Iq w Slixmpp +======================================================================= + +Wstęp i wymagania +----------------- + +* `'python3'` + +Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6+. + +Dla wstecznej kompatybilności z wcześniejszymi wersjami, wystarczy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. + +Instalacja dla Ubuntu linux: + +.. code-block:: bash + + sudo apt-get install python3.6 + +* `'slixmpp'` +* `'argparse'` +* `'logging'` +* `'subprocess'` +* `'threading'` + +Sprawdź czy powyżej wymienione bibliteki są dostępne w twoim środowisku wykonawczym. (Wszystkie z wyjątkiem slixmpp są w standardowej bibliotece pythona, jednak czasem kompilując źródła samodzielnie, część ze standardowych bibliotek może nie być zainstalowana z pythonem. + + +.. code-block:: python + + python3 --version + python3 -c "import slixmpp; print(slixmpp.__version__)" + python3 -c "import argparse; print(argparse.__version__)" + python3 -c "import logging; print(logging.__version__)" + python3 -m subprocess + python3 -m threading + +Mój wynik komend: + +.. code-block:: bash + + ~ $ python3 --version + Python 3.8.0 + ~ $ python3 -c "import slixmpp; print(slixmpp.__version__)" + 1.4.2 + ~ $ python3 -c "import argparse; print(argparse.__version__)" + 1.1 + ~ $ python3 -c "import logging; print(logging.__version__)" + 0.5.1.2 + ~ $ python3 -m subprocess #To nie powinno nic zwrócić + ~ $ python3 -m threading #To nie powinno nic zwrócić + +Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, dla potrzeb tutorialu powinny zostać zainstalowane jak na przykładzie poniżej: + +Instalacja na Ubuntu linux: + +.. code-block:: bash + + pip3 install slixmpp + #or + easy_install slixmpp + +Jeśli jakaś biblioteka zwróci NameError, zainstaluj pakiet ponownie. + +* `Konta dla Jabber` + +Do testowania, na potrzeby tutorialu będą niezbędne dwa prywatne konta jabbera. +Aby stworzyć nowe konto, w sieci istnieje dużo dostępnych darmowych serwerów: + +https://www.google.com/search?q=jabber+server+list + +Skrypt uruchamiający klientów +----------------------------- + +Poza lokalizacją projektu, powinniśmy stworzyć skrypt uruchamiający klientów testowo aby szybko móc sprawdzić czy rezultat jest prawidłowy. Ważne aby skrypt był poza projektem aby na przykład uniknąć przypadkowego wysłania na platformę gita swoich danych logowania. + +Na moim urządzeniu stworzyłem w ścieżce `'/usr/bin'` plik o nazwie `'test_slixmpp'` i dodałem uprawnienia do wykonywania go: + +.. code-block:: bash + + /usr/bin $ chmod 711 test_slixmpp + +Ten plik w tej formie powinniśmy móc edytować i czytać wyłącznie z uprawnieniami superuser. Plik zawiera prostą strukturę która pozwoli nam zapisać swoje dane logowania. + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala + #~ prefix = "xterm -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about rights to run your python files. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + +Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Więc dla jeszcze wcześniejszej kompatybilności można dopasować argumenty i podmienić na metodę `'subprocess.call()'`. + +Skrypt uruchomieniowy powinien być dopasowany do naszych potrzeb, można pobierać ścieżki do projektu z linii komend, wybierać z jaką flagą mają zostać uruchomione programy i wiele innych rzeczy które będą nam potrzebne. W tym punkcie musimy dostosować skrypt do swoich potrzeb co zaoszczędzi nam masę czasu w trakcie pracy. + +Dla testowania większych aplikacji podczas tworzenia pluginu, w mojej opinii szczególnie użyteczne są osobne linie poleceń dla każdego klienta aby zachować czytelność który i co zwraca, bądź który powoduje błąd. + +Stworzenie klienta i pluginu +---------------------------- + +W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. I stworzyłem klientów: `'sender'` i `'responder'`. Poniżej minimalna implementacja dla efektywnego testowania gdzie będziemy testować nasz plugin w trakcie jego projektowania: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Dwie niewymagane metody, pozwalające innym użytkownikom zobaczyć że jesteśmy online i wyświetlić tą informację + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy naszego example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Dwie niewymagane metody, pozwalające innym użytkownikom zobaczyć że jesteśmy online i wyświetlić tą informację + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy naszego example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +Następny plik który powinniśmy stworzyć to `'example_plugin'` ze ścieżką dostępną dla importu z poziomu klientów. Domyślnie umieszczam w tej samej lokalizacji co klientów. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin + self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin dodając to do `slixmpp/plugins/__init__.py` do pola `__all__` z prefixem xep 'xep_OPE'. W innym wypadku jest to tylko notka czytelna dla ludzi + + namespace = ExampleTag.namespace + + + class ExampleTag(ElementBase): + name = "example_tag" ##~ Nazwa naszego głównego taga dla XML w tym rozszerzeniu. + namespace = "https://example.net/our_extension" ##~ Namespace dla naszego obiektu jest definiowana w tym miejscu, powinna się odnosić do naszego portalu, w wiadomości wygląda tak: + + plugin_attrib = "example_tag" ##~ Nazwa pod którą będziemy odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo, tutaj rejestrujemy nazwę naszego obiektu by móc się do niego odwoływać z zewnątrz. Będziemy mogli się do niego odwoływać na przykład jak do słownika: stanza_object['example_tag']. `'example_tag'` staje się naszą nazwą pluginu i powinno być takie samo jak name. + + interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów naszego elementu które mogą być użyte w naszym elemencie. Na przykład `stanza_object['example_tag']` poda nam informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest nazwą naszego elementu. + +Jeżeli powyższy plugin nie jest w naszej lokalizacji a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu aby był dostępny z poziomu klientów: +.. code-block:: bash + + ln -s $Path_to_example_plugin_py $Path_to_clients_destinations + +Jeszcze innym wyjściem jest import relatywny z użyciem kropek aby dostać się do właściwej ścieżki. + +Pierwsze uruchomienie i przechwytywanie eventów +----------------------------------------------- + +Aby sprawdzić czy wszystko działa prawidłowo, możemy użyć metody `'start'`, ponieważ przypiszemy do niego event `'session_start'`, ten sygnał zostanie wywołany zaraz po tym gdy klient będzie gotów do działania, a własna metoda pozwoli nam zdefiniować odpowiednią czynność dla tego sygnału. + +W metodzie `'__init__'` tworzymy przekierowanie dla wywołania eventu `'session_start'` i kiedy zostanie wywołany, nasza metoda `'def start(self, event):'` będzie wykonana. Na pierwszy krok, dodajmy linię `'logging.info("I'm running")'` dla obu klientów (sender i responder) i użyjmy naszej komendy `'test_slixmpp'`. + +Teraz metoda `'def start(self, event):'` powinna wyglądać tak: + +.. code-block:: python + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + logging.info("I'm running") + #<<<<<<<<<<<< + +Jeśli oba klienty uruchomiły się poprawnie, możemy zakomentować te linię i wysłać naszą pierwszą wiadomość z pomocą następnego rozdziału. + +Budowanie obiektu Message +------------------------- + +W tym rozdziale, wysyłający powinien dostać informację do kogo należy wysłać wiadomość z linii komend za pomocą naszego skryptu testowego. +W poniższym przykładzie, dostęp do tej informacji mamy za pośrednictwem atrybutu `'selt.to'`: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Domyślnie mtype == "chat" if None; + msg = self.make_message(mto=to, mbody=body) + msg.send() + #<<<<<<<<<<<< + +W przykładzie, używamy wbudowanej metody `'make_message'` która tworzy dla nas wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli wyśle ją raz, zaraz po uruchomieniu. + +Aby otrzymać tą wiadomość, responder powinien wykorzystać odpowiedni event którego wywołanie jest wbudowane. Ta metoda decyduje co zrobić gdy dotrze do nas wiadomość której nie został przypisany inny event (na przykład naszej rozszerzonej w dalszej części) oraz posiada treść. +Przykład kodu: + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + #>>>>>>>>>>>> + self.add_event_handler("message", self.message) + #<<<<<<<<<<<< + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def message(self, msg): + #Pokazuje cały XML naszej wiadomości + logging.info(msg) + #Pokazuje wyłącznie pole 'body' wiadomości, podobnie jak dostęp do słownika + logging.info(msg['body']) + #<<<<<<<<<<<< + +Rozszerzenie Message o nasz tag ++++++++++++++++++++++++++++++++ + +Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message, w innym wypadku message['example_tag'] będzie polem napisowym, zamiast rozszerzeniem które będzie mogło zawierać swoje atrybuty i pod-elementy. + #<<<<<<<<<<<< + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + #<<<<<<<<<<<< + +Teraz dzięki rejestracji tagu, możemy rozszerzyć naszą wiadomość. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + msg = self.make_message(mto=to, mbody=body) + #>>>>>>>>>>>> + msg['example_tag'].set_some_string("Work!") + logging.info(msg) + #<<<<<<<<<<<< + msg.send() + +Teraz po uruchomieniu, logging powinien pokazać nam Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z naszym napisem `'Work'` oraz nadanym namespace. + +Nadanie oddzielnego sygnału dla rozszerzonej wiadomości ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Jeśli nie sprecyzujemy swojego eventu, zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, musimy zarejestrować odpowiedni handler dla naszego namespace oraz tagu aby stworzyć unikalną kombinację, która pozwoli nam przechwycić wyłącznie pożądane wiadomości (lub Iq object). + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', ##~ Nazwa tego Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytujemy wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag + self.__handle_message)) ##~ Metoda do której przypisujemy przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. + #<<<<<<<<<<<< + register_stanza_plugin(Message, ExampleTag) + + #>>>>>>>>>>>> + def __handle_message(self, msg): + # Tu możemy coś zrobić z przechwyconą wiadomością zanim trafi do klienta. + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. + #<<<<<<<<<<<< + +Obiekt StanzaPath powinien być poprawnie zainicjalizowany, oto schemat aby zrobić to poprawnie: +`'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` + +* Dla NAZWA_OBIEKTU możemy użyć `'message'` lub `'iq'`. +* Dla TYP_OBIEKTU jeśli obiektem jest message, możemy sprecyzować typ dla message, np. `'chat'` +* Dla TYP_OBIEKTU jeśli obiektem jest iq, możemy sprecyzować typ spośród: `'get, set, error or result'` +* Dla NAMESPACE zawsze to powinien być namespace z naszego rozszerzenia tagu. +* Dla TAG powinno zawierać nasz tag, `'example_tag'` w tym przypadku. + +Teraz, przechwytujemy wszystkie message które zawierają nasz namespace wewnątrz `'example_tag'`, możemy jak w programowaniu agentowym sprawdzić co zawiera, czy na pewno posiada wymagane pola itd. przed wysłaniem do klienta za pośrednictwem eventu `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message", "example_string") + + def send_example_message(self, to, body, some_string=""): + msg = self.make_message(mto=to, mbody=body) + if some_string: + msg['example_tag'].set_some_string(some_string) + msg.send() + #<<<<<<<<<<<< + +Powinniśmy zapamiętać linię z naszego pluginu: `'self.xmpp.event('example_tag_message', msg)'` + +W tej linii zdefiniowaliśmy nazwę eventu aby go przechwycić wewnątrz pliku responder.py. Jest nim `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja handlera + #<<<<<<<<<<<< + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def example_tag_message(self, msg): + logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq już tak) + #<<<<<<<<<<<< + +Teraz możemy odesłać wiadomość, ale nic się nie stanie jeśli tego nie zrobimy. Natomiast kolejny obiekt do komunikacji (Iq) wymaga odpowiedzi jeśli został wysłany, więc obydwaj klienci powinni być online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cel Iq nie odpowie za pomocą Iq o tym samym Id. + +Użyteczne metody i inne +----------------------- + +Modyfikacja przykładowego obiektu `Message` na `Iq`. +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Aby przerobić przykładowy obiekt Message na obiekt Iq, musimy zarejestrować nowy handler dla Iq podobnie jak dla wiadomości w rozdziale `,,Rozszerzenie Message o nasz tag''`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami, jest to użyteczne aby kod był czytelny, oraz odpowiednia weryfikacja lub działanie zostało podjęte pomijając sprawdzanie typu. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią, inaczej wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). Dlatego jest to bardziej wymiana informacji pomiędzy maszynami niż ludźmi którzy mogą zareagować zbyt wolno i stracić szansę na odpowiedź. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), + self.__handle_get_iq)) + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), + self.__handle_result_iq)) + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), + self.__handle_error_iq)) + #<<<<<<<<<<<< + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', + StanzaPath(f'message/{{{namespace}}}example_tag'), + self.__handle_message)) + + #>>>>>>>>>>>> + register_stanza_plugin(Iq, ExampleTag) + #<<<<<<<<<<<< + register_stanza_plugin(Message, ExampleTag) + + #>>>>>>>>>>>> + # Wszystkie możliwe typy Iq to: get, set, error, result + def __handle_get_iq(self, iq): + self.xmpp.event('example_tag_get_iq', iq) + + def __handle_result_iq(self, iq): + self.xmpp.event('example_tag_result_iq', iq) + + def __handle_error_iq(self, iq): + self.xmpp.event('example_tag_error_iq', iq) + #<<<<<<<<<<<< + + def __handle_message(self, msg): + self.xmpp.event('example_tag_message', msg) + +Eventy wywołane przez powyższe handlery, mogą zostać przechwycone jak w przypadku eventu `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_message", self.example_tag_message) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem że odbiorca jest offline. + logging.info(str(iq)) + reply = iq.reply(clear=False) + reply.send() + #<<<<<<<<<<<< + +Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True, wtedy to co jest zawarte wewnątrz Iq (z kilkoma wyjątkami) powinno zostać zdefiniowane ponownie. Jedyne informacje które zostaną w Iq po metodzie reply, nawet gdy parametr clean jest ustawiony na True, to ID tego Iq oraz JID wysyłającego. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + #<<<<<<<<<<<< + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.send_example_iq(self.to) + # Info_inside_tag + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" + iq['example_tag']['some_string'] = "Another_string" + iq['example_tag'].text = "Info_inside_tag" + iq.send() + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + + def example_tag_error_iq(self, iq): + logging.info(str(iq)) + #<<<<<<<<<<<< + +Dostęp do elementów ++++++++++++++++++++ + +Aby dostać się do pól wewnątrz Message lub Iq, jest kilka możliwości. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + #... + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + #>>>>>>>>>>>> + logging.info(iq['id']) + logging.info(iq.get('id')) + logging.info(iq['example_tag']['boolean']) + logging.info(iq['example_tag'].get('boolean')) + logging.info(iq.get('example_tag').get('boolean')) + #<<<<<<<<<<<< + +Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że nie musimy już precyzować tagu którego dotyczy. Dodatkową zaletą jest fakt niejednolitego dostępu, na przykład do parametru `'text'` między rozpoczęciem a zakończeniem tagu, co obrazuje poniższy przykład, ujednolicając metody do obiektowych getterów i setterów. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + #<<<<<<<<<<<< + +Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. + +Kiedy odpowiednie gettery i settery są stworzone, umożliwia sprawdzenie czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def send_example_iq(self, to): + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" #Przypisanie wprost + #>>>>>>>>>>>> + iq['example_tag'].set_some_string("Another_string") #Przypisanie poprzez setter + iq['example_tag'].set_text("Info_inside_tag") + #<<<<<<<<<<<< + iq.send() + +Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Żeby wczytać wcześniej zdefiniowany napis, z pliku albo lxml (ElementTree) jest dużo możliwości, tutaj pokażę przykład wykorzystując parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + #... + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + #... + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + #<<<<<<<<<<<< + +Do przetestowania tej funkcjonalności, będziemy potrzebować pliku zawierającego xml z naszym tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): + +.. code-block:: xml + + #File: $WORKDIR/test_example_tag.xml + + Info_inside_tag + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + #... + from slixmpp.xmlstream import ET + #... + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.disconnect_counter = 3 # Ta zmienna jest tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. + + def send_example_iq_tag_from_file(self, to, path): + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + #<<<<<<<<<<<< + +Jeśli Responder zwróci nasze wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa jak powinno. + +Łatwość użycia pluginu dla programistów ++++++++++++++++++++++++++++++++++++++++ + +Każdy plugin powinien posiadać pewne obiektowe metody, wczytanie danych jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. +Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego, aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, zamiast tego wysyłający dostaje error z komunikatem timeout. + +Poniżej przykład kodu podyktowanego tymi zasadami: + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), + self.__handle_get_iq)) + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), + self.__handle_result_iq)) + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), + self.__handle_error_iq)) + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', + StanzaPath(f'message/{{{namespace}}}example_tag'), + self.__handle_message)) + + register_stanza_plugin(Iq, ExampleTag) + register_stanza_plugin(Message, ExampleTag) + + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + self.xmpp.event('example_tag_get_iq', iq) + + def __handle_result_iq(self, iq): + self.xmpp.event('example_tag_result_iq', iq) + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) + + def __handle_message(self, msg): + self.xmpp.event('example_tag_message', msg) + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + self.set_boolean(boolean) + self.set_some_string(some_string) + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + self.add_event_handler("example_tag_message", self.example_tag_message) + + def start(self, event): + self.send_presence() + self.get_roster() + + def example_tag_get_iq(self, iq): + logging.info(iq) + reply = iq.reply() + reply["example_tag"].fill_interfaces(True, "Reply_string") + reply.send() + + def example_tag_message(self, msg): + logging.info(msg) + + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + self.send_presence() + self.get_roster() + + self.disconnect_counter = 5 + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() + + def send_example_iq(self, to): + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_message(self, to): + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + + + +Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Aby stworzyć zagnieżdżony tag, wewnątrz naszego głównego tagu, rozważmy nasz atrybut `'self.xml'` jako Element z ET (ElementTree). + +Można powtórzyć poprzednie działania, inicjalizować nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree z pomocą metody `'append'`. Jeśli przetwarzamy typ napisowy, można to zrobić nawet dzięki parsowaniu napisu na Element i kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, tu pokażę bardziej ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + #(...) + + class ExampleTag(ElementBase): + + #(...) + + def add_inside_tag(self, tag, attributes, text=""): + #Gdy chcemy dodać tagi wewnętrzne do naszego taga, to jest prosty przykład jak to zrobić: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z naszym wewnętrznym tagiem, na przykład: + itemXML.attrib.update(attributes) #~ Przypisujemy zdefiniowane atrybuty, na przykład: + itemXML.text = text #~ Dodajemy text wewnątrz tego tagu: our_text + self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z naszym tagiem `example_tag`. + +Kompletny kod z tutorialu +------------------------- + +Do kompletnego kodu pozostawione zostały angielskie komentarze, tworząc własny plugin za pierwszym razem, jestem przekonany że będą przydatne: + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal + #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about rights to run your python files. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + # All iq types are: get, set, error, result + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + # Do something with received iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_result_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + #There should keys should be also validated + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + #Some validation if it is necessary + self.set_boolean(boolean) + self.set_some_string(some_string) + + def add_inside_tag(self, tag, attributes, text=""): + #If we want to fill with additionaly tags our element, then we can do it that way for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: + itemXML.text = text #~ Fill field inside tag, for example: our_text + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + + +~ + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/test_example_tag.xml +.. code-block:: xml + + Info_inside_tag + + +Źródła i bibliogarfia +--------------------- + +Slixmpp project description: + +* https://pypi.org/project/slixmpp/ + +Official web documentation: + +* https://slixmpp.readthedocs.io/ + + +Official pdf documentation: + +* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf + +Note: Dokumentacje w formie Web i PDF mają pewne różnice, pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. + + diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst new file mode 100644 index 00000000..af1fd2eb --- /dev/null +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -0,0 +1,1820 @@ +How to make own slixmpp plugin for Message and IQ extension +=========================================================== + +Introduction and requirements +----------------------------- + +* `'python3'` + +Code used in tutorial is compatybile with python version 3.6+. + +For backward compatybility with versions before, delete f-strings functionality and replace this with older string formatting `'"{}".format("content")'` or `'%s, "content"'`. + +Ubuntu linux installation: + +.. code-block:: bash + + sudo apt-get install python3.6 + +* `'slixmpp'` +* `'argparse'` +* `'logging'` +* `'subprocess'` +* `'threading'` + +Check if these libraries and proper python version are available at your environment. +(all except slixmpp are in standard python library, this is very exceptionally situation to don't have it insalled with python) + +.. code-block:: python + + python3 --version + python3 -c "import slixmpp; print(slixmpp.__version__)" + python3 -c "import argparse; print(argparse.__version__)" + python3 -c "import logging; print(logging.__version__)" + python3 -m subprocess + python3 -m threading + +My output: + +.. code-block:: bash + + ~ $ python3 --version + Python 3.8.0 + ~ $ python3 -c "import slixmpp; print(slixmpp.__version__)" + 1.4.2 + ~ $ python3 -c "import argparse; print(argparse.__version__)" + 1.1 + ~ $ python3 -c "import logging; print(logging.__version__)" + 0.5.1.2 + ~ $ python3 -m subprocess #This should return nothing + ~ $ python3 -m threading #This should return nothing + +If some of libraries throws `'ImportError'` or `'no module named ...'`, try to install it with following example: + +Ubuntu linux installation: + +.. code-block:: bash + + pip3 install slixmpp + #or + easy_install slixmpp + +If some of libraries throws NameError, reinstall package. + +* `Jabber accounts` + +For testing purposes, there will be required two private jabber accounts. +For creating new account, on web are many free available servers: + +https://www.google.com/search?q=jabber+server+list + +Clients testing runner +---------------------- + +Outside of project location we should create testing script to get fast output of our changes, with our credentials to avoid by accident send these for example to git repository. + +At mine device I created at path `'/usr/bin'` file named `'test_slixmpp'` and let this file access to execute: + +.. code-block:: bash + + /usr/bin $ chmod 711 test_slixmpp + +This file contain: + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal + #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about rights to run your python files. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + +The `'subprocess.run()'` is compatybile with Python 3.5+. So if backward compatybility is needed, replace this with `'call'` method and adjust properly. + +At next point I write there my credentials, get paths from `'sys.argv[...]'` or `'os.getcwd()'`, get parameter to debug, quiet or default info and mock mine testing xml file. Whichever parameter is used, it should be comfortable and fast to testing scripts without refactoring script again. Before closed, make it open till proper paths to file be created (about full jid later). + +For larger manual testing application during development process there in my opinion should be used prefix with separate terminal for every client, then will be easier to find which client causes error for example. + +Create client and plugin +------------------------ + +There should be created two clients to check if everything works fine. I created `'sender'` and `'responder'` clients. There is minimal code implementation for effictive testing code when we need to build plugin: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +Next file to create is `'example_plugin.py'` with path available to import from clients. There as default I put it into that same localization as clients. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + +If it isn't it that same directory, then create symbolic link to localization reachable by clients: + +.. code-block:: bash + + ln -s $Path_to_example_plugin_py $Path_to_clients_destinations + +Otherwise import it properly with dots to get correct import path. + +First run and event handlers +---------------------------- + +To check if everything is okay, we can use start method, because right after client is ready, then event `'session_start'` should be raised. + +In `'__init__'` method are created handler for event call `'session_start'` and when it is called, then our method `'def start(self, event):'` will be exected. At first run add following line: `'logging.info("I'm running")'` to both of clients (sender and responder) and use `'test_slixmpp'` command. + +Now method `'def start(self, event):'` should look like this: + +.. code-block:: python + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + logging.info("I'm running") + #<<<<<<<<<<<< + +If everything works fine. Then we can comment this line and go to sending message at first example. + +Build message object +-------------------- + +In this tutorial section, example sender class should get recipient (jid of responder) from command line arguments, stored in test_slixmpp. Access to this argument are stored in attribute `'self.to'`. + +Code example: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Default mtype == "chat"; + msg = self.make_message(mto=to, mbody=body) + msg.send() + #<<<<<<<<<<<< + +In example below I using build-in method to make Message object with string "example_message" and I calling it right after `'start'` method. + +To receive this message, responder should have proper handler to handle signal with message object, and method to decide what to do with this message. There is example below: + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + #>>>>>>>>>>>> + self.add_event_handler("message", self.message) + #<<<<<<<<<<<< + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def message(self, msg): + #Show all inside msg + logging.info(msg) + #Show only body attribute, like dictionary access + logging.info(msg['body']) + #<<<<<<<<<<<< + +Extend message with our tags +++++++++++++++++++++++++++++ + +To extend our message object with specified tag with specified fields, our plugin should be registred as extension for message object: + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + #<<<<<<<<<<<< + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + #>>>>>>>>>>>> + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + #<<<<<<<<<<<< + +Now with registred object we can extend our message. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Default mtype == "chat"; + msg = self.make_message(mto=to, mbody=body) + #>>>>>>>>>>>> + msg['example_tag'].set_some_string("Work!") + logging.info(msg) + #<<<<<<<<<<<< + msg.send() + +Now after running, following message from logging should show `'example_tag'` included inside with our string, and namespace. + +Catch extended message with different event handler ++++++++++++++++++++++++++++++++++++++++++++++++++++ + +To get difference between extended messages and basic messages (or Iq), we can register handler for our namespace and tag to make unique combination and handle only these required messages. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + +StanzaPath object should be initialized in proper way, this is as follows: +`'OBJECT_NAME[@type=TYPE_OF_OBJECT][/{NAMESPACE}[TAG]]'` + +* For OBJECT_NAME we can use `'message'` or `'iq'`. +* For TYPE_OF_OBJECT if we specify iq, we can precise `'get, set, error or result'` +* For NAMESPACE it always should be namespace from our tag extension class. +* For TAG it should contain our tag, `'example_tag'` in this case. + +Now we catching all types of message with proper namespace inside `'example_tag'`, there we can do something with this message before we send this message stright to client with our own "example_tag_message" event. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message", "example_string") + + def send_example_message(self, to, body, some_string=""): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Default mtype == "chat"; + msg = self.make_message(mto=to, mbody=body) + if some_string: + msg['example_tag'].set_some_string(some_string) + msg.send() + #<<<<<<<<<<<< + +Next, remember line: `'self.xmpp.event('example_tag_message', msg)'`. + +There is event name to handle from responder `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_message", self.example_tag_message) + #<<<<<<<<<<<< + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def example_tag_message(self, msg): + logging.info(msg) # Message is standalone object, it can be replied, but no error arrives if not. + #<<<<<<<<<<<< + +There we can reply the message, but nothing will happen if we don't do this. But next object used in most cases are Iq. Iq object always should be replied if received, otherwise client had error typed reply due timeout if target of iq client don't answer this iq. + + +Useful methods and others +------------------------- + +Modify `Message` object example to `Iq`. +++++++++++++++++++++++++++++++++++++++++ + +To adjust example from Message object to Iq object, needed is to register new handler for iq like with message at chapter `,,Extend message with our tags''`. This time example contains several types with separate types to catch, this is useful to get difference between received iq request and iq response. Because all Iq messages should be repeated with that same ID to sender with response, otherwise sender get back iq with timeout error. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + #<<<<<<<<<<<< + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + #>>>>>>>>>>>> + # All iq types are: get, set, error, result + def __handle_get_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_result_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + #<<<<<<<<<<<< + +Events called from handlers, can be catched like with `'example_tag_message'` example. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_message", self.example_tag_message) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it call an error. + logging.info(str(iq)) + reply = iq.reply(clear=False) + reply.send() + #<<<<<<<<<<<< + +Default parameter `'clear'` for `'Iq.reply'` is set to True, then content inside Iq object should be fulfilled, omitting ID and recipient, this information Iq holding even when `'clear'` is set to True. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + #<<<<<<<<<<<< + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.send_example_iq(self.to) + # Info_inside_tag + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" + iq['example_tag']['some_string'] = "Another_string" + iq['example_tag'].text = "Info_inside_tag" + iq.send() + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + + def example_tag_error_iq(self, iq): + logging.info(str(iq)) + #<<<<<<<<<<<< + +Ways to access elements ++++++++++++++++++++++++ + +To access elements inside Message or Iq stanza are several ways, at first from clients is like access to dictionary: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + #... + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + #>>>>>>>>>>>> + logging.info(iq['id']) + logging.info(iq.get('id')) + logging.info(iq['example_tag']['boolean']) + logging.info(iq['example_tag'].get('boolean')) + logging.info(iq.get('example_tag').get('boolean')) + #<<<<<<<<<<<< + +From ExampleTag extension, access to elements is similar there is example getter and setter for specific field: + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + #>>>>>>>>>>>> + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + #<<<<<<<<<<<< + +Attribute `'self.xml'` is inherited from ElementBase and means exactly that same like `'Iq['example_tag']'` from client namespace. + +When proper setters and getters are used, then code can be cleaner and more object-like, like example below: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" + #>>>>>>>>>>>> + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + #<<<<<<<<<<<< + iq.send() + +Setup message from XML files, strings and other objects ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +To setup previously defined xml from string, from file containing this xml string or lxml (ElementTree) there are many ways to dump data. One of this is parse strings to lxml object, pass atributes and other info: + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + #... + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + #... + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + #>>>>>>>>>>>> + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + #<<<<<<<<<<<< + +To test this, we need example file with xml, example xml string and example ET object: + +.. code-block:: xml + + #File: $WORKDIR/test_example_tag.xml + + Info_inside_tag + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + #... + from slixmpp.xmlstream import ET + #... + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.disconnect_counter = 3 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + #<<<<<<<<<<<< + +If Responder return our `'Iq'` with reply, then all is okay and Sender should be disconnected. + +Dev friendly methods for plugin usage ++++++++++++++++++++++++++++++++++++++ + +Any plugin should have some sort of object-like methods, setup for our element, getters, setters and signals to make it easy for use for other developers. +During handling, data should be checked if is correct or return an error for sender. + +There is example followed by these rules: + + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + # All iq types are: get, set, error, result + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + # Do something with received iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_result_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + #There keys from dict should be also validated + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + #Some validation if it is necessary + self.set_boolean(boolean) + self.set_some_string(some_string) + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + self.add_event_handler("example_tag_message", self.example_tag_message) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it call an error. + logging.info(iq) + reply = iq.reply() + reply["example_tag"].fill_interfaces(True, "Reply_string") + reply.send() + + def example_tag_message(self, msg): + logging.info(msg) # Message is standalone object, it can be replied, but no error arrives if not. + + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 5 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + + + +Tags and strings nested inside our tag +++++++++++++++++++++++++++++++++++++++ + +To make nested element inside our IQ tag, consider our field `self.xml` as Element from ET (ElementTree). + +Adding nested element then, is just append Element to our Element. + + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + #(...) + + class ExampleTag(ElementBase): + + #(...) + + def add_inside_tag(self, tag, attributes, text=""): + #If we want to fill with additionaly tags our element, then we can do it that way for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: + itemXML.text = text #~ Fill field inside tag, for example: our_text + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + +There is way to do this with dictionary and name for nested element tag, but inside function fields should be transfered to ET element. + +Complete code from tutorial +--------------------------- + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal + #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about rights to run your python files. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + # All iq types are: get, set, error, result + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + # Do something with received iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_result_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + #There should keys should be also validated + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + #Some validation if it is necessary + self.set_boolean(boolean) + self.set_some_string(some_string) + + def add_inside_tag(self, tag, attributes, text=""): + #If we want to fill with additionaly tags our element, then we can do it that way for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: + itemXML.text = text #~ Fill field inside tag, for example: our_text + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + + +~ + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/test_example_tag.xml +.. code-block:: xml + + Info_inside_tag + + +Sources and references +---------------------- + +Slixmpp project description: + +* https://pypi.org/project/slixmpp/ + +Official web documentation: + +* https://slixmpp.readthedocs.io/ + + +Official pdf documentation: + +* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf + +Note: Web and PDF Documentation have differences and some things aren't mention in the another one (Both ways). + + -- cgit v1.2.3 From 9c4e3956a77cc5882e041f988df6e1343cb6ebdd Mon Sep 17 00:00:00 2001 From: Paulina Date: Sat, 29 Feb 2020 10:31:52 +0100 Subject: Correction and editing of the tutorials. [80 %] English version [0 %] Polish version [20 %] Both version consistency check [0 %] Final sanity check TODO: - comments in the code blocks - side-by-side consistency check --- .../make_plugin_extension_for_message_and_iq.rst | 356 ++++++++++----------- 1 file changed, 167 insertions(+), 189 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index af1fd2eb..b5680b5a 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -1,29 +1,27 @@ -How to make own slixmpp plugin for Message and IQ extension -=========================================================== +# How to make a slixmpp plugins for Messages and IQ extensions -Introduction and requirements ------------------------------ +## Introduction and requirements -* `'python3'` +- `'python3'` -Code used in tutorial is compatybile with python version 3.6+. +Code used in the following tutorial is written in python 3.6 or newer. -For backward compatybility with versions before, delete f-strings functionality and replace this with older string formatting `'"{}".format("content")'` or `'%s, "content"'`. +For backward compatibility, replace the f-strings functionality with older string formatting: `'"{}".format("content")'` or `'%s, "content"'`. -Ubuntu linux installation: +Ubuntu linux installation steps: .. code-block:: bash sudo apt-get install python3.6 -* `'slixmpp'` -* `'argparse'` -* `'logging'` -* `'subprocess'` -* `'threading'` +- `'slixmpp'` +- `'argparse'` +- `'logging'` +- `'subprocess'` +- `'threading'` -Check if these libraries and proper python version are available at your environment. -(all except slixmpp are in standard python library, this is very exceptionally situation to don't have it insalled with python) +Check if these libraries and the proper python version are available for your environment. +Every one of these, except the slixmpp, is a standard python library. To not have them installed by default is an unusual situation. .. code-block:: python @@ -34,7 +32,7 @@ Check if these libraries and proper python version are available at your environ python3 -m subprocess python3 -m threading -My output: +Example output: .. code-block:: bash @@ -49,9 +47,9 @@ My output: ~ $ python3 -m subprocess #This should return nothing ~ $ python3 -m threading #This should return nothing -If some of libraries throws `'ImportError'` or `'no module named ...'`, try to install it with following example: +If some of the libraries throw `'ImportError'` or `'no module named ...'` error, try to install them with: -Ubuntu linux installation: +On ubuntu linux: .. code-block:: bash @@ -59,33 +57,31 @@ Ubuntu linux installation: #or easy_install slixmpp -If some of libraries throws NameError, reinstall package. +If some of the libraries throws NameError, reinstall the whole package. -* `Jabber accounts` +- `Jabber accounts` -For testing purposes, there will be required two private jabber accounts. -For creating new account, on web are many free available servers: +For the testing purposes, two private jabber accounts are required. They can be created on one of many available sites, for example: -https://www.google.com/search?q=jabber+server+list +[https://www.google.com/search?q=jabber+server+list](https://www.google.com/search?q=jabber+server+list) -Clients testing runner ----------------------- +## Client launch script -Outside of project location we should create testing script to get fast output of our changes, with our credentials to avoid by accident send these for example to git repository. +The client launch script should be created outside of the main project location. This allows us to easly obtain the results when needed. It is recommended for the script to be outside of the project location in order to avoid accidental lekeage of our credencial details to the git platform. -At mine device I created at path `'/usr/bin'` file named `'test_slixmpp'` and let this file access to execute: +As the example, I created a file `'test_slixmpp'` in `'/usr/bin'` directory and give it the execute permission: .. code-block:: bash /usr/bin $ chmod 711 test_slixmpp -This file contain: +This file contains: .. code-block:: python #!/usr/bin/python3 #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - + import subprocess import threading import time @@ -94,8 +90,8 @@ This file contain: subprocess.run(shell_string, shell=True, universal_newlines=True) if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal - #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client; you can replace xterm with your terminal + #~ prefix = "xterm -e" # Separate terminal for every client; you can replace xterm with your terminal prefix = "" #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet @@ -112,10 +108,10 @@ This file contain: responder_password = "RESPONDER_PASSWORD" # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \\ " -t {responder_jid} --path {example_file} {postfix}" - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \\ " -p {responder_password} {postfix}" try: @@ -128,16 +124,16 @@ This file contain: except: print ("Error: unable to start thread") -The `'subprocess.run()'` is compatybile with Python 3.5+. So if backward compatybility is needed, replace this with `'call'` method and adjust properly. +The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatybility is needed, replace it with `'call'` method and adjust accordingly. The launch script should be convinient in use and easy to reconfigure again. We can adapt it to our needs, so it saves our time in the future. -At next point I write there my credentials, get paths from `'sys.argv[...]'` or `'os.getcwd()'`, get parameter to debug, quiet or default info and mock mine testing xml file. Whichever parameter is used, it should be comfortable and fast to testing scripts without refactoring script again. Before closed, make it open till proper paths to file be created (about full jid later). +We can define there the logging credentials, the paths derived from `'sys.argv[...]'` or `'os.getcwd()'`, set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. -For larger manual testing application during development process there in my opinion should be used prefix with separate terminal for every client, then will be easier to find which client causes error for example. +[TODO] Before closed, make it open till proper paths to file be created (about full jid later). +In case of manually testing the larger applications, it would be a good practise to introduce the unique name (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. -Create client and plugin ------------------------- +## Creating the client and the plugin -There should be created two clients to check if everything works fine. I created `'sender'` and `'responder'` clients. There is minimal code implementation for effictive testing code when we need to build plugin: +Two clients should be created in order to check if everything works correctly. I created the `'sender'` and the `'responder'` clients. The minimal amount of code needed for effective building and testing of the plugin is the following: .. code-block:: python @@ -160,12 +156,12 @@ There should be created two clients to check if everything works fine. I created self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) @@ -227,7 +223,7 @@ There should be created two clients to check if everything works fine. I created # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) @@ -267,7 +263,7 @@ There should be created two clients to check if everything works fine. I created except: pass -Next file to create is `'example_plugin.py'` with path available to import from clients. There as default I put it into that same localization as clients. +Next file to create is `'example_plugin.py'`. It can be placed in the same catalogue as the clients, so the problems with unknown paths can be avoided. .. code-block:: python @@ -292,33 +288,31 @@ Next file to create is `'example_plugin.py'` with path available to import from self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. namespace = ExampleTag.namespace - - + + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - -If it isn't it that same directory, then create symbolic link to localization reachable by clients: +If it is not in the same directory, then the symbolic link to the localisation reachable by the clients should be established: .. code-block:: bash ln -s $Path_to_example_plugin_py $Path_to_clients_destinations -Otherwise import it properly with dots to get correct import path. +The other solution is to relative import it (with the use of dots '.') to get the proper path. -First run and event handlers ----------------------------- +## First run and the event handlers -To check if everything is okay, we can use start method, because right after client is ready, then event `'session_start'` should be raised. +To check if everything is okay, we can use the start method. Right after the client is ready, the event `'session_start'` should be raised. -In `'__init__'` method are created handler for event call `'session_start'` and when it is called, then our method `'def start(self, event):'` will be exected. At first run add following line: `'logging.info("I'm running")'` to both of clients (sender and responder) and use `'test_slixmpp'` command. +In the `'__init__'` method, the handler for event call `'session_start'` is created. When it is called, the `'def start(self, event):'` method will be executed. During the first run, add the line: `'logging.info("I'm running")'` to both of the clients' code (the sender and the responder) and use `'test_slixmpp'` command. -Now method `'def start(self, event):'` should look like this: +Now, the `'def start(self, event):'` method should look like this: .. code-block:: python @@ -326,17 +320,16 @@ Now method `'def start(self, event):'` should look like this: # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> logging.info("I'm running") #<<<<<<<<<<<< -If everything works fine. Then we can comment this line and go to sending message at first example. +If everything works fine, we can comment this line out and go to the first example: sending a message. -Build message object --------------------- +## Building the message object -In this tutorial section, example sender class should get recipient (jid of responder) from command line arguments, stored in test_slixmpp. Access to this argument are stored in attribute `'self.to'`. +In this section of the tutorial, the example sender class should get a recipient (jid of responder) from command line arguments, stored in test_slixmpp. An access to this argument is stored in the `'self.to'`attribute. Code example: @@ -352,7 +345,7 @@ Code example: self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -367,9 +360,9 @@ Code example: msg.send() #<<<<<<<<<<<< -In example below I using build-in method to make Message object with string "example_message" and I calling it right after `'start'` method. +In the example below, we are using the build-in method of making the message object. It contains a string "example_message" and is called right after the `'start'` method. -To receive this message, responder should have proper handler to handle signal with message object, and method to decide what to do with this message. There is example below: +To receive this message, the responder should have a proper handler to the signal with the message object and the method to decide what to do with this message. As it is shown in the example below: .. code-block:: python @@ -384,7 +377,7 @@ To receive this message, responder should have proper handler to handle signal w #>>>>>>>>>>>> self.add_event_handler("message", self.message) #<<<<<<<<<<<< - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -398,10 +391,10 @@ To receive this message, responder should have proper handler to handle signal w logging.info(msg['body']) #<<<<<<<<<<<< -Extend message with our tags +Expanding the message with new tags ++++++++++++++++++++++++++++ -To extend our message object with specified tag with specified fields, our plugin should be registred as extension for message object: +To expand the Message object with our tag, the plugin should be registered as the extension for the Message object: .. code-block:: python @@ -416,15 +409,15 @@ To extend our message object with specified tag with specified fields, our plugi #>>>>>>>>>>>> register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. #<<<<<<<<<<<< - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - + #>>>>>>>>>>>> def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) @@ -433,7 +426,7 @@ To extend our message object with specified tag with specified fields, our plugi self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< -Now with registred object we can extend our message. +Now with the registered object, the message can be extended. .. code-block:: python @@ -447,7 +440,7 @@ Now with registred object we can extend our message. self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -464,12 +457,12 @@ Now with registred object we can extend our message. #<<<<<<<<<<<< msg.send() -Now after running, following message from logging should show `'example_tag'` included inside with our string, and namespace. +After running, the following message from the logging should show the `'example_tag'` stored inside with string and namespace defined previously by us. -Catch extended message with different event handler +Catching the extended message with different event handler +++++++++++++++++++++++++++++++++++++++++++++++++++ -To get difference between extended messages and basic messages (or Iq), we can register handler for our namespace and tag to make unique combination and handle only these required messages. +To get the difference between the extended messages and basic messages (or Iq), we can register the handler for the new namespace and tag. Then, make a unique name combination and handle only these required messages. .. code-block:: python @@ -487,20 +480,20 @@ To get difference between extended messages and basic messages (or Iq), we can r StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - + def __handle_message(self, msg): # Do something with received message self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. -StanzaPath object should be initialized in proper way, this is as follows: +StanzaPath objects should be initialized in a specific way, such as: `'OBJECT_NAME[@type=TYPE_OF_OBJECT][/{NAMESPACE}[TAG]]'` -* For OBJECT_NAME we can use `'message'` or `'iq'`. -* For TYPE_OF_OBJECT if we specify iq, we can precise `'get, set, error or result'` -* For NAMESPACE it always should be namespace from our tag extension class. -* For TAG it should contain our tag, `'example_tag'` in this case. +- For OBJECT_NAME we can use `'message'` or `'iq'`. +- For TYPE_OF_OBJECT, if we specify iq, we can use`'get, set, error or result'` +- NAMESPACE should always be a namespace from our tag extension class. +- TAG should contain our tag, in this case:`'example_tag'`. -Now we catching all types of message with proper namespace inside `'example_tag'`, there we can do something with this message before we send this message stright to client with our own "example_tag_message" event. +Now we are catching every message containing our namespace inside the `'example_tag'`field. We can check the content of it and then send it to the client with `'example_tag_message'` event. .. code-block:: python @@ -514,7 +507,7 @@ Now we catching all types of message with proper namespace inside `'example_tag' self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -533,7 +526,7 @@ Now we catching all types of message with proper namespace inside `'example_tag' Next, remember line: `'self.xmpp.event('example_tag_message', msg)'`. -There is event name to handle from responder `'example_tag_message'`. +There is a responder event handler that uses the`'example_tag_message'`. .. code-block:: python @@ -547,7 +540,7 @@ There is event name to handle from responder `'example_tag_message'`. #>>>>>>>>>>>> self.add_event_handler("example_tag_message", self.example_tag_message) #<<<<<<<<<<<< - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -558,16 +551,14 @@ There is event name to handle from responder `'example_tag_message'`. logging.info(msg) # Message is standalone object, it can be replied, but no error arrives if not. #<<<<<<<<<<<< -There we can reply the message, but nothing will happen if we don't do this. But next object used in most cases are Iq. Iq object always should be replied if received, otherwise client had error typed reply due timeout if target of iq client don't answer this iq. - +We can reply to the messages, but nothing will happen if we don't. However, when we receive the Iq object, we should always reply. Otherwise, the error reply occurs on the client side due to the target timeout. -Useful methods and others -------------------------- +## Useful methods and others -Modify `Message` object example to `Iq`. +Modifying the `Message` object example to `Iq` object. ++++++++++++++++++++++++++++++++++++++++ -To adjust example from Message object to Iq object, needed is to register new handler for iq like with message at chapter `,,Extend message with our tags''`. This time example contains several types with separate types to catch, this is useful to get difference between received iq request and iq response. Because all Iq messages should be repeated with that same ID to sender with response, otherwise sender get back iq with timeout error. +To convert the Message to the Iq object, we need to register a new handler for the Iq. We can do it in the same maner as in the `,,Extend message with our tags''`part. The following example contains several types of Iq [TODO with separate types to catch]. We can use it to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be pass on to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. .. code-block:: python @@ -623,8 +614,8 @@ To adjust example from Message object to Iq object, needed is to register new ha self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. #<<<<<<<<<<<< -Events called from handlers, can be catched like with `'example_tag_message'` example. - +The events called from the handlers, can be caught like in the`'example_tag_message'` example. + .. code-block:: python #File: $WORKDIR/example/responder.py @@ -646,7 +637,7 @@ Events called from handlers, can be catched like with `'example_tag_message'` ex reply.send() #<<<<<<<<<<<< -Default parameter `'clear'` for `'Iq.reply'` is set to True, then content inside Iq object should be fulfilled, omitting ID and recipient, this information Iq holding even when `'clear'` is set to True. +By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that case, the content of the Iq should be set again. After using the reply method, only the Id and the Jid parameters will stillbe set. .. code-block:: python @@ -669,10 +660,10 @@ Default parameter `'clear'` for `'Iq.reply'` is set to True, then content inside # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag #<<<<<<<<<<<< #>>>>>>>>>>>> @@ -693,10 +684,10 @@ Default parameter `'clear'` for `'Iq.reply'` is set to True, then content inside logging.info(str(iq)) #<<<<<<<<<<<< -Ways to access elements +Different ways to access the elements +++++++++++++++++++++++ -To access elements inside Message or Iq stanza are several ways, at first from clients is like access to dictionary: +There are several ways to access the elements inside the Message or Iq stanza. The first one, from the client's side, is simply accessing the dictionary: .. code-block:: python @@ -714,15 +705,15 @@ To access elements inside Message or Iq stanza are several ways, at first from c logging.info(iq.get('example_tag').get('boolean')) #<<<<<<<<<<<< -From ExampleTag extension, access to elements is similar there is example getter and setter for specific field: +For the ExampleTag extension, there is a getter and setter method for specific fields: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -742,9 +733,9 @@ From ExampleTag extension, access to elements is similar there is example getter self.xml.text = text #<<<<<<<<<<<< -Attribute `'self.xml'` is inherited from ElementBase and means exactly that same like `'Iq['example_tag']'` from client namespace. +The attribute `'self.xml'` is inherited from the ElementBase and is exactly the same as the `'Iq['example_tag']'` from the client namespace. -When proper setters and getters are used, then code can be cleaner and more object-like, like example below: +When the proper setters and getters are used, then the code can be cleaner and more object-oriented, like in the example below: .. code-block:: python @@ -771,22 +762,22 @@ When proper setters and getters are used, then code can be cleaner and more obje #<<<<<<<<<<<< iq.send() -Setup message from XML files, strings and other objects +Message setup from the XML files, strings and other objects +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -To setup previously defined xml from string, from file containing this xml string or lxml (ElementTree) there are many ways to dump data. One of this is parse strings to lxml object, pass atributes and other info: +There are many ways set up a xml from a string, xml-containing file or lxml (ElementTree) file. One of them is parsing the strings to lxml object, passing the attributes and other information, which may look like this: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + #... from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin #... - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -812,22 +803,22 @@ To setup previously defined xml from string, from file containing this xml strin self.xml.append(inner_tag) #<<<<<<<<<<<< -To test this, we need example file with xml, example xml string and example ET object: +To test this, we need an example file with xml, example xml string and example ET object: .. code-block:: xml #File: $WORKDIR/test_example_tag.xml - - Info_inside_tag + + Info_inside_tag .. code-block:: python #File: $WORKDIR/example/sender.py - + #... from slixmpp.xmlstream import ET #... - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) @@ -848,16 +839,16 @@ To test this, we need example file with xml, example xml string and example ET o self.disconnect_counter = 3 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - + # Info_inside_tag + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) @@ -886,23 +877,22 @@ To test this, we need example file with xml, example xml string and example ET o iq.send() #<<<<<<<<<<<< -If Responder return our `'Iq'` with reply, then all is okay and Sender should be disconnected. +If the Responder returns the proper `'Iq'` in the reply, then everything went okay and the Sender can be disconnected. Dev friendly methods for plugin usage +++++++++++++++++++++++++++++++++++++ -Any plugin should have some sort of object-like methods, setup for our element, getters, setters and signals to make it easy for use for other developers. -During handling, data should be checked if is correct or return an error for sender. - -There is example followed by these rules: +Any plugin should have some sort of object-like methods, setup for our elements: getters, setters and signals to make it easy to use. +During handling, the correctness of the data should be checked and the eventual errors returned to the sender. +The following code presents exactly this: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin from slixmpp import Iq @@ -969,7 +959,7 @@ There is example followed by these rules: class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -992,7 +982,7 @@ There is example followed by these rules: self.xml.tail = lxml.tail for inner_tag in lxml: self.xml.append(inner_tag) - + def setup_from_dict(self, data): #There keys from dict should be also validated self.xml.attrib.update(data) @@ -1023,7 +1013,7 @@ There is example followed by these rules: .. code-block:: python #File: $WORKDIR/example/responder.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1092,11 +1082,11 @@ There is example followed by these rules: xmpp.disconnect() except: pass - + .. code-block:: python #File: $WORKDIR/example/sender.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1126,26 +1116,26 @@ There is example followed by these rules: self.disconnect_counter = 5 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1243,21 +1233,16 @@ There is example followed by these rules: xmpp.disconnect() except: pass - - Tags and strings nested inside our tag ++++++++++++++++++++++++++++++++++++++ -To make nested element inside our IQ tag, consider our field `self.xml` as Element from ET (ElementTree). +To make the nested element inside our IQ tag, we need to consider `self.xml` field as an Element from ET (ElementTree). So, adding the nested elements is just appending the Element. -Adding nested element then, is just append Element to our Element. - - .. code-block:: python #File: $WORKDIR/example/example_plugin.py - + #(...) class ExampleTag(ElementBase): @@ -1266,18 +1251,17 @@ Adding nested element then, is just append Element to our Element. def add_inside_tag(self, tag, attributes, text=""): #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. -There is way to do this with dictionary and name for nested element tag, but inside function fields should be transfered to ET element. +There is a way to do this with a dictionary and name for the nested element tag. In that case, the insides of the function fields should be transferred to the ET element. -Complete code from tutorial ---------------------------- +## Complete code from tutorial .. code-block:: python - + #!/usr/bin/python3 #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) @@ -1307,10 +1291,10 @@ Complete code from tutorial responder_password = "RESPONDER_PASSWORD" # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \\ " -t {responder_jid} --path {example_file} {postfix}" - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \\ " -p {responder_password} {postfix}" try: @@ -1323,11 +1307,10 @@ Complete code from tutorial except: print ("Error: unable to start thread") - .. code-block:: python #File: $WORKDIR/example/example_plugin.py - + import logging from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin @@ -1396,7 +1379,7 @@ Complete code from tutorial class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -1449,11 +1432,10 @@ Complete code from tutorial def add_inside_tag(self, tag, attributes, text=""): #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. - ~ @@ -1490,29 +1472,29 @@ Complete code from tutorial self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1627,7 +1609,7 @@ Complete code from tutorial .. code-block:: python #File: $WORKDIR/example/responder.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1657,29 +1639,29 @@ Complete code from tutorial self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1794,27 +1776,23 @@ Complete code from tutorial .. code-block:: python #File: $WORKDIR/test_example_tag.xml -.. code-block:: xml - Info_inside_tag +.. code-block:: xml + Info_inside_tag -Sources and references ----------------------- +## Sources and references -Slixmpp project description: +The Slixmpp project description: -* https://pypi.org/project/slixmpp/ +- [https://pypi.org/project/slixmpp/](https://pypi.org/project/slixmpp/) Official web documentation: -* https://slixmpp.readthedocs.io/ - +- [https://slixmpp.readthedocs.io/](https://slixmpp.readthedocs.io/) Official pdf documentation: -* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf - -Note: Web and PDF Documentation have differences and some things aren't mention in the another one (Both ways). - +- [https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf](https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf) +Note: Web and PDF Documentations have differences and some things are mentioned in only one of them. -- cgit v1.2.3 From 01371041a3f0011495a0fe7d25ab6936d7f23af6 Mon Sep 17 00:00:00 2001 From: Paulina Date: Sun, 8 Mar 2020 11:23:31 +0100 Subject: Correction and editing of the tutorials. [85 %] English version [90 %] Polish version [45 %] Both version consistency check [0 %] Final sanity check + formating --- docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst | 169 ++++++++++----------- .../make_plugin_extension_for_message_and_iq.rst | 137 +++++++++-------- 2 files changed, 154 insertions(+), 152 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst index a679f62c..ff6cd0b9 100644 --- a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst +++ b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst @@ -6,9 +6,8 @@ Wstęp i wymagania * `'python3'` -Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6+. - -Dla wstecznej kompatybilności z wcześniejszymi wersjami, wystarczy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. +Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6 lub nowszej. +Dla wstecznej kompatybilności z wcześniejszymi wersjami należy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. Instalacja dla Ubuntu linux: @@ -16,14 +15,13 @@ Instalacja dla Ubuntu linux: sudo apt-get install python3.6 -* `'slixmpp'` +* `'slixmpp'` * `'argparse'` * `'logging'` * `'subprocess'` * `'threading'` -Sprawdź czy powyżej wymienione bibliteki są dostępne w twoim środowisku wykonawczym. (Wszystkie z wyjątkiem slixmpp są w standardowej bibliotece pythona, jednak czasem kompilując źródła samodzielnie, część ze standardowych bibliotek może nie być zainstalowana z pythonem. - +Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdaża się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. .. code-block:: python @@ -34,7 +32,7 @@ Sprawdź czy powyżej wymienione bibliteki są dostępne w twoim środowisku wyk python3 -m subprocess python3 -m threading -Mój wynik komend: +Wynik w terminalu: .. code-block:: bash @@ -46,12 +44,12 @@ Mój wynik komend: 1.1 ~ $ python3 -c "import logging; print(logging.__version__)" 0.5.1.2 - ~ $ python3 -m subprocess #To nie powinno nic zwrócić - ~ $ python3 -m threading #To nie powinno nic zwrócić + ~ $ python3 -m subprocess # Nie powinno nic zwrócić + ~ $ python3 -m threading # Nie powinno nic zwrócić -Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, dla potrzeb tutorialu powinny zostać zainstalowane jak na przykładzie poniżej: +Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, należy je zainstalować zgodnie z przykładem poniżej: -Instalacja na Ubuntu linux: +Instalacja Ubuntu linux: .. code-block:: bash @@ -59,27 +57,27 @@ Instalacja na Ubuntu linux: #or easy_install slixmpp -Jeśli jakaś biblioteka zwróci NameError, zainstaluj pakiet ponownie. +Jeśli jakaś biblioteka zwróci NameError, należy zainstalować pakiet ponownie. * `Konta dla Jabber` -Do testowania, na potrzeby tutorialu będą niezbędne dwa prywatne konta jabbera. -Aby stworzyć nowe konto, w sieci istnieje dużo dostępnych darmowych serwerów: +Do testowania niezbędne będą dwa prywatne konta jabbera. +Można je stworzyć na jednym z dostępnych darmowych serwerów: https://www.google.com/search?q=jabber+server+list Skrypt uruchamiający klientów ----------------------------- -Poza lokalizacją projektu, powinniśmy stworzyć skrypt uruchamiający klientów testowo aby szybko móc sprawdzić czy rezultat jest prawidłowy. Ważne aby skrypt był poza projektem aby na przykład uniknąć przypadkowego wysłania na platformę gita swoich danych logowania. +Skrypt pozwalający testować klientów powinien zostać stworzony poza lokalizacją projektu. Pozwoli to szybko sprawdzać wyniki skryptów oraz uniemożliwi przypadkowe wysłanie swoich danych na gita. -Na moim urządzeniu stworzyłem w ścieżce `'/usr/bin'` plik o nazwie `'test_slixmpp'` i dodałem uprawnienia do wykonywania go: +Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/usr/bin'` i nadać mu uprawnienia wykonywawcze: .. code-block:: bash /usr/bin $ chmod 711 test_slixmpp -Ten plik w tej formie powinniśmy móc edytować i czytać wyłącznie z uprawnieniami superuser. Plik zawiera prostą strukturę która pozwoli nam zapisać swoje dane logowania. +Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawiera prostą strukturę, która pozwoli nam zapisać dane logowania. .. code-block:: python @@ -95,7 +93,7 @@ Ten plik w tej formie powinniśmy móc edytować i czytać wyłącznie z uprawni if __name__ == "__main__": #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala - #~ prefix = "xterm -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala + #~ prefix = "xterm -e" prefix = "" #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet @@ -111,7 +109,7 @@ Ten plik w tej formie powinniśmy móc edytować i czytać wyłącznie z uprawni responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - # Remember about rights to run your python files. (`chmod +x ./file.py`) + # Pamiętaj o nadaniu praw do wykonywania (`chmod +x ./file.py`) SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" @@ -128,16 +126,16 @@ Ten plik w tej formie powinniśmy móc edytować i czytać wyłącznie z uprawni except: print ("Error: unable to start thread") -Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Więc dla jeszcze wcześniejszej kompatybilności można dopasować argumenty i podmienić na metodę `'subprocess.call()'`. +Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. -Skrypt uruchomieniowy powinien być dopasowany do naszych potrzeb, można pobierać ścieżki do projektu z linii komend, wybierać z jaką flagą mają zostać uruchomione programy i wiele innych rzeczy które będą nam potrzebne. W tym punkcie musimy dostosować skrypt do swoich potrzeb co zaoszczędzi nam masę czasu w trakcie pracy. +Skrypt uruchomieniowy powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. -Dla testowania większych aplikacji podczas tworzenia pluginu, w mojej opinii szczególnie użyteczne są osobne linie poleceń dla każdego klienta aby zachować czytelność który i co zwraca, bądź który powoduje błąd. +W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko okreslić, który klient co zwraca, bądź który powoduje błąd. Stworzenie klienta i pluginu ---------------------------- -W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. I stworzyłem klientów: `'sender'` i `'responder'`. Poniżej minimalna implementacja dla efektywnego testowania gdzie będziemy testować nasz plugin w trakcie jego projektowania: +W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: .. code-block:: python @@ -162,7 +160,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby s self.add_event_handler("session_start", self.start) def start(self, event): - # Dwie niewymagane metody, pozwalające innym użytkownikom zobaczyć że jesteśmy online i wyświetlić tą informację + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostepność online. self.send_presence() self.get_roster() @@ -196,8 +194,8 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby s args.password = getpass("Password: ") xmpp = Sender(args.jid, args.password, args.to, args.path) - #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy naszego example_plugin - + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin. + xmpp.connect() try: xmpp.process() @@ -224,7 +222,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby s self.add_event_handler("session_start", self.start) def start(self, event): - # Dwie niewymagane metody, pozwalające innym użytkownikom zobaczyć że jesteśmy online i wyświetlić tą informację + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online self.send_presence() self.get_roster() @@ -256,7 +254,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby s args.password = getpass("Password: ") xmpp = Responder(args.jid, args.password) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy naszego example_plugin + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin xmpp.connect() try: @@ -267,7 +265,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp, aby s except: pass -Następny plik który powinniśmy stworzyć to `'example_plugin'` ze ścieżką dostępną dla importu z poziomu klientów. Domyślnie umieszczam w tej samej lokalizacji co klientów. +Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w lokalizacji dostepnej dla klientów (domyślnie w tej samej, co skrypty klientów). .. code-block:: python @@ -289,38 +287,40 @@ Następny plik który powinniśmy stworzyć to `'example_plugin'` ze ścieżką class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin - self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin dodając to do `slixmpp/plugins/__init__.py` do pola `__all__` z prefixem xep 'xep_OPE'. W innym wypadku jest to tylko notka czytelna dla ludzi + self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin poprzez dodanie tego do `slixmpp/plugins/__init__.py`, w polu `__all__` z prefixem xep 'xep_OPE'. namespace = ExampleTag.namespace class ExampleTag(ElementBase): - name = "example_tag" ##~ Nazwa naszego głównego taga dla XML w tym rozszerzeniu. - namespace = "https://example.net/our_extension" ##~ Namespace dla naszego obiektu jest definiowana w tym miejscu, powinna się odnosić do naszego portalu, w wiadomości wygląda tak: + name = "example_tag" ##~ Nazwa głównego tagu dla XML w tym rozszerzeniu. + namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: - plugin_attrib = "example_tag" ##~ Nazwa pod którą będziemy odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo, tutaj rejestrujemy nazwę naszego obiektu by móc się do niego odwoływać z zewnątrz. Będziemy mogli się do niego odwoływać na przykład jak do słownika: stanza_object['example_tag']. `'example_tag'` staje się naszą nazwą pluginu i powinno być takie samo jak name. + plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` staje się nazwą pluginu i powinno być takie samo jak name. - interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów naszego elementu które mogą być użyte w naszym elemencie. Na przykład `stanza_object['example_tag']` poda nam informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest nazwą naszego elementu. + interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów elementu które mogą być użyte w elemencie. Na przykład `stanza_object['example_tag']` poda informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest elementu. + +Jeżeli powyższy plugin nie jest w domyślnej lokalizacji, a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu: -Jeżeli powyższy plugin nie jest w naszej lokalizacji a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu aby był dostępny z poziomu klientów: .. code-block:: bash ln -s $Path_to_example_plugin_py $Path_to_clients_destinations -Jeszcze innym wyjściem jest import relatywny z użyciem kropek aby dostać się do właściwej ścieżki. +Jeszcze innym wyjściem jest import relatywny z użyciem kropek '.' aby dostać się do właściwej ścieżki. Pierwsze uruchomienie i przechwytywanie eventów ----------------------------------------------- -Aby sprawdzić czy wszystko działa prawidłowo, możemy użyć metody `'start'`, ponieważ przypiszemy do niego event `'session_start'`, ten sygnał zostanie wywołany zaraz po tym gdy klient będzie gotów do działania, a własna metoda pozwoli nam zdefiniować odpowiednią czynność dla tego sygnału. +Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisany event `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. -W metodzie `'__init__'` tworzymy przekierowanie dla wywołania eventu `'session_start'` i kiedy zostanie wywołany, nasza metoda `'def start(self, event):'` będzie wykonana. Na pierwszy krok, dodajmy linię `'logging.info("I'm running")'` dla obu klientów (sender i responder) i użyjmy naszej komendy `'test_slixmpp'`. +W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a nastepnie użyć komendy `'test_slixmpp'`. -Teraz metoda `'def start(self, event):'` powinna wyglądać tak: +Metoda `'def start(self, event):'` powinna wyglądać tak: .. code-block:: python def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() @@ -328,13 +328,14 @@ Teraz metoda `'def start(self, event):'` powinna wyglądać tak: logging.info("I'm running") #<<<<<<<<<<<< -Jeśli oba klienty uruchomiły się poprawnie, możemy zakomentować te linię i wysłać naszą pierwszą wiadomość z pomocą następnego rozdziału. +Jeżeli oba klienty uruchomiły się poprawnie, można zakomentować tą linię. -Budowanie obiektu Message +Budowanie obiektu Message ------------------------- -W tym rozdziale, wysyłający powinien dostać informację do kogo należy wysłać wiadomość z linii komend za pomocą naszego skryptu testowego. -W poniższym przykładzie, dostęp do tej informacji mamy za pośrednictwem atrybutu `'selt.to'`: +Wysyłający powinien posiadać informację o tym, do kogo należy wysłać wiadomość. Nazwę i scieżkę odbiorcy można przekazać, na przykład, przez argumenty wywołania skryptu w lini komend. W poniższym przykładzie, są one trzymane w atrybucie `'self.to'`. + +Przykład: .. code-block:: python @@ -350,6 +351,7 @@ W poniższym przykładzie, dostęp do tej informacji mamy za pośrednictwem atry self.add_event_handler("session_start", self.start) def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> @@ -362,10 +364,9 @@ W poniższym przykładzie, dostęp do tej informacji mamy za pośrednictwem atry msg.send() #<<<<<<<<<<<< -W przykładzie, używamy wbudowanej metody `'make_message'` która tworzy dla nas wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli wyśle ją raz, zaraz po uruchomieniu. +W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. -Aby otrzymać tą wiadomość, responder powinien wykorzystać odpowiedni event którego wywołanie jest wbudowane. Ta metoda decyduje co zrobić gdy dotrze do nas wiadomość której nie został przypisany inny event (na przykład naszej rozszerzonej w dalszej części) oraz posiada treść. -Przykład kodu: +Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie został przypisany żaden inny event. Przykład takiego kodu: .. code-block:: python @@ -382,17 +383,18 @@ Przykład kodu: #<<<<<<<<<<<< def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> def message(self, msg): - #Pokazuje cały XML naszej wiadomości + #Pokazuje cały XML wiadomości logging.info(msg) - #Pokazuje wyłącznie pole 'body' wiadomości, podobnie jak dostęp do słownika + #Pokazuje wyłącznie pole 'body' wiadomości logging.info(msg['body']) #<<<<<<<<<<<< - +//TODO from here Rozszerzenie Message o nasz tag +++++++++++++++++++++++++++++++ @@ -404,12 +406,12 @@ Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin pow class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" + self.description = "OurPluginExtension" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py`, do metody `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message, w innym wypadku message['example_tag'] będzie polem napisowym, zamiast rozszerzeniem które będzie mogło zawierać swoje atrybuty i pod-elementy. + register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. #<<<<<<<<<<<< class ExampleTag(ElementBase): @@ -428,7 +430,7 @@ Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin pow self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< -Teraz dzięki rejestracji tagu, możemy rozszerzyć naszą wiadomość. +Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. .. code-block:: python @@ -456,12 +458,12 @@ Teraz dzięki rejestracji tagu, możemy rozszerzyć naszą wiadomość. #<<<<<<<<<<<< msg.send() -Teraz po uruchomieniu, logging powinien pokazać nam Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z naszym napisem `'Work'` oraz nadanym namespace. +Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z napisem `'Work'` oraz nadanym namespace. Nadanie oddzielnego sygnału dla rozszerzonej wiadomości +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Jeśli nie sprecyzujemy swojego eventu, zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, musimy zarejestrować odpowiedni handler dla naszego namespace oraz tagu aby stworzyć unikalną kombinację, która pozwoli nam przechwycić wyłącznie pożądane wiadomości (lub Iq object). +Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). .. code-block:: python @@ -487,16 +489,16 @@ Jeśli nie sprecyzujemy swojego eventu, zarówno rozszerzona jak i podstawowa wi self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. #<<<<<<<<<<<< -Obiekt StanzaPath powinien być poprawnie zainicjalizowany, oto schemat aby zrobić to poprawnie: +Obiekt StanzaPath powinien być poprawnie zainicjalizowany, według schematu: `'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` -* Dla NAZWA_OBIEKTU możemy użyć `'message'` lub `'iq'`. -* Dla TYP_OBIEKTU jeśli obiektem jest message, możemy sprecyzować typ dla message, np. `'chat'` -* Dla TYP_OBIEKTU jeśli obiektem jest iq, możemy sprecyzować typ spośród: `'get, set, error or result'` -* Dla NAMESPACE zawsze to powinien być namespace z naszego rozszerzenia tagu. -* Dla TAG powinno zawierać nasz tag, `'example_tag'` w tym przypadku. +* Dla NAZWA_OBIEKTU można użyć `'message'` lub `'iq'`. +* Dla TYP_OBIEKTU, jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'` +* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można sprecyzować typ spośród: `'get, set, error or result'` +* Dla NAMESPACE to powinien być namespace zgodny z rozszerzeniem tagu. +* TAG powinien zawierać tag, tutaj: `'example_tag'`. -Teraz, przechwytujemy wszystkie message które zawierają nasz namespace wewnątrz `'example_tag'`, możemy jak w programowaniu agentowym sprawdzić co zawiera, czy na pewno posiada wymagane pola itd. przed wysłaniem do klienta za pośrednictwem eventu `'example_tag_message'`. +Teraz, rogram przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też, jak w programowaniu agentowym, sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomośc jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. .. code-block:: python @@ -524,9 +526,7 @@ Teraz, przechwytujemy wszystkie message które zawierają nasz namespace wewnąt msg.send() #<<<<<<<<<<<< -Powinniśmy zapamiętać linię z naszego pluginu: `'self.xmpp.event('example_tag_message', msg)'` - -W tej linii zdefiniowaliśmy nazwę eventu aby go przechwycić wewnątrz pliku responder.py. Jest nim `'example_tag_message'`. +Należy zapamiętać linię pluginu: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku responder.py. Tutaj: `'example_tag_message'`. .. code-block:: python @@ -547,10 +547,11 @@ W tej linii zdefiniowaliśmy nazwę eventu aby go przechwycić wewnątrz pliku r #>>>>>>>>>>>> def example_tag_message(self, msg): - logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq już tak) + logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq jest inaczej). #<<<<<<<<<<<< -Teraz możemy odesłać wiadomość, ale nic się nie stanie jeśli tego nie zrobimy. Natomiast kolejny obiekt do komunikacji (Iq) wymaga odpowiedzi jeśli został wysłany, więc obydwaj klienci powinni być online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cel Iq nie odpowie za pomocą Iq o tym samym Id. +Teraz można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. +Natomiast kolejny obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. Użyteczne metody i inne ----------------------- @@ -558,7 +559,7 @@ Użyteczne metody i inne Modyfikacja przykładowego obiektu `Message` na `Iq`. ++++++++++++++++++++++++++++++++++++++++++++++++++++ -Aby przerobić przykładowy obiekt Message na obiekt Iq, musimy zarejestrować nowy handler dla Iq podobnie jak dla wiadomości w rozdziale `,,Rozszerzenie Message o nasz tag''`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami, jest to użyteczne aby kod był czytelny, oraz odpowiednia weryfikacja lub działanie zostało podjęte pomijając sprawdzanie typu. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią, inaczej wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). Dlatego jest to bardziej wymiana informacji pomiędzy maszynami niż ludźmi którzy mogą zareagować zbyt wolno i stracić szansę na odpowiedź. +Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o nasz tag"`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami. Poprawia to czytelność kodu oraz weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). .. code-block:: python @@ -611,7 +612,7 @@ Aby przerobić przykładowy obiekt Message na obiekt Iq, musimy zarejestrować n def __handle_message(self, msg): self.xmpp.event('example_tag_message', msg) -Eventy wywołane przez powyższe handlery, mogą zostać przechwycone jak w przypadku eventu `'example_tag_message'`. +Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. .. code-block:: python @@ -628,13 +629,13 @@ Eventy wywołane przez powyższe handlery, mogą zostać przechwycone jak w przy #<<<<<<<<<<<< #>>>>>>>>>>>> - def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem że odbiorca jest offline. + def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem. logging.info(str(iq)) reply = iq.reply(clear=False) reply.send() #<<<<<<<<<<<< -Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True, wtedy to co jest zawarte wewnątrz Iq (z kilkoma wyjątkami) powinno zostać zdefiniowane ponownie. Jedyne informacje które zostaną w Iq po metodzie reply, nawet gdy parametr clean jest ustawiony na True, to ID tego Iq oraz JID wysyłającego. +Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, co jest zawarte wewnątrz Iq (z kilkoma wyjątkami) powinno zostać zdefiniowane ponownie. Jedyne informacje które zostaną w Iq po metodzie reply, nawet gdy parametr clean jest ustawiony na True, to ID tego Iq oraz JID wysyłającego. .. code-block:: python @@ -683,7 +684,7 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True, wtedy to Dostęp do elementów +++++++++++++++++++ -Aby dostać się do pól wewnątrz Message lub Iq, jest kilka możliwości. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: +Jest kilka możliwości dostania się do pól wewnątrz Message lub Iq. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: .. code-block:: python @@ -701,7 +702,7 @@ Aby dostać się do pól wewnątrz Message lub Iq, jest kilka możliwości. Po p logging.info(iq.get('example_tag').get('boolean')) #<<<<<<<<<<<< -Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że nie musimy już precyzować tagu którego dotyczy. Dodatkową zaletą jest fakt niejednolitego dostępu, na przykład do parametru `'text'` między rozpoczęciem a zakończeniem tagu, co obrazuje poniższy przykład, ujednolicając metody do obiektowych getterów i setterów. +Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wymagane jest określanie tagu, którego dotyczy. Dodatkową zaletą jest fakt niejednolitego dostępu, na przykład do parametru `'text'` między rozpoczęciem a zakończeniem tagu. Pokazuje to poniższy przykład, ujednolicając metody obiektowych getterów i setterów. .. code-block:: python @@ -731,7 +732,7 @@ Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że nie musi Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. -Kiedy odpowiednie gettery i settery są stworzone, umożliwia sprawdzenie czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: +Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo, kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: .. code-block:: python @@ -760,7 +761,7 @@ Kiedy odpowiednie gettery i settery są stworzone, umożliwia sprawdzenie czy na Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Żeby wczytać wcześniej zdefiniowany napis, z pliku albo lxml (ElementTree) jest dużo możliwości, tutaj pokażę przykład wykorzystując parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. +Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. .. code-block:: python @@ -798,7 +799,7 @@ Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiekt self.xml.append(inner_tag) #<<<<<<<<<<<< -Do przetestowania tej funkcjonalności, będziemy potrzebować pliku zawierającego xml z naszym tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): +Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): .. code-block:: xml @@ -830,7 +831,7 @@ Do przetestowania tej funkcjonalności, będziemy potrzebować pliku zawierając self.get_roster() #>>>>>>>>>>>> - self.disconnect_counter = 3 # Ta zmienna jest tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. + self.disconnect_counter = 3 # Ta zmienna służy tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag @@ -868,13 +869,13 @@ Do przetestowania tej funkcjonalności, będziemy potrzebować pliku zawierając iq.send() #<<<<<<<<<<<< -Jeśli Responder zwróci nasze wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa jak powinno. +Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa tak, jak powinno. Łatwość użycia pluginu dla programistów +++++++++++++++++++++++++++++++++++++++ -Każdy plugin powinien posiadać pewne obiektowe metody, wczytanie danych jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. -Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego, aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, zamiast tego wysyłający dostaje error z komunikatem timeout. +Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. +Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. Poniżej przykład kodu podyktowanego tymi zasadami: @@ -1216,9 +1217,9 @@ Poniżej przykład kodu podyktowanego tymi zasadami: Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -Aby stworzyć zagnieżdżony tag, wewnątrz naszego głównego tagu, rozważmy nasz atrybut `'self.xml'` jako Element z ET (ElementTree). +Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). -Można powtórzyć poprzednie działania, inicjalizować nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree z pomocą metody `'append'`. Jeśli przetwarzamy typ napisowy, można to zrobić nawet dzięki parsowaniu napisu na Element i kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, tu pokażę bardziej ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. +Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typy napisowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. .. code-block:: python @@ -1240,7 +1241,7 @@ Można powtórzyć poprzednie działania, inicjalizować nowy element jak głów Kompletny kod z tutorialu ------------------------- -Do kompletnego kodu pozostawione zostały angielskie komentarze, tworząc własny plugin za pierwszym razem, jestem przekonany że będą przydatne: +W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angielskim. .. code-block:: python @@ -1782,5 +1783,3 @@ Official pdf documentation: * https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf Note: Dokumentacje w formie Web i PDF mają pewne różnice, pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. - - diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index b5680b5a..73e840c4 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -1,11 +1,12 @@ -# How to make a slixmpp plugins for Messages and IQ extensions +How to make a slixmpp plugins for Messages and IQ extensions +======================================================================= -## Introduction and requirements +Introduction and requirements +----------------- -- `'python3'` +* `'python3'` Code used in the following tutorial is written in python 3.6 or newer. - For backward compatibility, replace the f-strings functionality with older string formatting: `'"{}".format("content")'` or `'%s, "content"'`. Ubuntu linux installation steps: @@ -14,14 +15,13 @@ Ubuntu linux installation steps: sudo apt-get install python3.6 -- `'slixmpp'` -- `'argparse'` -- `'logging'` -- `'subprocess'` -- `'threading'` +* `'slixmpp'` +* `'argparse'` +* `'logging'` +* `'subprocess'` +* `'threading'` -Check if these libraries and the proper python version are available for your environment. -Every one of these, except the slixmpp, is a standard python library. To not have them installed by default is an unusual situation. +Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happend that some of them may not be installed. .. code-block:: python @@ -44,10 +44,10 @@ Example output: 1.1 ~ $ python3 -c "import logging; print(logging.__version__)" 0.5.1.2 - ~ $ python3 -m subprocess #This should return nothing - ~ $ python3 -m threading #This should return nothing + ~ $ python3 -m subprocess #Should return nothing + ~ $ python3 -m threading #Should return nothing -If some of the libraries throw `'ImportError'` or `'no module named ...'` error, try to install them with: +If some of the libraries throw `'ImportError'` or `'no module named ...'` error, install them with: On ubuntu linux: @@ -57,31 +57,32 @@ On ubuntu linux: #or easy_install slixmpp -If some of the libraries throws NameError, reinstall the whole package. +If some of the libraries throws NameError, reinstall the whole package once again. -- `Jabber accounts` +* `Jabber accounts` -For the testing purposes, two private jabber accounts are required. They can be created on one of many available sites, for example: +For the testing purposes, two private jabber accounts are required. They can be created on one of many available sites: [https://www.google.com/search?q=jabber+server+list](https://www.google.com/search?q=jabber+server+list) -## Client launch script +Client launch script +----------------------------- -The client launch script should be created outside of the main project location. This allows us to easly obtain the results when needed. It is recommended for the script to be outside of the project location in order to avoid accidental lekeage of our credencial details to the git platform. +The client launch script should be created outside of the main project location. This allows to easly obtain the results when needed and prevents accidental lekeage of credencial details to the git platform. -As the example, I created a file `'test_slixmpp'` in `'/usr/bin'` directory and give it the execute permission: +As the example, a file `'test_slixmpp'` can be created in `'/usr/bin'` directory, with executive permission: .. code-block:: bash /usr/bin $ chmod 711 test_slixmpp -This file contains: +This file should be readable and writable only with superuser permission. This file contains a simple structure for logging credentials: .. code-block:: python #!/usr/bin/python3 #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - + import subprocess import threading import time @@ -90,8 +91,8 @@ This file contains: subprocess.run(shell_string, shell=True, universal_newlines=True) if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client; you can replace xterm with your terminal - #~ prefix = "xterm -e" # Separate terminal for every client; you can replace xterm with your terminal + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client; can be replaced with other terminal + #~ prefix = "xterm -e" prefix = "" #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet @@ -107,11 +108,11 @@ This file contains: responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \\ + # Remember about the executable permission. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \\ + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" try: @@ -124,16 +125,16 @@ This file contains: except: print ("Error: unable to start thread") -The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatybility is needed, replace it with `'call'` method and adjust accordingly. The launch script should be convinient in use and easy to reconfigure again. We can adapt it to our needs, so it saves our time in the future. +The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatybility is needed, replace it with `'subprocess.call'` method and adjust accordingly. -We can define there the logging credentials, the paths derived from `'sys.argv[...]'` or `'os.getcwd()'`, set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. +The launch script should be convinient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. We can define there the logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. -[TODO] Before closed, make it open till proper paths to file be created (about full jid later). -In case of manually testing the larger applications, it would be a good practise to introduce the unique name (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. +In case of manually testing the larger applications, it would be a good practise to introduce the unique names (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. -## Creating the client and the plugin +Creating the client and the plugin +---------------------------- -Two clients should be created in order to check if everything works correctly. I created the `'sender'` and the `'responder'` clients. The minimal amount of code needed for effective building and testing of the plugin is the following: +Two slimxmpp clients should be created in order to check if everything works correctly (here: the `'sender'` and the `'responder'`). The minimal amount of code needed for effective building and testing of the plugin is the following: .. code-block:: python @@ -156,12 +157,12 @@ Two clients should be created in order to check if everything works correctly. I self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): - # Two, not required methods, but allows another users to see us available, and receive that information. + # Two, not required methods, but allows another users to see if the client is online. self.send_presence() self.get_roster() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) @@ -192,8 +193,8 @@ Two clients should be created in order to check if everything works correctly. I args.password = getpass("Password: ") xmpp = Sender(args.jid, args.password, args.to, args.path) - #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is the example_plugin class name. + xmpp.connect() try: xmpp.process() @@ -220,10 +221,10 @@ Two clients should be created in order to check if everything works correctly. I self.add_event_handler("session_start", self.start) def start(self, event): - # Two, not required methods, but allows another users to see us available, and receive that information. + # Two, not required methods, but allows another users to see if the client is online. self.send_presence() self.get_roster() - + if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) @@ -252,7 +253,7 @@ Two clients should be created in order to check if everything works correctly. I args.password = getpass("Password: ") xmpp = Responder(args.jid, args.password) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is the example_plugin class name. xmpp.connect() try: @@ -284,35 +285,36 @@ Next file to create is `'example_plugin.py'`. It can be placed in the same catal class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. + self.xep = "ope" ##~ String data readable by humans and to find plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` field, with 'xep_OPE' prefix. namespace = ExampleTag.namespace - - + + class ExampleTag(ElementBase): - name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + name = "example_tag" ##~ The name of the root XML element for that extension. + namespace = "" ##~ The namespace our stanza object lives in, like . Should be changed to your own namespace. - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name under which the data in plugin can be accessed. In particular, this object is reachable from the outside with: stanza_object['example_tag']. The `'example_tag'` is name of ElementBase extension and should be that same as the name. - interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. -If it is not in the same directory, then the symbolic link to the localisation reachable by the clients should be established: +If the plugin is not in the same directory as the clients, then the symbolic link to the localisation reachable by the clients should be established: .. code-block:: bash ln -s $Path_to_example_plugin_py $Path_to_clients_destinations -The other solution is to relative import it (with the use of dots '.') to get the proper path. +The other solution is to relative import it (with dots '.') to get the proper path. -## First run and the event handlers +First run and the event handlers +----------------------------------------------- -To check if everything is okay, we can use the start method. Right after the client is ready, the event `'session_start'` should be raised. +To check if everything is okay, we can use the `'start'` method (which triggers the `'session_start'` event). Right after the client is ready, the signal will be sent. -In the `'__init__'` method, the handler for event call `'session_start'` is created. When it is called, the `'def start(self, event):'` method will be executed. During the first run, add the line: `'logging.info("I'm running")'` to both of the clients' code (the sender and the responder) and use `'test_slixmpp'` command. +In the `'__init__'` method, the handler for event call `'session_start'` is created. When it is called, the `'def start(self, event):'` method will be executed. During the first run, add the line: `'logging.info("I'm running")'` to both the sender and the responder, and use `'test_slixmpp'` command. -Now, the `'def start(self, event):'` method should look like this: +The `'def start(self, event):'` method should look like this: .. code-block:: python @@ -320,16 +322,17 @@ Now, the `'def start(self, event):'` method should look like this: # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> logging.info("I'm running") #<<<<<<<<<<<< -If everything works fine, we can comment this line out and go to the first example: sending a message. +If everything works fine, we can comment this line out. -## Building the message object +Building the message object +------------------------- -In this section of the tutorial, the example sender class should get a recipient (jid of responder) from command line arguments, stored in test_slixmpp. An access to this argument is stored in the `'self.to'`attribute. +The example sender class should get a recipient name and address (jid of responder) from command line arguments, stored in test_slixmpp. An access to this argument is stored in the `'self.to'`attribute. Code example: @@ -345,7 +348,7 @@ Code example: self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -360,7 +363,7 @@ Code example: msg.send() #<<<<<<<<<<<< -In the example below, we are using the build-in method of making the message object. It contains a string "example_message" and is called right after the `'start'` method. +In the example below, we are using the build-in method `'make_message'`. It creates a string "example_message" and sends it at the end of `'start'` method. The message will be sent once, after the script launch. To receive this message, the responder should have a proper handler to the signal with the message object and the method to decide what to do with this message. As it is shown in the example below: @@ -377,7 +380,7 @@ To receive this message, the responder should have a proper handler to the signa #>>>>>>>>>>>> self.add_event_handler("message", self.message) #<<<<<<<<<<<< - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -387,11 +390,11 @@ To receive this message, the responder should have a proper handler to the signa def message(self, msg): #Show all inside msg logging.info(msg) - #Show only body attribute, like dictionary access + #Show only body attribute logging.info(msg['body']) #<<<<<<<<<<<< - -Expanding the message with new tags +//TODO from here +Expanding the message with new tag ++++++++++++++++++++++++++++ To expand the Message object with our tag, the plugin should be registered as the extension for the Message object: @@ -402,8 +405,8 @@ To expand the Message object with our tag, the plugin should be registered as th class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. namespace = ExampleTag.namespace #>>>>>>>>>>>> -- cgit v1.2.3 From b15d4aa0faebe5e2dd3adf85dde8ae0cbd9f1f27 Mon Sep 17 00:00:00 2001 From: Paulina Date: Sun, 15 Mar 2020 15:17:00 +0100 Subject: Correction and editing of the tutorials. [95 %] English version [95 %] Polish version [100%] Both version consistency check [80 %] Final sanity check + formating --- docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst | 134 +++++------ .../make_plugin_extension_for_message_and_iq.rst | 257 +++++++++++---------- 2 files changed, 197 insertions(+), 194 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst index ff6cd0b9..f138311c 100644 --- a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst +++ b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst @@ -394,11 +394,11 @@ Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: #Pokazuje wyłącznie pole 'body' wiadomości logging.info(msg['body']) #<<<<<<<<<<<< -//TODO from here -Rozszerzenie Message o nasz tag + +Rozszerzenie Message o nowy tag +++++++++++++++++++++++++++++++ -Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message. +Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message: .. code-block:: python @@ -406,21 +406,21 @@ Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin pow class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin. - self.xep = "ope" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py`, do metody `__all__` z 'xep_OPE'. + self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. #<<<<<<<<<<<< class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" + name = "example_tag" ##~ Nazwa pliku XML dla tego rozszerzenia.. + namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . - plugin_attrib = "example_tag" + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - interfaces = {"boolean", "some_string"} + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. #>>>>>>>>>>>> def set_boolean(self, boolean): @@ -430,7 +430,7 @@ Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin pow self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< -Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. +Teraz, po rejestracji tagu, można rozszerzyć wiadomość. .. code-block:: python @@ -446,11 +446,14 @@ Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. self.add_event_handler("session_start", self.start) def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() self.send_example_message(self.to, "example_message") def send_example_message(self, to, body): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) #>>>>>>>>>>>> msg['example_tag'].set_some_string("Work!") @@ -458,7 +461,7 @@ Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. #<<<<<<<<<<<< msg.send() -Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z napisem `'Work'` oraz nadanym namespace. +Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , oraz z napisem `'Work'` i nadanym namespace. Nadanie oddzielnego sygnału dla rozszerzonej wiadomości +++++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -471,34 +474,31 @@ Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" + self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace - #>>>>>>>>>>>> + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag', ##~ Nazwa tego Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytujemy wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag - self.__handle_message)) ##~ Metoda do której przypisujemy przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. - #<<<<<<<<<<<< - register_stanza_plugin(Message, ExampleTag) + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytuje wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag + self.__handle_message)) ##~ Metoda do której zostaje przypisany przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. + + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. - #>>>>>>>>>>>> def __handle_message(self, msg): - # Tu możemy coś zrobić z przechwyconą wiadomością zanim trafi do klienta. + # Tu można coś zrobić z przechwyconą wiadomością zanim trafi do klienta. self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. - #<<<<<<<<<<<< Obiekt StanzaPath powinien być poprawnie zainicjalizowany, według schematu: `'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` * Dla NAZWA_OBIEKTU można użyć `'message'` lub `'iq'`. -* Dla TYP_OBIEKTU, jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'` -* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można sprecyzować typ spośród: `'get, set, error or result'` -* Dla NAMESPACE to powinien być namespace zgodny z rozszerzeniem tagu. +* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można użyć typu spośród: `'get, set, error or result'`. Jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'`.. +* Dla NAMESPACE powinien to być namespace zgodny z rozszerzeniem tagu. * TAG powinien zawierać tag, tutaj: `'example_tag'`. -Teraz, rogram przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też, jak w programowaniu agentowym, sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomośc jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. +Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomość jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. .. code-block:: python @@ -514,19 +514,22 @@ Teraz, rogram przechwyci wszystkie message, które zawierają sprecyzowany names self.add_event_handler("session_start", self.start) def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> self.send_example_message(self.to, "example_message", "example_string") def send_example_message(self, to, body, some_string=""): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) if some_string: msg['example_tag'].set_some_string(some_string) msg.send() #<<<<<<<<<<<< - -Należy zapamiętać linię pluginu: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku responder.py. Tutaj: `'example_tag_message'`. + +Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku "responder.py". Tutaj to: `'example_tag_message'`. .. code-block:: python @@ -542,24 +545,25 @@ Należy zapamiętać linię pluginu: `'self.xmpp.event('example_tag_message', ms #<<<<<<<<<<<< def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> def example_tag_message(self, msg): - logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq jest inaczej). + logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej, ale nic się nie stanie, gdy zostanie wysłana. #<<<<<<<<<<<< -Teraz można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. -Natomiast kolejny obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. +Można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. +Natomiast obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout, jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. Użyteczne metody i inne ----------------------- -Modyfikacja przykładowego obiektu `Message` na `Iq`. +Modyfikacja przykładowego obiektu `Message` na obiekt `Iq`. ++++++++++++++++++++++++++++++++++++++++++++++++++++ -Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o nasz tag"`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami. Poprawia to czytelność kodu oraz weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). +Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o tag"`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). .. code-block:: python @@ -567,50 +571,52 @@ Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" + self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> self.xmpp.register_handler( - Callback('ExampleGet Event:example_tag', - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), - self.__handle_get_iq)) + Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacka + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag + self.__handle_get_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. self.xmpp.register_handler( - Callback('ExampleResult Event:example_tag', - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), - self.__handle_result_iq)) + Callback('ExampleResult Event:example_tag', ##~ Nazwa tego Callbacka + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag + self.__handle_result_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. self.xmpp.register_handler( - Callback('ExampleError Event:example_tag', - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), - self.__handle_error_iq)) - #<<<<<<<<<<<< + Callback('ExampleError Event:example_tag', ##~ Nazwa tego Callbacka + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag + self.__handle_error_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. + self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', - StanzaPath(f'message/{{{namespace}}}example_tag'), - self.__handle_message)) + Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacka + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Iq z example_tag + self.__handle_message)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. - #>>>>>>>>>>>> - register_stanza_plugin(Iq, ExampleTag) + register_stanza_plugin(Iq, ExampleTag) ##~ Rejestruje rozszerzenie taga dla obiektu Iq. W przeciwnym wypadku, Iq['example_tag'] będzie polem string zamiast kontenerem. #<<<<<<<<<<<< - register_stanza_plugin(Message, ExampleTag) + register_stanza_plugin(Message, ExampleTag) ##~ Rejestruje rozszerzenie taga dla obiektu Message. W przeciwnym wypadku, message['example_tag'] będzie polem string zamiast kontenerem. #>>>>>>>>>>>> # Wszystkie możliwe typy Iq to: get, set, error, result def __handle_get_iq(self, iq): - self.xmpp.event('example_tag_get_iq', iq) + # Zrób coś z otrzymanym iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. def __handle_result_iq(self, iq): - self.xmpp.event('example_tag_result_iq', iq) + # Zrób coś z otrzymanym Iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. def __handle_error_iq(self, iq): - self.xmpp.event('example_tag_error_iq', iq) - #<<<<<<<<<<<< + # Zrób coś z otrzymanym Iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. def __handle_message(self, msg): - self.xmpp.event('example_tag_message', msg) + # Zrób coś z otrzymanym message + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. @@ -1290,7 +1296,6 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel except: print ("Error: unable to start thread") - .. code-block:: python #File: $WORKDIR/example/example_plugin.py @@ -1419,8 +1424,7 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text - self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. - + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. ~ @@ -1765,21 +1769,19 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel Info_inside_tag - Źródła i bibliogarfia --------------------- -Slixmpp project description: +Slixmpp - opis projektu: * https://pypi.org/project/slixmpp/ -Official web documentation: - -* https://slixmpp.readthedocs.io/ +Oficjalna strona z dokumentacją: +* https://slixmpp.readthedocs.io/ -Official pdf documentation: +Oficjalna dokumentacja PDF: * https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf -Note: Dokumentacje w formie Web i PDF mają pewne różnice, pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. +Note: Dokumentacje w formie Web i PDF różnią się; pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index 73e840c4..9c5dae2a 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -393,11 +393,11 @@ To receive this message, the responder should have a proper handler to the signa #Show only body attribute logging.info(msg['body']) #<<<<<<<<<<<< -//TODO from here -Expanding the message with new tag + +Expanding the Message with a new tag ++++++++++++++++++++++++++++ -To expand the Message object with our tag, the plugin should be registered as the extension for the Message object: +To expand the Message object with a tag, the plugin should be registered as the extension for the Message object: .. code-block:: python @@ -405,22 +405,22 @@ To expand the Message object with our tag, the plugin should be registered as th class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register the tags extension for Message object, otherwise message['example_tag'] will be string field instead container and whould not be able to manage fields and create sub elements. #<<<<<<<<<<<< - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The namespace for stanza object, like . - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as 'name' above. interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - + #>>>>>>>>>>>> def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) @@ -429,7 +429,7 @@ To expand the Message object with our tag, the plugin should be registered as th self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< -Now with the registered object, the message can be extended. +Now, with the registered object, the message can be extended. .. code-block:: python @@ -443,7 +443,7 @@ Now with the registered object, the message can be extended. self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -460,12 +460,12 @@ Now with the registered object, the message can be extended. #<<<<<<<<<<<< msg.send() -After running, the following message from the logging should show the `'example_tag'` stored inside with string and namespace defined previously by us. +After running, the logging should print the Message with tag `'example_tag'` stored inside , string `'Work'` and given namespace. -Catching the extended message with different event handler +Giving the extended message the separate signal +++++++++++++++++++++++++++++++++++++++++++++++++++ -To get the difference between the extended messages and basic messages (or Iq), we can register the handler for the new namespace and tag. Then, make a unique name combination and handle only these required messages. +If the separate event is not defined, then both normal and extended message will be cached by signal `'message'`. In order to have the special event, the handler for the namespace ang tag should be created. Then, make a unique name combination, which allows the handler can catch only the wanted messages (or Iq object). .. code-block:: python @@ -473,30 +473,30 @@ To get the difference between the extended messages and basic messages (or Iq), class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag - self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handles only the Message with good example_tag and namespace. + self.__handle_message)) ##~ Method which catches the proper Message, should raise event for the client. + register_stanza_plugin(Message, ExampleTag) ##~ Register the tags extension for Message object, otherwise message['example_tag'] will be string field instead container and whould not be able to manage fields and create sub elements. + def __handle_message(self, msg): - # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + # Here something can be done with received message before it reaches the client. + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by the client with desired objest as an argument. StanzaPath objects should be initialized in a specific way, such as: `'OBJECT_NAME[@type=TYPE_OF_OBJECT][/{NAMESPACE}[TAG]]'` -- For OBJECT_NAME we can use `'message'` or `'iq'`. -- For TYPE_OF_OBJECT, if we specify iq, we can use`'get, set, error or result'` -- NAMESPACE should always be a namespace from our tag extension class. -- TAG should contain our tag, in this case:`'example_tag'`. +* For OBJECT_NAME we can use `'message'` or `'iq'`. +* For TYPE_OF_OBJECT, when iq is specified, `'get, set, error or result'` can be used. When objest is a message, then the message type can be used, like `'chat'`. +* NAMESPACE should always be a namespace from tag extension class. +* TAG should contain the tag, in this case:`'example_tag'`. -Now we are catching every message containing our namespace inside the `'example_tag'`field. We can check the content of it and then send it to the client with `'example_tag_message'` event. +Now every message containing the defined namespace inside `'example_tag'` is catched. It is possible to check the content of it. Then, the message is send to the client with the `'example_tag_message'` event. .. code-block:: python @@ -510,7 +510,7 @@ Now we are catching every message containing our namespace inside the `'example_ self.path = path self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -527,9 +527,7 @@ Now we are catching every message containing our namespace inside the `'example_ msg.send() #<<<<<<<<<<<< -Next, remember line: `'self.xmpp.event('example_tag_message', msg)'`. - -There is a responder event handler that uses the`'example_tag_message'`. +Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The name of an event to catch inside the "responder.py" file was defined here. Here it is: `'example_tag_message'`. .. code-block:: python @@ -541,7 +539,7 @@ There is a responder event handler that uses the`'example_tag_message'`. self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> - self.add_event_handler("example_tag_message", self.example_tag_message) + self.add_event_handler("example_tag_message", self.example_tag_message) #Registration of the handler #<<<<<<<<<<<< def start(self, event): @@ -551,17 +549,19 @@ There is a responder event handler that uses the`'example_tag_message'`. #>>>>>>>>>>>> def example_tag_message(self, msg): - logging.info(msg) # Message is standalone object, it can be replied, but no error arrives if not. + logging.info(msg) # Message is standalone object, it can be replied, but no error rises if not. #<<<<<<<<<<<< -We can reply to the messages, but nothing will happen if we don't. However, when we receive the Iq object, we should always reply. Otherwise, the error reply occurs on the client side due to the target timeout. +The messages can be replied, but nothing will happen if we don't. +However, when we receive the Iq object, we should always reply. Otherwise, the error occurs on the client side due to the target timeout if the cell Iq won't reply with Iq with the same Id. -## Useful methods and others +Useful methods and misc. +----------------------- -Modifying the `Message` object example to `Iq` object. +Modifying the example `Message` object to the `Iq` object. ++++++++++++++++++++++++++++++++++++++++ -To convert the Message to the Iq object, we need to register a new handler for the Iq. We can do it in the same maner as in the `,,Extend message with our tags''`part. The following example contains several types of Iq [TODO with separate types to catch]. We can use it to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be pass on to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. +To convert the Message into the Iq object, a new handler for the Iq should be registered, in the same maner as in the `,,Extend message with tags''`part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. .. code-block:: python @@ -569,24 +569,24 @@ To convert the Message to the Iq object, we need to register a new handler for t class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'get' and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'result' and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'error' and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( @@ -602,22 +602,21 @@ To convert the Message to the Iq object, we need to register a new handler for t # All iq types are: get, set, error, result def __handle_get_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_get_iq', iq) ##~ Call the event which can be handled by clients to send or something other. def __handle_result_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_result_iq', iq) ##~ Call the event which can be handled by clients to send or something other. def __handle_error_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other. def __handle_message(self, msg): # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. - #<<<<<<<<<<<< + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other. -The events called from the handlers, can be caught like in the`'example_tag_message'` example. +The events called by the example handlers can be caught like in the`'example_tag_message'` example. .. code-block:: python @@ -634,13 +633,13 @@ The events called from the handlers, can be caught like in the`'example_tag_mess #<<<<<<<<<<<< #>>>>>>>>>>>> - def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it call an error. + def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it calls an error. logging.info(str(iq)) reply = iq.reply(clear=False) reply.send() #<<<<<<<<<<<< -By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that case, the content of the Iq should be set again. After using the reply method, only the Id and the Jid parameters will stillbe set. +By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that case, the content of the Iq should be set again. After using the reply method, only the Id and the Jid parameters will still be set. .. code-block:: python @@ -663,10 +662,10 @@ By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag #<<<<<<<<<<<< #>>>>>>>>>>>> @@ -690,7 +689,7 @@ By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that Different ways to access the elements +++++++++++++++++++++++ -There are several ways to access the elements inside the Message or Iq stanza. The first one, from the client's side, is simply accessing the dictionary: +There are several ways to access the elements inside the Message or Iq stanza. The first one: the client can access them like a dictionary: .. code-block:: python @@ -708,17 +707,17 @@ There are several ways to access the elements inside the Message or Iq stanza. T logging.info(iq.get('example_tag').get('boolean')) #<<<<<<<<<<<< -For the ExampleTag extension, there is a getter and setter method for specific fields: +The access to the elements from extendet ExampleTag is simmilar. However, defining the types is not required and the access can be diversified (like for the `'text'` field below). For the ExampleTag extension, there is a 'getter' and 'setter' method for specific fields: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . Should be changed for own namespace. - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'], the `'example_tag'` is the name of ElementBase extension. And this should be that same as name. interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. @@ -738,7 +737,7 @@ For the ExampleTag extension, there is a getter and setter method for specific f The attribute `'self.xml'` is inherited from the ElementBase and is exactly the same as the `'Iq['example_tag']'` from the client namespace. -When the proper setters and getters are used, then the code can be cleaner and more object-oriented, like in the example below: +When the proper setters and getters are used, it is easy to check whether some argument is proper for the plugin or is conversable to another type. The code itself can be cleaner and more object-oriented, like in the example below: .. code-block:: python @@ -758,9 +757,9 @@ When the proper setters and getters are used, then the code can be cleaner and m def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") - iq['example_tag']['boolean'] = "True" + iq['example_tag']['boolean'] = "True" #Direct assignment #>>>>>>>>>>>> - iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_some_string("Another_string") #Assignment by setter iq['example_tag'].set_text("Info_inside_tag") #<<<<<<<<<<<< iq.send() @@ -768,19 +767,19 @@ When the proper setters and getters are used, then the code can be cleaner and m Message setup from the XML files, strings and other objects +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -There are many ways set up a xml from a string, xml-containing file or lxml (ElementTree) file. One of them is parsing the strings to lxml object, passing the attributes and other information, which may look like this: +There are many ways to set up a xml from a string, xml-containing file or lxml (ElementTree) file. One of them is parsing the strings to lxml object, passing the attributes and other information, which may look like this: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + #... from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin #... - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -806,22 +805,22 @@ There are many ways set up a xml from a string, xml-containing file or lxml (Ele self.xml.append(inner_tag) #<<<<<<<<<<<< -To test this, we need an example file with xml, example xml string and example ET object: +To test this, we need an example file with xml, example xml string and example lxml (ET) object: .. code-block:: xml #File: $WORKDIR/test_example_tag.xml - - Info_inside_tag + + Info_inside_tag .. code-block:: python #File: $WORKDIR/example/sender.py - + #... from slixmpp.xmlstream import ET #... - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) @@ -839,24 +838,24 @@ To test this, we need an example file with xml, example xml string and example E self.get_roster() #>>>>>>>>>>>> - self.disconnect_counter = 3 # This is only for disconnect when we receive all replies for sended Iq + self.disconnect_counter = 3 # Disconnects when all replies from Iq are received. self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - + # Info_inside_tag + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + self.disconnect() # Example disconnect after receiving the maximum number of recponses. def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) @@ -880,22 +879,22 @@ To test this, we need an example file with xml, example xml string and example E iq.send() #<<<<<<<<<<<< -If the Responder returns the proper `'Iq'` in the reply, then everything went okay and the Sender can be disconnected. +If the Responder returns the proper `'Iq'` and the Sender disconnects after three answers, then everything works okay. Dev friendly methods for plugin usage +++++++++++++++++++++++++++++++++++++ -Any plugin should have some sort of object-like methods, setup for our elements: getters, setters and signals to make it easy to use. -During handling, the correctness of the data should be checked and the eventual errors returned to the sender. +Any plugin should have some sort of object-like methods, that was setup for elements: reading the data, getters, setters and signals, to make them easy to use. +During handling, the correctness of the data should be checked and the eventual errors returned back to the sender. In order to avoid the situation where the answer message is never send, the sender gets the timeout error. The following code presents exactly this: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin from slixmpp import Iq @@ -910,8 +909,8 @@ The following code presents exactly this: class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace self.xmpp.register_handler( @@ -922,20 +921,20 @@ The following code presents exactly this: self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag - self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. # All iq types are: get, set, error, result def __handle_get_iq(self, iq): @@ -946,23 +945,23 @@ The following code presents exactly this: error["error"]["text"] = "Without some_string value returns error." error.send() # Do something with received iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other. def __handle_result_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other. def __handle_error_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other. def __handle_message(self, msg): # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other. class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The namespace stanza object lives in, like . You should change it for your own namespace. plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -1261,7 +1260,8 @@ To make the nested element inside our IQ tag, we need to consider `self.xml` fie There is a way to do this with a dictionary and name for the nested element tag. In that case, the insides of the function fields should be transferred to the ET element. -## Complete code from tutorial +Complete code from tutorial +------------------------- .. code-block:: python @@ -1294,10 +1294,10 @@ There is a way to do this with a dictionary and name for the nested element tag. responder_password = "RESPONDER_PASSWORD" # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \\ + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \\ + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" try: @@ -1313,7 +1313,7 @@ There is a way to do this with a dictionary and name for the nested element tag. .. code-block:: python #File: $WORKDIR/example/example_plugin.py - + import logging from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin @@ -1382,7 +1382,7 @@ There is a way to do this with a dictionary and name for the nested element tag. class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -1435,7 +1435,7 @@ There is a way to do this with a dictionary and name for the nested element tag. def add_inside_tag(self, tag, attributes, text=""): #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. @@ -1475,29 +1475,29 @@ There is a way to do this with a dictionary and name for the nested element tag. self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1612,7 +1612,7 @@ There is a way to do this with a dictionary and name for the nested element tag. .. code-block:: python #File: $WORKDIR/example/responder.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1642,29 +1642,29 @@ There is a way to do this with a dictionary and name for the nested element tag. self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1782,20 +1782,21 @@ There is a way to do this with a dictionary and name for the nested element tag. .. code-block:: xml - Info_inside_tag + Info_inside_tag -## Sources and references +Sources and references +--------------------- The Slixmpp project description: -- [https://pypi.org/project/slixmpp/](https://pypi.org/project/slixmpp/) +* https://pypi.org/project/slixmpp/ Official web documentation: -- [https://slixmpp.readthedocs.io/](https://slixmpp.readthedocs.io/) +* https://slixmpp.readthedocs.io/ -Official pdf documentation: +Official PDF documentation: -- [https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf](https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf) +* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf Note: Web and PDF Documentations have differences and some things are mentioned in only one of them. -- cgit v1.2.3 From fe6458303a57dc00d8eb7adb017e31a4470e39f8 Mon Sep 17 00:00:00 2001 From: Paulina Date: Sun, 15 Mar 2020 15:26:21 +0100 Subject: Correction and editing of the tutorials. [85 %] English version [90 %] Polish version [45 %] Both version consistency check [0 %] Final sanity check + formating --- docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst | 1785 -------------------- ...make_plugin_extension_for_message_and_iq.pl.rst | 1785 ++++++++++++++++++++ 2 files changed, 1785 insertions(+), 1785 deletions(-) delete mode 100644 docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst create mode 100644 docs/howto/make_plugin_extension_for_message_and_iq.pl.rst (limited to 'docs/howto') diff --git a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst b/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst deleted file mode 100644 index ff6cd0b9..00000000 --- a/docs/howto/Tutorial_Plugin_do_Slixmpp.pl.rst +++ /dev/null @@ -1,1785 +0,0 @@ -Jak stworzyć własny plugin rozszerzający obiekty Message i Iq w Slixmpp -======================================================================= - -Wstęp i wymagania ------------------ - -* `'python3'` - -Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6 lub nowszej. -Dla wstecznej kompatybilności z wcześniejszymi wersjami należy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. - -Instalacja dla Ubuntu linux: - -.. code-block:: bash - - sudo apt-get install python3.6 - -* `'slixmpp'` -* `'argparse'` -* `'logging'` -* `'subprocess'` -* `'threading'` - -Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdaża się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. - -.. code-block:: python - - python3 --version - python3 -c "import slixmpp; print(slixmpp.__version__)" - python3 -c "import argparse; print(argparse.__version__)" - python3 -c "import logging; print(logging.__version__)" - python3 -m subprocess - python3 -m threading - -Wynik w terminalu: - -.. code-block:: bash - - ~ $ python3 --version - Python 3.8.0 - ~ $ python3 -c "import slixmpp; print(slixmpp.__version__)" - 1.4.2 - ~ $ python3 -c "import argparse; print(argparse.__version__)" - 1.1 - ~ $ python3 -c "import logging; print(logging.__version__)" - 0.5.1.2 - ~ $ python3 -m subprocess # Nie powinno nic zwrócić - ~ $ python3 -m threading # Nie powinno nic zwrócić - -Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, należy je zainstalować zgodnie z przykładem poniżej: - -Instalacja Ubuntu linux: - -.. code-block:: bash - - pip3 install slixmpp - #or - easy_install slixmpp - -Jeśli jakaś biblioteka zwróci NameError, należy zainstalować pakiet ponownie. - -* `Konta dla Jabber` - -Do testowania niezbędne będą dwa prywatne konta jabbera. -Można je stworzyć na jednym z dostępnych darmowych serwerów: - -https://www.google.com/search?q=jabber+server+list - -Skrypt uruchamiający klientów ------------------------------ - -Skrypt pozwalający testować klientów powinien zostać stworzony poza lokalizacją projektu. Pozwoli to szybko sprawdzać wyniki skryptów oraz uniemożliwi przypadkowe wysłanie swoich danych na gita. - -Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/usr/bin'` i nadać mu uprawnienia wykonywawcze: - -.. code-block:: bash - - /usr/bin $ chmod 711 test_slixmpp - -Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawiera prostą strukturę, która pozwoli nam zapisać dane logowania. - -.. code-block:: python - - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala - #~ prefix = "xterm -e" - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Pamiętaj o nadaniu praw do wykonywania (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") - -Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. - -Skrypt uruchomieniowy powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. - -W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko okreslić, który klient co zwraca, bądź który powoduje błąd. - -Stworzenie klienta i pluginu ----------------------------- - -W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - import logging - from argparse import ArgumentParser - from getpass import getpass - import time - - import slixmpp - from slixmpp.xmlstream import ET - - import example_plugin - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - - def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostepność online. - self.send_presence() - self.get_roster() - - if __name__ == '__main__': - parser = ArgumentParser(description=Sender.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message/iq to") - parser.add_argument("--path", dest="path", - help="path to load example_tag content") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Sender(args.jid, args.password, args.to, args.path) - #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin. - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - import logging - from argparse import ArgumentParser - from getpass import getpass - - import slixmpp - import example_plugin - - class Responder(slixmpp.ClientXMPP): - def __init__(self, jid, password): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.add_event_handler("session_start", self.start) - - def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online - self.send_presence() - self.get_roster() - - if __name__ == '__main__': - parser = ArgumentParser(description=Responder.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message to") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Responder(args.jid, args.password) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - -Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w lokalizacji dostepnej dla klientów (domyślnie w tej samej, co skrypty klientów). - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - import logging - - from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - - from slixmpp import Iq - from slixmpp import Message - - from slixmpp.plugins.base import BasePlugin - - from slixmpp.xmlstream.handler import Callback - from slixmpp.xmlstream.matcher import StanzaPath - - log = logging.getLogger(__name__) - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin - self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin poprzez dodanie tego do `slixmpp/plugins/__init__.py`, w polu `__all__` z prefixem xep 'xep_OPE'. - - namespace = ExampleTag.namespace - - - class ExampleTag(ElementBase): - name = "example_tag" ##~ Nazwa głównego tagu dla XML w tym rozszerzeniu. - namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: - - plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` staje się nazwą pluginu i powinno być takie samo jak name. - - interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów elementu które mogą być użyte w elemencie. Na przykład `stanza_object['example_tag']` poda informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest elementu. - -Jeżeli powyższy plugin nie jest w domyślnej lokalizacji, a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu: - -.. code-block:: bash - - ln -s $Path_to_example_plugin_py $Path_to_clients_destinations - -Jeszcze innym wyjściem jest import relatywny z użyciem kropek '.' aby dostać się do właściwej ścieżki. - -Pierwsze uruchomienie i przechwytywanie eventów ------------------------------------------------ - -Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisany event `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. - -W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a nastepnie użyć komendy `'test_slixmpp'`. - -Metoda `'def start(self, event):'` powinna wyglądać tak: - -.. code-block:: python - - def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. - self.send_presence() - self.get_roster() - - #>>>>>>>>>>>> - logging.info("I'm running") - #<<<<<<<<<<<< - -Jeżeli oba klienty uruchomiły się poprawnie, można zakomentować tą linię. - -Budowanie obiektu Message -------------------------- - -Wysyłający powinien posiadać informację o tym, do kogo należy wysłać wiadomość. Nazwę i scieżkę odbiorcy można przekazać, na przykład, przez argumenty wywołania skryptu w lini komend. W poniższym przykładzie, są one trzymane w atrybucie `'self.to'`. - -Przykład: - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - - def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. - self.send_presence() - self.get_roster() - #>>>>>>>>>>>> - self.send_example_message(self.to, "example_message") - - def send_example_message(self, to, body): - #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Domyślnie mtype == "chat" if None; - msg = self.make_message(mto=to, mbody=body) - msg.send() - #<<<<<<<<<<<< - -W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. - -Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie został przypisany żaden inny event. Przykład takiego kodu: - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - - class Responder(slixmpp.ClientXMPP): - def __init__(self, jid, password): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.add_event_handler("session_start", self.start) - - #>>>>>>>>>>>> - self.add_event_handler("message", self.message) - #<<<<<<<<<<<< - - def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. - self.send_presence() - self.get_roster() - - #>>>>>>>>>>>> - def message(self, msg): - #Pokazuje cały XML wiadomości - logging.info(msg) - #Pokazuje wyłącznie pole 'body' wiadomości - logging.info(msg['body']) - #<<<<<<<<<<<< -//TODO from here -Rozszerzenie Message o nasz tag -+++++++++++++++++++++++++++++++ - -Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message. - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin. - self.xep = "ope" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py`, do metody `__all__` z 'xep_OPE'. - - namespace = ExampleTag.namespace - #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. - #<<<<<<<<<<<< - - class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" - - plugin_attrib = "example_tag" - - interfaces = {"boolean", "some_string"} - - #>>>>>>>>>>>> - def set_boolean(self, boolean): - self.xml.attrib['boolean'] = str(boolean) - - def set_some_string(self, some_string): - self.xml.attrib['some_string'] = some_string - #<<<<<<<<<<<< - -Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - - def start(self, event): - self.send_presence() - self.get_roster() - self.send_example_message(self.to, "example_message") - - def send_example_message(self, to, body): - msg = self.make_message(mto=to, mbody=body) - #>>>>>>>>>>>> - msg['example_tag'].set_some_string("Work!") - logging.info(msg) - #<<<<<<<<<<<< - msg.send() - -Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z napisem `'Work'` oraz nadanym namespace. - -Nadanie oddzielnego sygnału dla rozszerzonej wiadomości -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" - - namespace = ExampleTag.namespace - #>>>>>>>>>>>> - self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', ##~ Nazwa tego Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytujemy wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag - self.__handle_message)) ##~ Metoda do której przypisujemy przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. - #<<<<<<<<<<<< - register_stanza_plugin(Message, ExampleTag) - - #>>>>>>>>>>>> - def __handle_message(self, msg): - # Tu możemy coś zrobić z przechwyconą wiadomością zanim trafi do klienta. - self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. - #<<<<<<<<<<<< - -Obiekt StanzaPath powinien być poprawnie zainicjalizowany, według schematu: -`'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` - -* Dla NAZWA_OBIEKTU można użyć `'message'` lub `'iq'`. -* Dla TYP_OBIEKTU, jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'` -* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można sprecyzować typ spośród: `'get, set, error or result'` -* Dla NAMESPACE to powinien być namespace zgodny z rozszerzeniem tagu. -* TAG powinien zawierać tag, tutaj: `'example_tag'`. - -Teraz, rogram przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też, jak w programowaniu agentowym, sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomośc jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - - def start(self, event): - self.send_presence() - self.get_roster() - #>>>>>>>>>>>> - self.send_example_message(self.to, "example_message", "example_string") - - def send_example_message(self, to, body, some_string=""): - msg = self.make_message(mto=to, mbody=body) - if some_string: - msg['example_tag'].set_some_string(some_string) - msg.send() - #<<<<<<<<<<<< - -Należy zapamiętać linię pluginu: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku responder.py. Tutaj: `'example_tag_message'`. - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - - class Responder(slixmpp.ClientXMPP): - def __init__(self, jid, password): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.add_event_handler("session_start", self.start) - #>>>>>>>>>>>> - self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja handlera - #<<<<<<<<<<<< - - def start(self, event): - self.send_presence() - self.get_roster() - - #>>>>>>>>>>>> - def example_tag_message(self, msg): - logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq jest inaczej). - #<<<<<<<<<<<< - -Teraz można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. -Natomiast kolejny obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. - -Użyteczne metody i inne ------------------------ - -Modyfikacja przykładowego obiektu `Message` na `Iq`. -++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o nasz tag"`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami. Poprawia to czytelność kodu oraz weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" - - namespace = ExampleTag.namespace - #>>>>>>>>>>>> - self.xmpp.register_handler( - Callback('ExampleGet Event:example_tag', - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), - self.__handle_get_iq)) - - self.xmpp.register_handler( - Callback('ExampleResult Event:example_tag', - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), - self.__handle_result_iq)) - - self.xmpp.register_handler( - Callback('ExampleError Event:example_tag', - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), - self.__handle_error_iq)) - #<<<<<<<<<<<< - self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', - StanzaPath(f'message/{{{namespace}}}example_tag'), - self.__handle_message)) - - #>>>>>>>>>>>> - register_stanza_plugin(Iq, ExampleTag) - #<<<<<<<<<<<< - register_stanza_plugin(Message, ExampleTag) - - #>>>>>>>>>>>> - # Wszystkie możliwe typy Iq to: get, set, error, result - def __handle_get_iq(self, iq): - self.xmpp.event('example_tag_get_iq', iq) - - def __handle_result_iq(self, iq): - self.xmpp.event('example_tag_result_iq', iq) - - def __handle_error_iq(self, iq): - self.xmpp.event('example_tag_error_iq', iq) - #<<<<<<<<<<<< - - def __handle_message(self, msg): - self.xmpp.event('example_tag_message', msg) - -Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - - class Responder(slixmpp.ClientXMPP): - def __init__(self, jid, password): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_message", self.example_tag_message) - #>>>>>>>>>>>> - self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) - #<<<<<<<<<<<< - - #>>>>>>>>>>>> - def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem. - logging.info(str(iq)) - reply = iq.reply(clear=False) - reply.send() - #<<<<<<<<<<<< - -Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, co jest zawarte wewnątrz Iq (z kilkoma wyjątkami) powinno zostać zdefiniowane ponownie. Jedyne informacje które zostaną w Iq po metodzie reply, nawet gdy parametr clean jest ustawiony na True, to ID tego Iq oraz JID wysyłającego. - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - #>>>>>>>>>>>> - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - #<<<<<<<<<<<< - - def start(self, event): - self.send_presence() - self.get_roster() - - #>>>>>>>>>>>> - self.send_example_iq(self.to) - # Info_inside_tag - #<<<<<<<<<<<< - - #>>>>>>>>>>>> - def send_example_iq(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get") - iq['example_tag']['boolean'] = "True" - iq['example_tag']['some_string'] = "Another_string" - iq['example_tag'].text = "Info_inside_tag" - iq.send() - #<<<<<<<<<<<< - - #>>>>>>>>>>>> - def example_tag_result_iq(self, iq): - logging.info(str(iq)) - - def example_tag_error_iq(self, iq): - logging.info(str(iq)) - #<<<<<<<<<<<< - -Dostęp do elementów -+++++++++++++++++++ - -Jest kilka możliwości dostania się do pól wewnątrz Message lub Iq. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - #... - def example_tag_result_iq(self, iq): - logging.info(str(iq)) - #>>>>>>>>>>>> - logging.info(iq['id']) - logging.info(iq.get('id')) - logging.info(iq['example_tag']['boolean']) - logging.info(iq['example_tag'].get('boolean')) - logging.info(iq.get('example_tag').get('boolean')) - #<<<<<<<<<<<< - -Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wymagane jest określanie tagu, którego dotyczy. Dodatkową zaletą jest fakt niejednolitego dostępu, na przykład do parametru `'text'` między rozpoczęciem a zakończeniem tagu. Pokazuje to poniższy przykład, ujednolicając metody obiektowych getterów i setterów. - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" - - plugin_attrib = "example_tag" - - interfaces = {"boolean", "some_string"} - - #>>>>>>>>>>>> - def get_some_string(self): - return self.xml.attrib.get("some_string", None) - - def get_text(self, text): - return self.xml.text - - def set_some_string(self, some_string): - self.xml.attrib['some_string'] = some_string - - def set_text(self, text): - self.xml.text = text - #<<<<<<<<<<<< - -Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. - -Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo, kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - - def send_example_iq(self, to): - iq = self.make_iq(ito=to, itype="get") - iq['example_tag']['boolean'] = "True" #Przypisanie wprost - #>>>>>>>>>>>> - iq['example_tag'].set_some_string("Another_string") #Przypisanie poprzez setter - iq['example_tag'].set_text("Info_inside_tag") - #<<<<<<<<<<<< - iq.send() - -Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - #... - from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - #... - - class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" - - plugin_attrib = "example_tag" - - interfaces = {"boolean", "some_string"} - - #>>>>>>>>>>>> - def setup_from_string(self, string): - """Initialize tag element from string""" - et_extension_tag_xml = ET.fromstring(string) - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_file(self, path): - """Initialize tag element from file containing adjusted data""" - et_extension_tag_xml = ET.parse(path).getroot() - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_lxml(self, lxml): - """Add ET data to self xml structure.""" - self.xml.attrib.update(lxml.attrib) - self.xml.text = lxml.text - self.xml.tail = lxml.tail - for inner_tag in lxml: - self.xml.append(inner_tag) - #<<<<<<<<<<<< - -Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): - -.. code-block:: xml - - #File: $WORKDIR/test_example_tag.xml - - Info_inside_tag - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - #... - from slixmpp.xmlstream import ET - #... - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - - def start(self, event): - self.send_presence() - self.get_roster() - - #>>>>>>>>>>>> - self.disconnect_counter = 3 # Ta zmienna służy tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. - - self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag - - string = 'Info_inside_tag' - et = ET.fromstring(string) - self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag - - self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - - def example_tag_result_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. - - def send_example_iq_tag_from_file(self, to, path): - iq = self.make_iq(ito=to, itype="get", id=2) - iq['example_tag'].setup_from_file(path) - - iq.send() - - def send_example_iq_tag_from_element_tree(self, to, et): - iq = self.make_iq(ito=to, itype="get", id=3) - iq['example_tag'].setup_from_lxml(et) - - iq.send() - - def send_example_iq_tag_from_string(self, to, string): - iq = self.make_iq(ito=to, itype="get", id=5) - iq['example_tag'].setup_from_string(string) - - iq.send() - #<<<<<<<<<<<< - -Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa tak, jak powinno. - -Łatwość użycia pluginu dla programistów -+++++++++++++++++++++++++++++++++++++++ - -Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. -Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. - -Poniżej przykład kodu podyktowanego tymi zasadami: - -.. code-block:: python - - #File: $WORKDIR/example/example plugin.py - - import logging - - from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - - from slixmpp import Iq - from slixmpp import Message - - from slixmpp.plugins.base import BasePlugin - - from slixmpp.xmlstream.handler import Callback - from slixmpp.xmlstream.matcher import StanzaPath - - log = logging.getLogger(__name__) - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" - - namespace = ExampleTag.namespace - self.xmpp.register_handler( - Callback('ExampleGet Event:example_tag', - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), - self.__handle_get_iq)) - - self.xmpp.register_handler( - Callback('ExampleResult Event:example_tag', - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), - self.__handle_result_iq)) - - self.xmpp.register_handler( - Callback('ExampleError Event:example_tag', - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), - self.__handle_error_iq)) - - self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', - StanzaPath(f'message/{{{namespace}}}example_tag'), - self.__handle_message)) - - register_stanza_plugin(Iq, ExampleTag) - register_stanza_plugin(Message, ExampleTag) - - def __handle_get_iq(self, iq): - if iq.get_some_string is None: - error = iq.reply(clear=False) - error["type"] = "error" - error["error"]["condition"] = "missing-data" - error["error"]["text"] = "Without some_string value returns error." - error.send() - self.xmpp.event('example_tag_get_iq', iq) - - def __handle_result_iq(self, iq): - self.xmpp.event('example_tag_result_iq', iq) - - def __handle_error_iq(self, iq): - # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) - - def __handle_message(self, msg): - self.xmpp.event('example_tag_message', msg) - - class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" - - plugin_attrib = "example_tag" - - interfaces = {"boolean", "some_string"} - - def setup_from_string(self, string): - """Initialize tag element from string""" - et_extension_tag_xml = ET.fromstring(string) - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_file(self, path): - """Initialize tag element from file containing adjusted data""" - et_extension_tag_xml = ET.parse(path).getroot() - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_lxml(self, lxml): - """Add ET data to self xml structure.""" - self.xml.attrib.update(lxml.attrib) - self.xml.text = lxml.text - self.xml.tail = lxml.tail - for inner_tag in lxml: - self.xml.append(inner_tag) - - def setup_from_dict(self, data): - self.xml.attrib.update(data) - - def get_boolean(self): - return self.xml.attrib.get("boolean", None) - - def get_some_string(self): - return self.xml.attrib.get("some_string", None) - - def get_text(self, text): - return self.xml.text - - def set_boolean(self, boolean): - self.xml.attrib['boolean'] = str(boolean) - - def set_some_string(self, some_string): - self.xml.attrib['some_string'] = some_string - - def set_text(self, text): - self.xml.text = text - - def fill_interfaces(self, boolean, some_string): - self.set_boolean(boolean) - self.set_some_string(some_string) - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - - import logging - from argparse import ArgumentParser - from getpass import getpass - - import slixmpp - import example_plugin - - class Responder(slixmpp.ClientXMPP): - def __init__(self, jid, password): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) - self.add_event_handler("example_tag_message", self.example_tag_message) - - def start(self, event): - self.send_presence() - self.get_roster() - - def example_tag_get_iq(self, iq): - logging.info(iq) - reply = iq.reply() - reply["example_tag"].fill_interfaces(True, "Reply_string") - reply.send() - - def example_tag_message(self, msg): - logging.info(msg) - - - if __name__ == '__main__': - parser = ArgumentParser(description=Responder.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message to") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Responder(args.jid, args.password) - xmpp.register_plugin('OurPlugin', module=example_plugin) - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - import logging - from argparse import ArgumentParser - from getpass import getpass - import time - - import slixmpp - from slixmpp.xmlstream import ET - - import example_plugin - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - - def start(self, event): - self.send_presence() - self.get_roster() - - self.disconnect_counter = 5 - - self.send_example_iq(self.to) - # Info_inside_tag - - self.send_example_message(self.to) - # Info_inside_tag_message - - self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag - - string = 'Info_inside_tag' - et = ET.fromstring(string) - self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag - - self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found - - self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - - - def example_tag_result_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() - - def example_tag_error_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() - - def send_example_iq(self, to): - iq = self.make_iq(ito=to, itype="get") - iq['example_tag'].set_boolean(True) - iq['example_tag'].set_some_string("Another_string") - iq['example_tag'].set_text("Info_inside_tag") - iq.send() - - def send_example_message(self, to): - msg = self.make_message(mto=to) - msg['example_tag'].set_boolean(True) - msg['example_tag'].set_some_string("Message string") - msg['example_tag'].set_text("Info_inside_tag_message") - msg.send() - - def send_example_iq_tag_from_file(self, to, path): - iq = self.make_iq(ito=to, itype="get", id=2) - iq['example_tag'].setup_from_file(path) - - iq.send() - - def send_example_iq_tag_from_element_tree(self, to, et): - iq = self.make_iq(ito=to, itype="get", id=3) - iq['example_tag'].setup_from_lxml(et) - - iq.send() - - def send_example_iq_to_get_error(self, to): - iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) - iq.send() - - def send_example_iq_tag_from_string(self, to, string): - iq = self.make_iq(ito=to, itype="get", id=5) - iq['example_tag'].setup_from_string(string) - - iq.send() - - if __name__ == '__main__': - parser = ArgumentParser(description=Sender.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message/iq to") - parser.add_argument("--path", dest="path", - help="path to load example_tag content") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Sender(args.jid, args.password, args.to, args.path) - xmpp.register_plugin('OurPlugin', module=example_plugin) - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - - - -Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). - -Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typy napisowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. - -.. code-block:: python - - #File: $WORKDIR/example/example_plugin.py - - #(...) - - class ExampleTag(ElementBase): - - #(...) - - def add_inside_tag(self, tag, attributes, text=""): - #Gdy chcemy dodać tagi wewnętrzne do naszego taga, to jest prosty przykład jak to zrobić: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z naszym wewnętrznym tagiem, na przykład: - itemXML.attrib.update(attributes) #~ Przypisujemy zdefiniowane atrybuty, na przykład: - itemXML.text = text #~ Dodajemy text wewnątrz tego tagu: our_text - self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z naszym tagiem `example_tag`. - -Kompletny kod z tutorialu -------------------------- - -W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angielskim. - -.. code-block:: python - - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal - #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") - - -.. code-block:: python - - #File: $WORKDIR/example/example_plugin.py - - import logging - - from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - - from slixmpp import Iq - from slixmpp import Message - - from slixmpp.plugins.base import BasePlugin - - from slixmpp.xmlstream.handler import Callback - from slixmpp.xmlstream.matcher import StanzaPath - - log = logging.getLogger(__name__) - - class OurPlugin(BasePlugin): - def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. - self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. - - namespace = ExampleTag.namespace - self.xmpp.register_handler( - Callback('ExampleGet Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag - self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - - self.xmpp.register_handler( - Callback('ExampleResult Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag - self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - - self.xmpp.register_handler( - Callback('ExampleError Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag - self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - - self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag',##~ Name of this Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag - self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - - register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - - # All iq types are: get, set, error, result - def __handle_get_iq(self, iq): - if iq.get_some_string is None: - error = iq.reply(clear=False) - error["type"] = "error" - error["error"]["condition"] = "missing-data" - error["error"]["text"] = "Without some_string value returns error." - error.send() - # Do something with received iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - - def __handle_result_iq(self, iq): - # Do something with received iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - - def __handle_error_iq(self, iq): - # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - - def __handle_message(self, msg): - # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. - - class ExampleTag(ElementBase): - name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace - - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. - - interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - - def setup_from_string(self, string): - """Initialize tag element from string""" - et_extension_tag_xml = ET.fromstring(string) - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_file(self, path): - """Initialize tag element from file containing adjusted data""" - et_extension_tag_xml = ET.parse(path).getroot() - self.setup_from_lxml(et_extension_tag_xml) - - def setup_from_lxml(self, lxml): - """Add ET data to self xml structure.""" - self.xml.attrib.update(lxml.attrib) - self.xml.text = lxml.text - self.xml.tail = lxml.tail - for inner_tag in lxml: - self.xml.append(inner_tag) - - def setup_from_dict(self, data): - #There should keys should be also validated - self.xml.attrib.update(data) - - def get_boolean(self): - return self.xml.attrib.get("boolean", None) - - def get_some_string(self): - return self.xml.attrib.get("some_string", None) - - def get_text(self, text): - return self.xml.text - - def set_boolean(self, boolean): - self.xml.attrib['boolean'] = str(boolean) - - def set_some_string(self, some_string): - self.xml.attrib['some_string'] = some_string - - def set_text(self, text): - self.xml.text = text - - def fill_interfaces(self, boolean, some_string): - #Some validation if it is necessary - self.set_boolean(boolean) - self.set_some_string(some_string) - - def add_inside_tag(self, tag, attributes, text=""): - #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: - itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: - itemXML.text = text #~ Fill field inside tag, for example: our_text - self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. - - -~ - -.. code-block:: python - - #File: $WORKDIR/example/sender.py - - import logging - from argparse import ArgumentParser - from getpass import getpass - import time - - import slixmpp - from slixmpp.xmlstream import ET - - import example_plugin - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - - def start(self, event): - # Two, not required methods, but allows another users to see us available, and receive that information. - self.send_presence() - self.get_roster() - - self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq - - self.send_example_iq(self.to) - # Info_inside_tag - - self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag - - self.send_example_message(self.to) - # Info_inside_tag_message - - self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag - - string = 'Info_inside_tag' - et = ET.fromstring(string) - self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag - - self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found - - self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - - - def example_tag_result_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - - def example_tag_error_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - - def send_example_iq(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get") - iq['example_tag'].set_boolean(True) - iq['example_tag'].set_some_string("Another_string") - iq['example_tag'].set_text("Info_inside_tag") - iq.send() - - def send_example_iq_with_inner_tag(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=1) - iq['example_tag'].set_some_string("Another_string") - iq['example_tag'].set_text("Info_inside_tag") - - inner_attributes = {"first_field": "1", "secound_field": "2"} - iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - - iq.send() - - def send_example_message(self, to): - #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - msg = self.make_message(mto=to) - msg['example_tag'].set_boolean(True) - msg['example_tag'].set_some_string("Message string") - msg['example_tag'].set_text("Info_inside_tag_message") - msg.send() - - def send_example_iq_tag_from_file(self, to, path): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=2) - iq['example_tag'].setup_from_file(path) - - iq.send() - - def send_example_iq_tag_from_element_tree(self, to, et): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=3) - iq['example_tag'].setup_from_lxml(et) - - iq.send() - - def send_example_iq_to_get_error(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. - iq.send() - - def send_example_iq_tag_from_string(self, to, string): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=5) - iq['example_tag'].setup_from_string(string) - - iq.send() - - if __name__ == '__main__': - parser = ArgumentParser(description=Sender.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message/iq to") - parser.add_argument("--path", dest="path", - help="path to load example_tag content") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Sender(args.jid, args.password, args.to, args.path) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - -~ - -.. code-block:: python - - #File: $WORKDIR/example/responder.py - - import logging - from argparse import ArgumentParser - from getpass import getpass - import time - - import slixmpp - from slixmpp.xmlstream import ET - - import example_plugin - - class Sender(slixmpp.ClientXMPP): - def __init__(self, jid, password, to, path): - slixmpp.ClientXMPP.__init__(self, jid, password) - - self.to = to - self.path = path - - self.add_event_handler("session_start", self.start) - self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) - self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - - def start(self, event): - # Two, not required methods, but allows another users to see us available, and receive that information. - self.send_presence() - self.get_roster() - - self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq - - self.send_example_iq(self.to) - # Info_inside_tag - - self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag - - self.send_example_message(self.to) - # Info_inside_tag_message - - self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag - - string = 'Info_inside_tag' - et = ET.fromstring(string) - self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag - - self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found - - self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag - - - def example_tag_result_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - - def example_tag_error_iq(self, iq): - self.disconnect_counter -= 1 - logging.info(str(iq)) - if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - - def send_example_iq(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get") - iq['example_tag'].set_boolean(True) - iq['example_tag'].set_some_string("Another_string") - iq['example_tag'].set_text("Info_inside_tag") - iq.send() - - def send_example_iq_with_inner_tag(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=1) - iq['example_tag'].set_some_string("Another_string") - iq['example_tag'].set_text("Info_inside_tag") - - inner_attributes = {"first_field": "1", "secound_field": "2"} - iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - - iq.send() - - def send_example_message(self, to): - #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - msg = self.make_message(mto=to) - msg['example_tag'].set_boolean(True) - msg['example_tag'].set_some_string("Message string") - msg['example_tag'].set_text("Info_inside_tag_message") - msg.send() - - def send_example_iq_tag_from_file(self, to, path): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=2) - iq['example_tag'].setup_from_file(path) - - iq.send() - - def send_example_iq_tag_from_element_tree(self, to, et): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=3) - iq['example_tag'].setup_from_lxml(et) - - iq.send() - - def send_example_iq_to_get_error(self, to): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. - iq.send() - - def send_example_iq_tag_from_string(self, to, string): - #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) - iq = self.make_iq(ito=to, itype="get", id=5) - iq['example_tag'].setup_from_string(string) - - iq.send() - - if __name__ == '__main__': - parser = ArgumentParser(description=Sender.__doc__) - - parser.add_argument("-q", "--quiet", help="set logging to ERROR", - action="store_const", dest="loglevel", - const=logging.ERROR, default=logging.INFO) - parser.add_argument("-d", "--debug", help="set logging to DEBUG", - action="store_const", dest="loglevel", - const=logging.DEBUG, default=logging.INFO) - - parser.add_argument("-j", "--jid", dest="jid", - help="JID to use") - parser.add_argument("-p", "--password", dest="password", - help="password to use") - parser.add_argument("-t", "--to", dest="to", - help="JID to send the message/iq to") - parser.add_argument("--path", dest="path", - help="path to load example_tag content") - - args = parser.parse_args() - - logging.basicConfig(level=args.loglevel, - format=' %(name)s - %(levelname)-8s %(message)s') - - if args.jid is None: - args.jid = input("Username: ") - if args.password is None: - args.password = getpass("Password: ") - - xmpp = Sender(args.jid, args.password, args.to, args.path) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - - xmpp.connect() - try: - xmpp.process() - except KeyboardInterrupt: - try: - xmpp.disconnect() - except: - pass - -~ - -.. code-block:: python - - #File: $WORKDIR/test_example_tag.xml -.. code-block:: xml - - Info_inside_tag - - -Źródła i bibliogarfia ---------------------- - -Slixmpp project description: - -* https://pypi.org/project/slixmpp/ - -Official web documentation: - -* https://slixmpp.readthedocs.io/ - - -Official pdf documentation: - -* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf - -Note: Dokumentacje w formie Web i PDF mają pewne różnice, pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst new file mode 100644 index 00000000..ff6cd0b9 --- /dev/null +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -0,0 +1,1785 @@ +Jak stworzyć własny plugin rozszerzający obiekty Message i Iq w Slixmpp +======================================================================= + +Wstęp i wymagania +----------------- + +* `'python3'` + +Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6 lub nowszej. +Dla wstecznej kompatybilności z wcześniejszymi wersjami należy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. + +Instalacja dla Ubuntu linux: + +.. code-block:: bash + + sudo apt-get install python3.6 + +* `'slixmpp'` +* `'argparse'` +* `'logging'` +* `'subprocess'` +* `'threading'` + +Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdaża się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. + +.. code-block:: python + + python3 --version + python3 -c "import slixmpp; print(slixmpp.__version__)" + python3 -c "import argparse; print(argparse.__version__)" + python3 -c "import logging; print(logging.__version__)" + python3 -m subprocess + python3 -m threading + +Wynik w terminalu: + +.. code-block:: bash + + ~ $ python3 --version + Python 3.8.0 + ~ $ python3 -c "import slixmpp; print(slixmpp.__version__)" + 1.4.2 + ~ $ python3 -c "import argparse; print(argparse.__version__)" + 1.1 + ~ $ python3 -c "import logging; print(logging.__version__)" + 0.5.1.2 + ~ $ python3 -m subprocess # Nie powinno nic zwrócić + ~ $ python3 -m threading # Nie powinno nic zwrócić + +Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, należy je zainstalować zgodnie z przykładem poniżej: + +Instalacja Ubuntu linux: + +.. code-block:: bash + + pip3 install slixmpp + #or + easy_install slixmpp + +Jeśli jakaś biblioteka zwróci NameError, należy zainstalować pakiet ponownie. + +* `Konta dla Jabber` + +Do testowania niezbędne będą dwa prywatne konta jabbera. +Można je stworzyć na jednym z dostępnych darmowych serwerów: + +https://www.google.com/search?q=jabber+server+list + +Skrypt uruchamiający klientów +----------------------------- + +Skrypt pozwalający testować klientów powinien zostać stworzony poza lokalizacją projektu. Pozwoli to szybko sprawdzać wyniki skryptów oraz uniemożliwi przypadkowe wysłanie swoich danych na gita. + +Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/usr/bin'` i nadać mu uprawnienia wykonywawcze: + +.. code-block:: bash + + /usr/bin $ chmod 711 test_slixmpp + +Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawiera prostą strukturę, która pozwoli nam zapisać dane logowania. + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala + #~ prefix = "xterm -e" + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Pamiętaj o nadaniu praw do wykonywania (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + +Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. + +Skrypt uruchomieniowy powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. + +W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko okreslić, który klient co zwraca, bądź który powoduje błąd. + +Stworzenie klienta i pluginu +---------------------------- + +W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostepność online. + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin. + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + self.send_presence() + self.get_roster() + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w lokalizacji dostepnej dla klientów (domyślnie w tej samej, co skrypty klientów). + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin + self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin poprzez dodanie tego do `slixmpp/plugins/__init__.py`, w polu `__all__` z prefixem xep 'xep_OPE'. + + namespace = ExampleTag.namespace + + + class ExampleTag(ElementBase): + name = "example_tag" ##~ Nazwa głównego tagu dla XML w tym rozszerzeniu. + namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: + + plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` staje się nazwą pluginu i powinno być takie samo jak name. + + interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów elementu które mogą być użyte w elemencie. Na przykład `stanza_object['example_tag']` poda informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest elementu. + +Jeżeli powyższy plugin nie jest w domyślnej lokalizacji, a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu: + +.. code-block:: bash + + ln -s $Path_to_example_plugin_py $Path_to_clients_destinations + +Jeszcze innym wyjściem jest import relatywny z użyciem kropek '.' aby dostać się do właściwej ścieżki. + +Pierwsze uruchomienie i przechwytywanie eventów +----------------------------------------------- + +Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisany event `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. + +W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a nastepnie użyć komendy `'test_slixmpp'`. + +Metoda `'def start(self, event):'` powinna wyglądać tak: + +.. code-block:: python + + def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + logging.info("I'm running") + #<<<<<<<<<<<< + +Jeżeli oba klienty uruchomiły się poprawnie, można zakomentować tą linię. + +Budowanie obiektu Message +------------------------- + +Wysyłający powinien posiadać informację o tym, do kogo należy wysłać wiadomość. Nazwę i scieżkę odbiorcy można przekazać, na przykład, przez argumenty wywołania skryptu w lini komend. W poniższym przykładzie, są one trzymane w atrybucie `'self.to'`. + +Przykład: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + # Domyślnie mtype == "chat" if None; + msg = self.make_message(mto=to, mbody=body) + msg.send() + #<<<<<<<<<<<< + +W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. + +Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie został przypisany żaden inny event. Przykład takiego kodu: + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + + #>>>>>>>>>>>> + self.add_event_handler("message", self.message) + #<<<<<<<<<<<< + + def start(self, event): + # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def message(self, msg): + #Pokazuje cały XML wiadomości + logging.info(msg) + #Pokazuje wyłącznie pole 'body' wiadomości + logging.info(msg['body']) + #<<<<<<<<<<<< +//TODO from here +Rozszerzenie Message o nasz tag ++++++++++++++++++++++++++++++++ + +Aby rozszerzyć obiekt Message wybranym tagiem ze specjalnymi polami, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ String do przeczytania przez ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py`, do metody `__all__` z 'xep_OPE'. + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + register_stanza_plugin(Message, ExampleTag) ##~ Rejetrujemy rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. + #<<<<<<<<<<<< + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + #<<<<<<<<<<<< + +Teraz dzięki rejestracji tagu, możemy rozszerzyć wiadomość. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + self.send_example_message(self.to, "example_message") + + def send_example_message(self, to, body): + msg = self.make_message(mto=to, mbody=body) + #>>>>>>>>>>>> + msg['example_tag'].set_some_string("Work!") + logging.info(msg) + #<<<<<<<<<<<< + msg.send() + +Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , wraz z napisem `'Work'` oraz nadanym namespace. + +Nadanie oddzielnego sygnału dla rozszerzonej wiadomości ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', ##~ Nazwa tego Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytujemy wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag + self.__handle_message)) ##~ Metoda do której przypisujemy przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. + #<<<<<<<<<<<< + register_stanza_plugin(Message, ExampleTag) + + #>>>>>>>>>>>> + def __handle_message(self, msg): + # Tu możemy coś zrobić z przechwyconą wiadomością zanim trafi do klienta. + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. + #<<<<<<<<<<<< + +Obiekt StanzaPath powinien być poprawnie zainicjalizowany, według schematu: +`'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` + +* Dla NAZWA_OBIEKTU można użyć `'message'` lub `'iq'`. +* Dla TYP_OBIEKTU, jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'` +* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można sprecyzować typ spośród: `'get, set, error or result'` +* Dla NAMESPACE to powinien być namespace zgodny z rozszerzeniem tagu. +* TAG powinien zawierać tag, tutaj: `'example_tag'`. + +Teraz, rogram przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też, jak w programowaniu agentowym, sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomośc jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + + def start(self, event): + self.send_presence() + self.get_roster() + #>>>>>>>>>>>> + self.send_example_message(self.to, "example_message", "example_string") + + def send_example_message(self, to, body, some_string=""): + msg = self.make_message(mto=to, mbody=body) + if some_string: + msg['example_tag'].set_some_string(some_string) + msg.send() + #<<<<<<<<<<<< + +Należy zapamiętać linię pluginu: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku responder.py. Tutaj: `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja handlera + #<<<<<<<<<<<< + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + def example_tag_message(self, msg): + logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej. Może zostać zwrócona odpowiedź, ale nie jest to sposób komunikacji maszyn, więc żaden timeout error nie zostanie wywołany gdy nie zostanie zwrócona. (W przypadku Iq jest inaczej). + #<<<<<<<<<<<< + +Teraz można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. +Natomiast kolejny obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. + +Użyteczne metody i inne +----------------------- + +Modyfikacja przykładowego obiektu `Message` na `Iq`. +++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o nasz tag"`. Tym razem, przykład będzie zawierał kilka typów Iq z oddzielnymi typami. Poprawia to czytelność kodu oraz weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id do wysyłającego wraz z odpowiedzią. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + #>>>>>>>>>>>> + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), + self.__handle_get_iq)) + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), + self.__handle_result_iq)) + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), + self.__handle_error_iq)) + #<<<<<<<<<<<< + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', + StanzaPath(f'message/{{{namespace}}}example_tag'), + self.__handle_message)) + + #>>>>>>>>>>>> + register_stanza_plugin(Iq, ExampleTag) + #<<<<<<<<<<<< + register_stanza_plugin(Message, ExampleTag) + + #>>>>>>>>>>>> + # Wszystkie możliwe typy Iq to: get, set, error, result + def __handle_get_iq(self, iq): + self.xmpp.event('example_tag_get_iq', iq) + + def __handle_result_iq(self, iq): + self.xmpp.event('example_tag_result_iq', iq) + + def __handle_error_iq(self, iq): + self.xmpp.event('example_tag_error_iq', iq) + #<<<<<<<<<<<< + + def __handle_message(self, msg): + self.xmpp.event('example_tag_message', msg) + +Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_message", self.example_tag_message) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem. + logging.info(str(iq)) + reply = iq.reply(clear=False) + reply.send() + #<<<<<<<<<<<< + +Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, co jest zawarte wewnątrz Iq (z kilkoma wyjątkami) powinno zostać zdefiniowane ponownie. Jedyne informacje które zostaną w Iq po metodzie reply, nawet gdy parametr clean jest ustawiony na True, to ID tego Iq oraz JID wysyłającego. + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + #>>>>>>>>>>>> + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + #<<<<<<<<<<<< + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.send_example_iq(self.to) + # Info_inside_tag + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" + iq['example_tag']['some_string'] = "Another_string" + iq['example_tag'].text = "Info_inside_tag" + iq.send() + #<<<<<<<<<<<< + + #>>>>>>>>>>>> + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + + def example_tag_error_iq(self, iq): + logging.info(str(iq)) + #<<<<<<<<<<<< + +Dostęp do elementów ++++++++++++++++++++ + +Jest kilka możliwości dostania się do pól wewnątrz Message lub Iq. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + #... + def example_tag_result_iq(self, iq): + logging.info(str(iq)) + #>>>>>>>>>>>> + logging.info(iq['id']) + logging.info(iq.get('id')) + logging.info(iq['example_tag']['boolean']) + logging.info(iq['example_tag'].get('boolean')) + logging.info(iq.get('example_tag').get('boolean')) + #<<<<<<<<<<<< + +Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wymagane jest określanie tagu, którego dotyczy. Dodatkową zaletą jest fakt niejednolitego dostępu, na przykład do parametru `'text'` między rozpoczęciem a zakończeniem tagu. Pokazuje to poniższy przykład, ujednolicając metody obiektowych getterów i setterów. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + #<<<<<<<<<<<< + +Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. + +Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo, kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def send_example_iq(self, to): + iq = self.make_iq(ito=to, itype="get") + iq['example_tag']['boolean'] = "True" #Przypisanie wprost + #>>>>>>>>>>>> + iq['example_tag'].set_some_string("Another_string") #Przypisanie poprzez setter + iq['example_tag'].set_text("Info_inside_tag") + #<<<<<<<<<<<< + iq.send() + +Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + #... + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + #... + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + #>>>>>>>>>>>> + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + #<<<<<<<<<<<< + +Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): + +.. code-block:: xml + + #File: $WORKDIR/test_example_tag.xml + + Info_inside_tag + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + #... + from slixmpp.xmlstream import ET + #... + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + self.send_presence() + self.get_roster() + + #>>>>>>>>>>>> + self.disconnect_counter = 3 # Ta zmienna służy tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. + + def send_example_iq_tag_from_file(self, to, path): + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + #<<<<<<<<<<<< + +Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa tak, jak powinno. + +Łatwość użycia pluginu dla programistów ++++++++++++++++++++++++++++++++++++++++ + +Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. +Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. + +Poniżej przykład kodu podyktowanego tymi zasadami: + +.. code-block:: python + + #File: $WORKDIR/example/example plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" + self.xep = "ope" + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), + self.__handle_get_iq)) + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), + self.__handle_result_iq)) + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), + self.__handle_error_iq)) + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag', + StanzaPath(f'message/{{{namespace}}}example_tag'), + self.__handle_message)) + + register_stanza_plugin(Iq, ExampleTag) + register_stanza_plugin(Message, ExampleTag) + + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + self.xmpp.event('example_tag_get_iq', iq) + + def __handle_result_iq(self, iq): + self.xmpp.event('example_tag_result_iq', iq) + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) + + def __handle_message(self, msg): + self.xmpp.event('example_tag_message', msg) + + class ExampleTag(ElementBase): + name = "example_tag" + namespace = "https://example.net/our_extension" + + plugin_attrib = "example_tag" + + interfaces = {"boolean", "some_string"} + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + self.set_boolean(boolean) + self.set_some_string(some_string) + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + + import slixmpp + import example_plugin + + class Responder(slixmpp.ClientXMPP): + def __init__(self, jid, password): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) + self.add_event_handler("example_tag_message", self.example_tag_message) + + def start(self, event): + self.send_presence() + self.get_roster() + + def example_tag_get_iq(self, iq): + logging.info(iq) + reply = iq.reply() + reply["example_tag"].fill_interfaces(True, "Reply_string") + reply.send() + + def example_tag_message(self, msg): + logging.info(msg) + + + if __name__ == '__main__': + parser = ArgumentParser(description=Responder.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message to") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Responder(args.jid, args.password) + xmpp.register_plugin('OurPlugin', module=example_plugin) + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + self.send_presence() + self.get_roster() + + self.disconnect_counter = 5 + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() + + def send_example_iq(self, to): + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_message(self, to): + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + + + +Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ + +Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). + +Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typy napisowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + #(...) + + class ExampleTag(ElementBase): + + #(...) + + def add_inside_tag(self, tag, attributes, text=""): + #Gdy chcemy dodać tagi wewnętrzne do naszego taga, to jest prosty przykład jak to zrobić: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z naszym wewnętrznym tagiem, na przykład: + itemXML.attrib.update(attributes) #~ Przypisujemy zdefiniowane atrybuty, na przykład: + itemXML.text = text #~ Dodajemy text wewnątrz tego tagu: our_text + self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z naszym tagiem `example_tag`. + +Kompletny kod z tutorialu +------------------------- + +W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angielskim. + +.. code-block:: python + + #!/usr/bin/python3 + #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + + import subprocess + import threading + import time + + def start_shell(shell_string): + subprocess.run(shell_string, shell=True, universal_newlines=True) + + if __name__ == "__main__": + #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal + #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal + prefix = "" + #~ postfix = " -d" # Debug + #~ postfix = " -q" # Quiet + postfix = "" + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about rights to run your python files. (`chmod +x ./file.py`) + SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ + " -t {responder_jid} --path {example_file} {postfix}" + + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ + " -p {responder_password} {postfix}" + + try: + responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) + sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) + responder.start() + sender.start() + while True: + time.sleep(0.5) + except: + print ("Error: unable to start thread") + + +.. code-block:: python + + #File: $WORKDIR/example/example_plugin.py + + import logging + + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin + + from slixmpp import Iq + from slixmpp import Message + + from slixmpp.plugins.base import BasePlugin + + from slixmpp.xmlstream.handler import Callback + from slixmpp.xmlstream.matcher import StanzaPath + + log = logging.getLogger(__name__) + + class OurPlugin(BasePlugin): + def plugin_init(self): + self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. + self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. + + namespace = ExampleTag.namespace + self.xmpp.register_handler( + Callback('ExampleGet Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleResult Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleError Event:example_tag', ##~ Name of this Callback + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. + + self.xmpp.register_handler( + Callback('ExampleMessage Event:example_tag',##~ Name of this Callback + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag + self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. + + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + + # All iq types are: get, set, error, result + def __handle_get_iq(self, iq): + if iq.get_some_string is None: + error = iq.reply(clear=False) + error["type"] = "error" + error["error"]["condition"] = "missing-data" + error["error"]["text"] = "Without some_string value returns error." + error.send() + # Do something with received iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_result_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_error_iq(self, iq): + # Do something with received iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. + + def __handle_message(self, msg): + # Do something with received message + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. + + class ExampleTag(ElementBase): + name = "example_tag" ##~ The name of the root XML element of that extension. + namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + + def setup_from_string(self, string): + """Initialize tag element from string""" + et_extension_tag_xml = ET.fromstring(string) + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_file(self, path): + """Initialize tag element from file containing adjusted data""" + et_extension_tag_xml = ET.parse(path).getroot() + self.setup_from_lxml(et_extension_tag_xml) + + def setup_from_lxml(self, lxml): + """Add ET data to self xml structure.""" + self.xml.attrib.update(lxml.attrib) + self.xml.text = lxml.text + self.xml.tail = lxml.tail + for inner_tag in lxml: + self.xml.append(inner_tag) + + def setup_from_dict(self, data): + #There should keys should be also validated + self.xml.attrib.update(data) + + def get_boolean(self): + return self.xml.attrib.get("boolean", None) + + def get_some_string(self): + return self.xml.attrib.get("some_string", None) + + def get_text(self, text): + return self.xml.text + + def set_boolean(self, boolean): + self.xml.attrib['boolean'] = str(boolean) + + def set_some_string(self, some_string): + self.xml.attrib['some_string'] = some_string + + def set_text(self, text): + self.xml.text = text + + def fill_interfaces(self, boolean, some_string): + #Some validation if it is necessary + self.set_boolean(boolean) + self.set_some_string(some_string) + + def add_inside_tag(self, tag, attributes, text=""): + #If we want to fill with additionaly tags our element, then we can do it that way for example: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: + itemXML.text = text #~ Fill field inside tag, for example: our_text + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + + +~ + +.. code-block:: python + + #File: $WORKDIR/example/sender.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/example/responder.py + + import logging + from argparse import ArgumentParser + from getpass import getpass + import time + + import slixmpp + from slixmpp.xmlstream import ET + + import example_plugin + + class Sender(slixmpp.ClientXMPP): + def __init__(self, jid, password, to, path): + slixmpp.ClientXMPP.__init__(self, jid, password) + + self.to = to + self.path = path + + self.add_event_handler("session_start", self.start) + self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) + self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) + + def start(self, event): + # Two, not required methods, but allows another users to see us available, and receive that information. + self.send_presence() + self.get_roster() + + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + + self.send_example_iq(self.to) + # Info_inside_tag + + self.send_example_iq_with_inner_tag(self.to) + # Info_inside_tag + + self.send_example_message(self.to) + # Info_inside_tag_message + + self.send_example_iq_tag_from_file(self.to, self.path) + # Info_inside_tag + + string = 'Info_inside_tag' + et = ET.fromstring(string) + self.send_example_iq_tag_from_element_tree(self.to, et) + # Info_inside_tag + + self.send_example_iq_to_get_error(self.to) + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found + + self.send_example_iq_tag_from_string(self.to, string) + # Info_inside_tag + + + def example_tag_result_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def example_tag_error_iq(self, iq): + self.disconnect_counter -= 1 + logging.info(str(iq)) + if not self.disconnect_counter: + self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get") + iq['example_tag'].set_boolean(True) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + iq.send() + + def send_example_iq_with_inner_tag(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=1) + iq['example_tag'].set_some_string("Another_string") + iq['example_tag'].set_text("Info_inside_tag") + + inner_attributes = {"first_field": "1", "secound_field": "2"} + iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) + + iq.send() + + def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) + msg = self.make_message(mto=to) + msg['example_tag'].set_boolean(True) + msg['example_tag'].set_some_string("Message string") + msg['example_tag'].set_text("Info_inside_tag_message") + msg.send() + + def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=2) + iq['example_tag'].setup_from_file(path) + + iq.send() + + def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=3) + iq['example_tag'].setup_from_lxml(et) + + iq.send() + + def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=4) + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq.send() + + def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) + iq = self.make_iq(ito=to, itype="get", id=5) + iq['example_tag'].setup_from_string(string) + + iq.send() + + if __name__ == '__main__': + parser = ArgumentParser(description=Sender.__doc__) + + parser.add_argument("-q", "--quiet", help="set logging to ERROR", + action="store_const", dest="loglevel", + const=logging.ERROR, default=logging.INFO) + parser.add_argument("-d", "--debug", help="set logging to DEBUG", + action="store_const", dest="loglevel", + const=logging.DEBUG, default=logging.INFO) + + parser.add_argument("-j", "--jid", dest="jid", + help="JID to use") + parser.add_argument("-p", "--password", dest="password", + help="password to use") + parser.add_argument("-t", "--to", dest="to", + help="JID to send the message/iq to") + parser.add_argument("--path", dest="path", + help="path to load example_tag content") + + args = parser.parse_args() + + logging.basicConfig(level=args.loglevel, + format=' %(name)s - %(levelname)-8s %(message)s') + + if args.jid is None: + args.jid = input("Username: ") + if args.password is None: + args.password = getpass("Password: ") + + xmpp = Sender(args.jid, args.password, args.to, args.path) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + + xmpp.connect() + try: + xmpp.process() + except KeyboardInterrupt: + try: + xmpp.disconnect() + except: + pass + +~ + +.. code-block:: python + + #File: $WORKDIR/test_example_tag.xml +.. code-block:: xml + + Info_inside_tag + + +Źródła i bibliogarfia +--------------------- + +Slixmpp project description: + +* https://pypi.org/project/slixmpp/ + +Official web documentation: + +* https://slixmpp.readthedocs.io/ + + +Official pdf documentation: + +* https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf + +Note: Dokumentacje w formie Web i PDF mają pewne różnice, pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. -- cgit v1.2.3 From c8d802a6c78c91878971f5ef6ac7bb86c7f060ba Mon Sep 17 00:00:00 2001 From: Paulina Date: Sun, 15 Mar 2020 17:27:47 +0100 Subject: Correction and editing of the tutorials. [95 %] English version [95 %] Polish version [100%] Both version consistency check [80 %] Final sanity check + formating --- ...make_plugin_extension_for_message_and_iq.pl.rst | 160 ++++++++++++--------- .../make_plugin_extension_for_message_and_iq.rst | 122 ++++++++-------- 2 files changed, 152 insertions(+), 130 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst index f138311c..5d774cff 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -1,5 +1,5 @@ Jak stworzyć własny plugin rozszerzający obiekty Message i Iq w Slixmpp -======================================================================= +==================================================================== Wstęp i wymagania ----------------- @@ -61,8 +61,7 @@ Jeśli jakaś biblioteka zwróci NameError, należy zainstalować pakiet ponowni * `Konta dla Jabber` -Do testowania niezbędne będą dwa prywatne konta jabbera. -Można je stworzyć na jednym z dostępnych darmowych serwerów: +Do testowania niezbędne będą dwa prywatne konta jabbera. Można je stworzyć na jednym z dostępnych darmowych serwerów: https://www.google.com/search?q=jabber+server+list @@ -293,7 +292,7 @@ Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w class ExampleTag(ElementBase): - name = "example_tag" ##~ Nazwa głównego tagu dla XML w tym rozszerzeniu. + name = "example_tag" ##~ Nazwa głównego pliku XML w tym rozszerzeniu. namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` staje się nazwą pluginu i powinno być takie samo jak name. @@ -359,7 +358,7 @@ Przykład: def send_example_message(self, to, body): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Domyślnie mtype == "chat" if None; + # Domyślnie mtype == "chat"; msg = self.make_message(mto=to, mbody=body) msg.send() #<<<<<<<<<<<< @@ -396,7 +395,7 @@ Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: #<<<<<<<<<<<< Rozszerzenie Message o nowy tag -+++++++++++++++++++++++++++++++ +------------------------- Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message: @@ -415,8 +414,8 @@ Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestro #<<<<<<<<<<<< class ExampleTag(ElementBase): - name = "example_tag" ##~ Nazwa pliku XML dla tego rozszerzenia.. - namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . + name = "example_tag" ##~ Nazwa głównego pliku XML dla tego rozszerzenia.. + namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. @@ -464,7 +463,7 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , oraz z napisem `'Work'` i nadanym namespace. Nadanie oddzielnego sygnału dla rozszerzonej wiadomości -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------- Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). @@ -480,10 +479,9 @@ Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa namespace = ExampleTag.namespace self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', ##~ Nazwa tego Callback + Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytuje wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag self.__handle_message)) ##~ Metoda do której zostaje przypisany przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. - register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. def __handle_message(self, msg): @@ -560,8 +558,8 @@ Natomiast obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwa Użyteczne metody i inne ----------------------- -Modyfikacja przykładowego obiektu `Message` na obiekt `Iq`. -++++++++++++++++++++++++++++++++++++++++++++++++++++ +Modyfikacja przykładowego obiektu `Message` na obiekt `Iq` +------------------------- Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o tag"`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). @@ -661,6 +659,7 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, #<<<<<<<<<<<< def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online self.send_presence() self.get_roster() @@ -688,7 +687,7 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, #<<<<<<<<<<<< Dostęp do elementów -+++++++++++++++++++ +------------------------- Jest kilka możliwości dostania się do pól wewnątrz Message lub Iq. Po pierwsze, z poziomu klienta, można dostać zawartość jak ze słownika: @@ -715,12 +714,12 @@ Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wym #File: $WORKDIR/example/example plugin.py class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" + name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. + namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - interfaces = {"boolean", "some_string"} + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. #>>>>>>>>>>>> def get_some_string(self): @@ -756,6 +755,7 @@ Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewn self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") iq['example_tag']['boolean'] = "True" #Przypisanie wprost #>>>>>>>>>>>> @@ -765,7 +765,7 @@ Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewn iq.send() Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------- Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. @@ -778,12 +778,12 @@ Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku al #... class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" + name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. + namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - interfaces = {"boolean", "some_string"} + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. #>>>>>>>>>>>> def setup_from_string(self, string): @@ -833,6 +833,7 @@ Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online self.send_presence() self.get_roster() @@ -857,18 +858,21 @@ Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) iq.send() def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) iq.send() def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) @@ -877,8 +881,8 @@ Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa tak, jak powinno. -Łatwość użycia pluginu dla programistów -+++++++++++++++++++++++++++++++++++++++ +Łatwość użycia pluginu dla programistów +-------------------------------------- Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. @@ -905,33 +909,34 @@ Poniżej przykład kodu podyktowanego tymi zasadami: class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" - self.xep = "ope" + self.description = "OurPluginExtension" ##~ Tekst czytelny dla człowieka oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ Tekst czytelny dla człowieka oraz do znalezienia pluginu przez inny plugin poprzez dodanie go do `slixmpp/plugins/__init__.py` do funkcji `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace self.xmpp.register_handler( - Callback('ExampleGet Event:example_tag', - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), - self.__handle_get_iq)) + Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. self.xmpp.register_handler( - Callback('ExampleResult Event:example_tag', - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), - self.__handle_result_iq)) + Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. self.xmpp.register_handler( - Callback('ExampleError Event:example_tag', - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), - self.__handle_error_iq)) + Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. self.xmpp.register_handler( - Callback('ExampleMessage Event:example_tag', - StanzaPath(f'message/{{{namespace}}}example_tag'), - self.__handle_message)) - - register_stanza_plugin(Iq, ExampleTag) - register_stanza_plugin(Message, ExampleTag) - + Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacku + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługije tylko Message z example_tag + self.__handle_message)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. + + register_stanza_plugin(Iq, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Iq. Bez tego, iq['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć podelementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć podelementów. + + # Wszystkie możliwe typy iq: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: error = iq.reply(clear=False) @@ -939,25 +944,28 @@ Poniżej przykład kodu podyktowanego tymi zasadami: error["error"]["condition"] = "missing-data" error["error"]["text"] = "Without some_string value returns error." error.send() - self.xmpp.event('example_tag_get_iq', iq) + # Zrób coś z otrzymanym Iq + self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. def __handle_result_iq(self, iq): - self.xmpp.event('example_tag_result_iq', iq) + # Zrób coś z otrzymanym Iq + self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. def __handle_error_iq(self, iq): - # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) + # Zrób coś z otrzymanym Iq + self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. def __handle_message(self, msg): - self.xmpp.event('example_tag_message', msg) + # Zrób coś z otrzymanym Message + self.xmpp.event('example_tag_message', msg) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. class ExampleTag(ElementBase): - name = "example_tag" - namespace = "https://example.net/our_extension" + name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. + namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - interfaces = {"boolean", "some_string"} + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. def setup_from_string(self, string): """Initialize tag element from string""" @@ -978,6 +986,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.xml.append(inner_tag) def setup_from_dict(self, data): + #Poprawnośc kluczy słownika powinna być sprawdzona self.xml.attrib.update(data) def get_boolean(self): @@ -999,6 +1008,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.xml.text = text def fill_interfaces(self, boolean, some_string): + #Jakaś walidacja, jeśli jest potrzebna self.set_boolean(boolean) self.set_some_string(some_string) @@ -1022,17 +1032,18 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.add_event_handler("example_tag_message", self.example_tag_message) def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online self.send_presence() self.get_roster() - def example_tag_get_iq(self, iq): + def example_tag_get_iq(self, iq): # Iq zawsze powinien odpowiedzieć. Jeżeli użytkownik jest offline, zostanie zrwócony error. logging.info(iq) reply = iq.reply() reply["example_tag"].fill_interfaces(True, "Reply_string") reply.send() def example_tag_message(self, msg): - logging.info(msg) + logging.info(msg) # Na Message można odpowiedzieć, ale nie trzeba. if __name__ == '__main__': @@ -1063,7 +1074,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: args.password = getpass("Password: ") xmpp = Responder(args.jid, args.password) - xmpp.register_plugin('OurPlugin', module=example_plugin) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPluggin jest nazwa klasy example_plugin xmpp.connect() try: @@ -1073,7 +1084,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: xmpp.disconnect() except: pass - + .. code-block:: python #File: $WORKDIR/example/sender.py @@ -1100,10 +1111,11 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online self.send_presence() self.get_roster() - self.disconnect_counter = 5 + self.disconnect_counter = 5 # Aplikacja rozłączy się po odebraniu takiej ilości odpowiedzi. self.send_example_iq(self.to) # Info_inside_tag @@ -1132,15 +1144,16 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() - + self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() - + self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. + def send_example_iq(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") iq['example_tag'].set_boolean(True) iq['example_tag'].set_some_string("Another_string") @@ -1148,6 +1161,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: iq.send() def send_example_message(self, to): + #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) msg['example_tag'].set_boolean(True) msg['example_tag'].set_some_string("Message string") @@ -1155,23 +1169,27 @@ Poniżej przykład kodu podyktowanego tymi zasadami: msg.send() def send_example_iq_tag_from_file(self, to, path): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) iq.send() def send_example_iq_tag_from_element_tree(self, to, et): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) iq.send() def send_example_iq_to_get_error(self, to): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) + iq['example_tag'].set_boolean(True) # Kiedy, aby otrzymać odpowiedż z błędem, potrzebny jest example_tag bez wartości bool. iq.send() def send_example_iq_tag_from_string(self, to, string): + #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) @@ -1207,7 +1225,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: args.password = getpass("Password: ") xmpp = Sender(args.jid, args.password, args.to, args.path) - xmpp.register_plugin('OurPlugin', module=example_plugin) + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy z example_plugin. xmpp.connect() try: @@ -1217,16 +1235,15 @@ Poniżej przykład kodu podyktowanego tymi zasadami: xmpp.disconnect() except: pass - Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ +-------------------------------------- -Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). +Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). W takim wypadku, aby stworzyć zagnieżdżony element można użyć funkcji 'append'. Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typy napisowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. - + .. code-block:: python #File: $WORKDIR/example/example_plugin.py @@ -1238,13 +1255,15 @@ Można powtórzyć poprzednie działania inicjalizując nowy element jak główn #(...) def add_inside_tag(self, tag, attributes, text=""): - #Gdy chcemy dodać tagi wewnętrzne do naszego taga, to jest prosty przykład jak to zrobić: + #Można rozszerzyć tag o tagi wewnętrzne do tagu, na przykład tak: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z naszym wewnętrznym tagiem, na przykład: itemXML.attrib.update(attributes) #~ Przypisujemy zdefiniowane atrybuty, na przykład: itemXML.text = text #~ Dodajemy text wewnątrz tego tagu: our_text self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z naszym tagiem `example_tag`. -Kompletny kod z tutorialu +Można też zrobić to samo używając słownika i nazw jako kluczy zagnieżdżonych elementów. W takim przypadku, pola funkcji powinny zostać przeniesione do ET. + +Kompletny kod tutorialu ------------------------- W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angielskim. @@ -1424,7 +1443,7 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text - self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. ~ @@ -1765,6 +1784,7 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel .. code-block:: python #File: $WORKDIR/test_example_tag.xml + .. code-block:: xml Info_inside_tag diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index 9c5dae2a..3db7eb03 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -1,5 +1,5 @@ How to make a slixmpp plugins for Messages and IQ extensions -======================================================================= +==================================================================== Introduction and requirements ----------------- @@ -49,7 +49,7 @@ Example output: If some of the libraries throw `'ImportError'` or `'no module named ...'` error, install them with: -On ubuntu linux: +On Ubuntu linux: .. code-block:: bash @@ -395,7 +395,7 @@ To receive this message, the responder should have a proper handler to the signa #<<<<<<<<<<<< Expanding the Message with a new tag -++++++++++++++++++++++++++++ +------------------------- To expand the Message object with a tag, the plugin should be registered as the extension for the Message object: @@ -405,12 +405,12 @@ To expand the Message object with a tag, the plugin should be registered as the class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. - self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. + self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. + self.xep = "ope" ##~ String data readable by humans and to find plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Register the tags extension for Message object, otherwise message['example_tag'] will be string field instead container and whould not be able to manage fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register the tag extension for Message object, otherwise message['example_tag'] will be string field instead container and managing fields and create sub elements would be impossible. #<<<<<<<<<<<< class ExampleTag(ElementBase): @@ -463,9 +463,9 @@ Now, with the registered object, the message can be extended. After running, the logging should print the Message with tag `'example_tag'` stored inside , string `'Work'` and given namespace. Giving the extended message the separate signal -+++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------- -If the separate event is not defined, then both normal and extended message will be cached by signal `'message'`. In order to have the special event, the handler for the namespace ang tag should be created. Then, make a unique name combination, which allows the handler can catch only the wanted messages (or Iq object). +If the separate event is not defined, then both normal and extended message will be cached by signal `'message'`. In order to have the special event, the handler for the namespace and tag should be created. Then, make a unique name combination, which allows the handler can catch only the wanted messages (or Iq object). .. code-block:: python @@ -473,16 +473,16 @@ If the separate event is not defined, then both normal and extended message will class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. - self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. + self.description = "OurPluginExtension" ##~ String data readable by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data readable by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handles only the Message with good example_tag and namespace. - self.__handle_message)) ##~ Method which catches the proper Message, should raise event for the client. - register_stanza_plugin(Message, ExampleTag) ##~ Register the tags extension for Message object, otherwise message['example_tag'] will be string field instead container and whould not be able to manage fields and create sub elements. + self.__handle_message)) ##~ Method catches the proper Message, should raise event for the client. + register_stanza_plugin(Message, ExampleTag) ##~ Register the tags extension for Message object, otherwise message['example_tag'] will be string field instead container and managing the fields and create sub elements would not be possible. def __handle_message(self, msg): # Here something can be done with received message before it reaches the client. @@ -541,7 +541,7 @@ Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The nam #>>>>>>>>>>>> self.add_event_handler("example_tag_message", self.example_tag_message) #Registration of the handler #<<<<<<<<<<<< - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() @@ -549,7 +549,7 @@ Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The nam #>>>>>>>>>>>> def example_tag_message(self, msg): - logging.info(msg) # Message is standalone object, it can be replied, but no error rises if not. + logging.info(msg) # Message is standalone object, it can be replied, but no error is returned if not. #<<<<<<<<<<<< The messages can be replied, but nothing will happen if we don't. @@ -558,8 +558,8 @@ However, when we receive the Iq object, we should always reply. Otherwise, the e Useful methods and misc. ----------------------- -Modifying the example `Message` object to the `Iq` object. -++++++++++++++++++++++++++++++++++++++++ +Modifying the example `Message` object to the `Iq` object +------------------------- To convert the Message into the Iq object, a new handler for the Iq should be registered, in the same maner as in the `,,Extend message with tags''`part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. @@ -569,8 +569,8 @@ To convert the Message into the Iq object, a new handler for the Iq should be re class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. - self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. + self.description = "OurPluginExtension" ##~ String data readab;e by humans and to find the plugin by another plugin. + self.xep = "ope" ##~ String data readable by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> @@ -602,21 +602,21 @@ To convert the Message into the Iq object, a new handler for the Iq should be re # All iq types are: get, set, error, result def __handle_get_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Call the event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_get_iq', iq) ##~ Calls the event which can be handled by clients. def __handle_result_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Call the event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_result_iq', iq) ##~ Calls the event which can be handled by clients. def __handle_error_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_error_iq', iq) ##~ Calls the event which can be handled by clients. def __handle_message(self, msg): # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_message', msg) ##~ Calls the event which can be handled by clients. -The events called by the example handlers can be caught like in the`'example_tag_message'` example. +The events called by the example handlers can be caught like in the`'example_tag_message'` part. .. code-block:: python @@ -687,7 +687,7 @@ By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that #<<<<<<<<<<<< Different ways to access the elements -+++++++++++++++++++++++ +------------------------- There are several ways to access the elements inside the Message or Iq stanza. The first one: the client can access them like a dictionary: @@ -765,7 +765,7 @@ When the proper setters and getters are used, it is easy to check whether some a iq.send() Message setup from the XML files, strings and other objects -+++++++++++++++++++++++++++++++++++++++++++++++++++++++ +------------------------- There are many ways to set up a xml from a string, xml-containing file or lxml (ElementTree) file. One of them is parsing the strings to lxml object, passing the attributes and other information, which may look like this: @@ -781,9 +781,9 @@ There are many ways to set up a xml from a string, xml-containing file or lxml ( name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as name. - interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. #>>>>>>>>>>>> def setup_from_string(self, string): @@ -855,7 +855,7 @@ To test this, we need an example file with xml, example xml string and example l self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() # Example disconnect after receiving the maximum number of recponses. + self.disconnect() # Example disconnect after receiving the maximum number of responses. def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) @@ -882,7 +882,7 @@ To test this, we need an example file with xml, example xml string and example l If the Responder returns the proper `'Iq'` and the Sender disconnects after three answers, then everything works okay. Dev friendly methods for plugin usage -+++++++++++++++++++++++++++++++++++++ +-------------------------------------- Any plugin should have some sort of object-like methods, that was setup for elements: reading the data, getters, setters and signals, to make them easy to use. During handling, the correctness of the data should be checked and the eventual errors returned back to the sender. In order to avoid the situation where the answer message is never send, the sender gets the timeout error. @@ -915,17 +915,17 @@ The following code presents exactly this: namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag + StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'get' and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag + StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'result' and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback - StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag + StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'error' and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. self.xmpp.register_handler( @@ -935,7 +935,7 @@ The following code presents exactly this: register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. - + # All iq types are: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: @@ -945,27 +945,27 @@ The following code presents exactly this: error["error"]["text"] = "Without some_string value returns error." error.send() # Do something with received iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something else. def __handle_result_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something else. def __handle_error_iq(self, iq): # Do something with received iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something else. def __handle_message(self, msg): # Do something with received message - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other. + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something else. class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace stanza object lives in, like . You should change it for your own namespace. - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as name. - interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. def setup_from_string(self, string): """Initialize tag element from string""" @@ -984,7 +984,7 @@ The following code presents exactly this: self.xml.tail = lxml.tail for inner_tag in lxml: self.xml.append(inner_tag) - + def setup_from_dict(self, data): #There keys from dict should be also validated self.xml.attrib.update(data) @@ -1008,14 +1008,14 @@ The following code presents exactly this: self.xml.text = text def fill_interfaces(self, boolean, some_string): - #Some validation if it is necessary + #Some validation, if necessary self.set_boolean(boolean) self.set_some_string(some_string) .. code-block:: python #File: $WORKDIR/example/responder.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1088,7 +1088,7 @@ The following code presents exactly this: .. code-block:: python #File: $WORKDIR/example/sender.py - + import logging from argparse import ArgumentParser from getpass import getpass @@ -1115,42 +1115,42 @@ The following code presents exactly this: self.send_presence() self.get_roster() - self.disconnect_counter = 5 # This is only for disconnect when we receive all replies for sended Iq + self.disconnect_counter = 5 # # Disconnect after receiving the maximum number of responses. self.send_example_iq(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) - # Info_inside_tag_message + # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) - # - # OUR ERROR Without boolean value returns error. - # OFFLINE ERROR User session not found + # + # OUR ERROR Without boolean value returns error. + # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + self.disconnect() # Example disconnect after receiving the maximum number of responses. def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: - self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. + self.disconnect() # Example disconnect after receiving the maximum number of responses. def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) @@ -1185,7 +1185,7 @@ The following code presents exactly this: def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag the without boolean value. iq.send() def send_example_iq_tag_from_string(self, to, string): @@ -1225,7 +1225,7 @@ The following code presents exactly this: args.password = getpass("Password: ") xmpp = Sender(args.jid, args.password, args.to, args.path) - xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin + xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin. xmpp.connect() try: @@ -1237,14 +1237,16 @@ The following code presents exactly this: pass Tags and strings nested inside our tag -++++++++++++++++++++++++++++++++++++++ +-------------------------------------- -To make the nested element inside our IQ tag, we need to consider `self.xml` field as an Element from ET (ElementTree). So, adding the nested elements is just appending the Element. +To create the nested element inside IQ tag, `self.xml` field can be considered as an Element from ET (ElementTree). Therefore adding the nested Elements is appending the Element. + +As shown in the previous examples, it is possible to create a new element as main (ExampleTag). However, when the additional methods or validation is not needed and the result will be parsed to xml anyway, it may be better to nest the Element from ElementTree with method 'append'. In order to not use the 'setup' method again, the code below shows way of the manual addition of the nested tag and creation of ET Element. .. code-block:: python #File: $WORKDIR/example/example_plugin.py - + #(...) class ExampleTag(ElementBase): -- cgit v1.2.3 From fc77fb7648cc8b0215da83ecd6727e746af89bf4 Mon Sep 17 00:00:00 2001 From: Paulina Date: Sun, 15 Mar 2020 18:02:46 +0100 Subject: Correction and editing of the tutorials. [95 %] English version [95 %] Polish version [100%] Both version consistency check [95 %] Final sanity check + formating --- ...make_plugin_extension_for_message_and_iq.pl.rst | 74 +++++++------- .../make_plugin_extension_for_message_and_iq.rst | 110 ++++++++++----------- 2 files changed, 92 insertions(+), 92 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst index 5d774cff..c3685eae 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -21,7 +21,7 @@ Instalacja dla Ubuntu linux: * `'subprocess'` * `'threading'` -Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdaża się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. +Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdarza się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. .. code-block:: python @@ -70,7 +70,7 @@ Skrypt uruchamiający klientów Skrypt pozwalający testować klientów powinien zostać stworzony poza lokalizacją projektu. Pozwoli to szybko sprawdzać wyniki skryptów oraz uniemożliwi przypadkowe wysłanie swoich danych na gita. -Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/usr/bin'` i nadać mu uprawnienia wykonywawcze: +Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/usr/bin'` i nadać mu uprawnienia wykonawcze: .. code-block:: bash @@ -127,14 +127,14 @@ Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawie Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. -Skrypt uruchomieniowy powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. +Skrypt uruchamiający powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. -W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko okreslić, który klient co zwraca, bądź który powoduje błąd. +W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko określić, który klient co zwraca, bądź który powoduje błąd. Stworzenie klienta i pluginu ---------------------------- -W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchomieniowy działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: +W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchamiający działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: .. code-block:: python @@ -159,7 +159,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz self.add_event_handler("session_start", self.start) def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostepność online. + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online. self.send_presence() self.get_roster() @@ -221,7 +221,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz self.add_event_handler("session_start", self.start) def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() @@ -264,7 +264,7 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz except: pass -Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w lokalizacji dostepnej dla klientów (domyślnie w tej samej, co skrypty klientów). +Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w lokalizacji dostępnej dla klientów (domyślnie w tej samej, co skrypty klientów). .. code-block:: python @@ -312,14 +312,14 @@ Pierwsze uruchomienie i przechwytywanie eventów Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisany event `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. -W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a nastepnie użyć komendy `'test_slixmpp'`. +W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a następnie użyć komendy `'test_slixmpp'`. Metoda `'def start(self, event):'` powinna wyglądać tak: .. code-block:: python def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() @@ -332,7 +332,7 @@ Jeżeli oba klienty uruchomiły się poprawnie, można zakomentować tą linię. Budowanie obiektu Message ------------------------- -Wysyłający powinien posiadać informację o tym, do kogo należy wysłać wiadomość. Nazwę i scieżkę odbiorcy można przekazać, na przykład, przez argumenty wywołania skryptu w lini komend. W poniższym przykładzie, są one trzymane w atrybucie `'self.to'`. +Wysyłający powinien posiadać informację o tym, do kogo należy wysłać wiadomość. Nazwę i ścieżkę odbiorcy można przekazać, na przykład, przez argumenty wywołania skryptu w linii komend. W poniższym przykładzie, są one trzymane w atrybucie `'self.to'`. Przykład: @@ -350,7 +350,7 @@ Przykład: self.add_event_handler("session_start", self.start) def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> @@ -382,7 +382,7 @@ Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: #<<<<<<<<<<<< def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() @@ -410,14 +410,14 @@ Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestro namespace = ExampleTag.namespace #>>>>>>>>>>>> - register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i pod-elementów. #<<<<<<<<<<<< class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML dla tego rozszerzenia.. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. @@ -445,7 +445,7 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. self.add_event_handler("session_start", self.start) def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() self.send_example_message(self.to, "example_message") @@ -482,7 +482,7 @@ Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytuje wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag self.__handle_message)) ##~ Metoda do której zostaje przypisany przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. - register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i podelementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i pod-elementów. def __handle_message(self, msg): # Tu można coś zrobić z przechwyconą wiadomością zanim trafi do klienta. @@ -512,7 +512,7 @@ Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany name self.add_event_handler("session_start", self.start) def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() #>>>>>>>>>>>> @@ -543,7 +543,7 @@ Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W #<<<<<<<<<<<< def start(self, event): - # Metody niewymagane, ale pozwalające na zobaczenie dostepności online. + # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() @@ -553,7 +553,7 @@ Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W #<<<<<<<<<<<< Można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. -Natomiast obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeout, jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. +Natomiast obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeoutu, jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. Użyteczne metody i inne ----------------------- @@ -602,19 +602,19 @@ Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować # Wszystkie możliwe typy Iq to: get, set, error, result def __handle_get_iq(self, iq): # Zrób coś z otrzymanym iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. + self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. def __handle_result_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. + self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. def __handle_error_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. + self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. def __handle_message(self, msg): # Zrób coś z otrzymanym message - self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może być obsłuzony przez klienta lub inaczej. + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. @@ -659,7 +659,7 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, #<<<<<<<<<<<< def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() @@ -717,7 +717,7 @@ Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wym name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. @@ -767,7 +767,7 @@ Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewn Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów ------------------------- -Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu napisowego do lxml (ElementTree) i przekazanie atrybutów. +Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu tekstowego do lxml (ElementTree) i przekazanie atrybutów. .. code-block:: python @@ -781,7 +781,7 @@ Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku al name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. @@ -833,7 +833,7 @@ Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() @@ -930,11 +930,11 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacku - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługije tylko Message z example_tag + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Message z example_tag self.__handle_message)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. - register_stanza_plugin(Iq, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Iq. Bez tego, iq['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć podelementów. - register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć podelementów. + register_stanza_plugin(Iq, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Iq. Bez tego, iq['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. # Wszystkie możliwe typy iq: get, set, error, result def __handle_get_iq(self, iq): @@ -963,7 +963,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestronanego obieksu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. @@ -1032,11 +1032,11 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.add_event_handler("example_tag_message", self.example_tag_message) def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() - def example_tag_get_iq(self, iq): # Iq zawsze powinien odpowiedzieć. Jeżeli użytkownik jest offline, zostanie zrwócony error. + def example_tag_get_iq(self, iq): # Iq zawsze powinien odpowiedzieć. Jeżeli użytkownik jest offline, zostanie zwrócony error. logging.info(iq) reply = iq.reply() reply["example_tag"].fill_interfaces(True, "Reply_string") @@ -1111,7 +1111,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępnośc online + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() @@ -1242,7 +1242,7 @@ Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). W takim wypadku, aby stworzyć zagnieżdżony element można użyć funkcji 'append'. -Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typy napisowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. +Można powtórzyć poprzednie działania inicjalizując nowy element jak główny (ExampleTag). Jednak jeśli nie potrzebujemy dodatkowych metod, czy walidacji, a jest to wynik dla innego procesu który i tak będzie parsował xml, wtedy możemy zagnieździć zwyczajny Element z ElementTree za pomocą metody `'append'`. W przypadku przetwarzania typu tekstowego, można to zrobić nawet dzięki parsowaniu napisu na Element - kolejne zagnieżdżenia już będą w dodanym Elemencie do głównego. By nie powtarzać metody setup, poniżej przedstawione jest ręczne dodanie zagnieżdżonego taga konstruując ET.Element samodzielnie. .. code-block:: python diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index 3db7eb03..e7202cd0 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -21,7 +21,7 @@ Ubuntu linux installation steps: * `'subprocess'` * `'threading'` -Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happend that some of them may not be installed. +Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happened that some of them may not be installed. .. code-block:: python @@ -68,7 +68,7 @@ For the testing purposes, two private jabber accounts are required. They can be Client launch script ----------------------------- -The client launch script should be created outside of the main project location. This allows to easly obtain the results when needed and prevents accidental lekeage of credencial details to the git platform. +The client launch script should be created outside of the main project location. This allows to easily obtain the results when needed and prevents accidental leakage of credential details to the git platform. As the example, a file `'test_slixmpp'` can be created in `'/usr/bin'` directory, with executive permission: @@ -125,9 +125,9 @@ This file should be readable and writable only with superuser permission. This f except: print ("Error: unable to start thread") -The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatybility is needed, replace it with `'subprocess.call'` method and adjust accordingly. +The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatibility is needed, replace it with `'subprocess.call'` method and adjust accordingly. -The launch script should be convinient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. We can define there the logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. +The launch script should be convenient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. We can define there the logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. In case of manually testing the larger applications, it would be a good practise to introduce the unique names (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. @@ -293,7 +293,7 @@ Next file to create is `'example_plugin.py'`. It can be placed in the same catal class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element for that extension. - namespace = "" ##~ The namespace our stanza object lives in, like . Should be changed to your own namespace. + namespace = "" ##~ The namespace of the object, like . Should be changed to your namespace. plugin_attrib = "example_tag" ##~ The name under which the data in plugin can be accessed. In particular, this object is reachable from the outside with: stanza_object['example_tag']. The `'example_tag'` is name of ElementBase extension and should be that same as the name. @@ -486,17 +486,17 @@ If the separate event is not defined, then both normal and extended message will def __handle_message(self, msg): # Here something can be done with received message before it reaches the client. - self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by the client with desired objest as an argument. + self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by the client with desired object as an argument. -StanzaPath objects should be initialized in a specific way, such as: +StanzaPath objects should be initialised in a specific way, such as: `'OBJECT_NAME[@type=TYPE_OF_OBJECT][/{NAMESPACE}[TAG]]'` * For OBJECT_NAME we can use `'message'` or `'iq'`. -* For TYPE_OF_OBJECT, when iq is specified, `'get, set, error or result'` can be used. When objest is a message, then the message type can be used, like `'chat'`. +* For TYPE_OF_OBJECT, when iq is specified, `'get, set, error or result'` can be used. When object is a message, then the message type can be used, like `'chat'`. * NAMESPACE should always be a namespace from tag extension class. * TAG should contain the tag, in this case:`'example_tag'`. -Now every message containing the defined namespace inside `'example_tag'` is catched. It is possible to check the content of it. Then, the message is send to the client with the `'example_tag_message'` event. +Now every message containing the defined namespace inside `'example_tag'` is cached. It is possible to check the content of it. Then, the message is send to the client with the `'example_tag_message'` event. .. code-block:: python @@ -561,7 +561,7 @@ Useful methods and misc. Modifying the example `Message` object to the `Iq` object ------------------------- -To convert the Message into the Iq object, a new handler for the Iq should be registered, in the same maner as in the `,,Extend message with tags''`part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. +To convert the Message into the Iq object, a new handler for the Iq should be registered, in the same manner as in the `,,Extend message with tags''`part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. .. code-block:: python @@ -569,7 +569,7 @@ To convert the Message into the Iq object, a new handler for the Iq should be re class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String data readab;e by humans and to find the plugin by another plugin. + self.description = "OurPluginExtension" ##~ String data readable by humans and to find the plugin by another plugin. self.xep = "ope" ##~ String data readable by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. namespace = ExampleTag.namespace @@ -594,9 +594,9 @@ To convert the Message into the Iq object, a new handler for the Iq should be re StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. #<<<<<<<<<<<< - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container, where it is impossible to manage fields and create sub elements. #>>>>>>>>>>>> # All iq types are: get, set, error, result @@ -707,7 +707,7 @@ There are several ways to access the elements inside the Message or Iq stanza. T logging.info(iq.get('example_tag').get('boolean')) #<<<<<<<<<<<< -The access to the elements from extendet ExampleTag is simmilar. However, defining the types is not required and the access can be diversified (like for the `'text'` field below). For the ExampleTag extension, there is a 'getter' and 'setter' method for specific fields: +The access to the elements from extended ExampleTag is similar. However, defining the types is not required and the access can be diversified (like for the `'text'` field below). For the ExampleTag extension, there is a 'getter' and 'setter' method for specific fields: .. code-block:: python @@ -715,11 +715,11 @@ The access to the elements from extendet ExampleTag is simmilar. However, defini class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . Should be changed for own namespace. + namespace = "https://example.net/our_extension" ##~ The namespace for stanza object, like . Should be changed to own namespace. - plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'], the `'example_tag'` is the name of ElementBase extension. And this should be that same as name. + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'], the `'example_tag'` is the name of ElementBase extension. And this should be the same as name. - interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. #>>>>>>>>>>>> def get_some_string(self): @@ -737,7 +737,7 @@ The access to the elements from extendet ExampleTag is simmilar. However, defini The attribute `'self.xml'` is inherited from the ElementBase and is exactly the same as the `'Iq['example_tag']'` from the client namespace. -When the proper setters and getters are used, it is easy to check whether some argument is proper for the plugin or is conversable to another type. The code itself can be cleaner and more object-oriented, like in the example below: +When the proper setters and getters are used, it is easy to check whether some argument is proper for the plugin or is convertible to another type. The code itself can be cleaner and more object-oriented, like in the example below: .. code-block:: python @@ -779,7 +779,7 @@ There are many ways to set up a xml from a string, xml-containing file or lxml ( class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The stanza object namespace, like . Should be changed to your own namespace plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as name. @@ -811,7 +811,7 @@ To test this, we need an example file with xml, example xml string and example l #File: $WORKDIR/test_example_tag.xml - Info_inside_tag + Info_inside_tag .. code-block:: python @@ -841,15 +841,15 @@ To test this, we need an example file with xml, example xml string and example l self.disconnect_counter = 3 # Disconnects when all replies from Iq are received. self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 @@ -933,8 +933,8 @@ The following code presents exactly this: StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead of container, where we can manage our fields and create sub elements. + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. # All iq types are: get, set, error, result def __handle_get_iq(self, iq): @@ -1124,12 +1124,12 @@ The following code presents exactly this: # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) # @@ -1137,7 +1137,7 @@ The following code presents exactly this: # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1185,7 +1185,7 @@ The following code presents exactly this: def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag the without boolean value. + iq['example_tag'].set_boolean(True) # For example, the condition to receive the error respond is the example_tag the without boolean value. iq.send() def send_example_iq_tag_from_string(self, to, string): @@ -1236,7 +1236,7 @@ The following code presents exactly this: except: pass -Tags and strings nested inside our tag +Tags and strings nested inside the tag -------------------------------------- To create the nested element inside IQ tag, `self.xml` field can be considered as an Element from ET (ElementTree). Therefore adding the nested Elements is appending the Element. @@ -1254,8 +1254,8 @@ As shown in the previous examples, it is possible to create a new element as mai #(...) def add_inside_tag(self, tag, attributes, text=""): - #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + #If more tags is needed inside the element, they can be added like that: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialise ET with tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. @@ -1356,8 +1356,8 @@ Complete code from tutorial StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. + register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. # All iq types are: get, set, error, result def __handle_get_iq(self, iq): @@ -1384,7 +1384,7 @@ Complete code from tutorial class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. - namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace + namespace = "https://example.net/our_extension" ##~ The stanza object namespace, like . Should be changed for your namespace. plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. @@ -1436,8 +1436,8 @@ Complete code from tutorial self.set_some_string(some_string) def add_inside_tag(self, tag, attributes, text=""): - #If we want to fill with additionaly tags our element, then we can do it that way for example: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: + #If more tags is needed inside the element, they can be added like that: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialise ET with tag, for example: itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. @@ -1474,24 +1474,24 @@ Complete code from tutorial self.send_presence() self.get_roster() - self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sent Iq self.send_example_iq(self.to) # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) # @@ -1499,7 +1499,7 @@ Complete code from tutorial # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1528,7 +1528,7 @@ Complete code from tutorial iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - inner_attributes = {"first_field": "1", "secound_field": "2"} + inner_attributes = {"first_field": "1", "second_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) iq.send() @@ -1558,7 +1558,7 @@ Complete code from tutorial def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq['example_tag'].set_boolean(True) # For example, the condition to receive error respond is the example_tag without boolean value. iq.send() def send_example_iq_tag_from_string(self, to, string): @@ -1647,18 +1647,18 @@ Complete code from tutorial # Info_inside_tag self.send_example_iq_with_inner_tag(self.to) - # Info_inside_tag + # Info_inside_tag self.send_example_message(self.to) # Info_inside_tag_message self.send_example_iq_tag_from_file(self.to, self.path) - # Info_inside_tag + # Info_inside_tag - string = 'Info_inside_tag' + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) - # Info_inside_tag + # Info_inside_tag self.send_example_iq_to_get_error(self.to) # @@ -1666,7 +1666,7 @@ Complete code from tutorial # OFFLINE ERROR User session not found self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): @@ -1695,7 +1695,7 @@ Complete code from tutorial iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - inner_attributes = {"first_field": "1", "secound_field": "2"} + inner_attributes = {"first_field": "1", "second_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) iq.send() @@ -1725,7 +1725,7 @@ Complete code from tutorial def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. + iq['example_tag'].set_boolean(True) # For example, the condition for receivingg error respond is example_tag without boolean value. iq.send() def send_example_iq_tag_from_string(self, to, string): @@ -1784,7 +1784,7 @@ Complete code from tutorial .. code-block:: xml - Info_inside_tag + Info_inside_tag Sources and references --------------------- -- cgit v1.2.3 From 9fd8684c5a86ca7d3e3ba99b689e695e28d42bf5 Mon Sep 17 00:00:00 2001 From: Paulina Date: Sat, 21 Mar 2020 17:08:31 +0100 Subject: Correction and editing of the tutorials. [98 %] English version [98 %] Polish version [100%] Both version consistency check [95 %] Final sanity check + formating --- ...make_plugin_extension_for_message_and_iq.pl.rst | 10 +++++----- .../make_plugin_extension_for_message_and_iq.rst | 22 +++++++++++----------- 2 files changed, 16 insertions(+), 16 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst index c3685eae..8911ea14 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -127,14 +127,14 @@ Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawie Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. -Skrypt uruchamiający powinien być dostosowany do naszych potrzeb: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. +Skrypt uruchamiający powinien być dostosowany do potrzeb urzytkownika: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko określić, który klient co zwraca, bądź który powoduje błąd. Stworzenie klienta i pluginu ---------------------------- -W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy nasz skrypt uruchamiający działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: +W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy skrypt uruchamiający działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: .. code-block:: python @@ -295,7 +295,7 @@ Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w name = "example_tag" ##~ Nazwa głównego pliku XML w tym rozszerzeniu. namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: - plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` staje się nazwą pluginu i powinno być takie samo jak name. + plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` jest nazwą pluginu i powinno być takie samo jak name. interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów elementu które mogą być użyte w elemencie. Na przykład `stanza_object['example_tag']` poda informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest elementu. @@ -1256,10 +1256,10 @@ Można powtórzyć poprzednie działania inicjalizując nowy element jak główn def add_inside_tag(self, tag, attributes, text=""): #Można rozszerzyć tag o tagi wewnętrzne do tagu, na przykład tak: - itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z naszym wewnętrznym tagiem, na przykład: + itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z wewnętrznym tagiem, na przykład: itemXML.attrib.update(attributes) #~ Przypisujemy zdefiniowane atrybuty, na przykład: itemXML.text = text #~ Dodajemy text wewnątrz tego tagu: our_text - self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z naszym tagiem `example_tag`. + self.xml.append(itemXML) #~ I tak skonstruowany Element po prostu dodajemy do elementu z tagiem `example_tag`. Można też zrobić to samo używając słownika i nazw jako kluczy zagnieżdżonych elementów. W takim przypadku, pola funkcji powinny zostać przeniesione do ET. diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index e7202cd0..501bbe0a 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -127,7 +127,7 @@ This file should be readable and writable only with superuser permission. This f The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatibility is needed, replace it with `'subprocess.call'` method and adjust accordingly. -The launch script should be convenient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. We can define there the logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. +The launch script should be convenient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. Logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more things can be defined inside. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. In case of manually testing the larger applications, it would be a good practise to introduce the unique names (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. @@ -310,7 +310,7 @@ The other solution is to relative import it (with dots '.') to get the proper pa First run and the event handlers ----------------------------------------------- -To check if everything is okay, we can use the `'start'` method (which triggers the `'session_start'` event). Right after the client is ready, the signal will be sent. +To check if everything is okay, the `'start'` method can be used(which triggers the `'session_start'` event). Right after the client is ready, the signal will be sent. In the `'__init__'` method, the handler for event call `'session_start'` is created. When it is called, the `'def start(self, event):'` method will be executed. During the first run, add the line: `'logging.info("I'm running")'` to both the sender and the responder, and use `'test_slixmpp'` command. @@ -327,7 +327,7 @@ The `'def start(self, event):'` method should look like this: logging.info("I'm running") #<<<<<<<<<<<< -If everything works fine, we can comment this line out. +If everything works fine, this line can be commented out. Building the message object ------------------------- @@ -363,7 +363,7 @@ Code example: msg.send() #<<<<<<<<<<<< -In the example below, we are using the build-in method `'make_message'`. It creates a string "example_message" and sends it at the end of `'start'` method. The message will be sent once, after the script launch. +In the example below, the build-in method `'make_message'` is used. It creates a string "example_message" and sends it at the end of `'start'` method. The message will be sent once, after the script launch. To receive this message, the responder should have a proper handler to the signal with the message object and the method to decide what to do with this message. As it is shown in the example below: @@ -491,7 +491,7 @@ If the separate event is not defined, then both normal and extended message will StanzaPath objects should be initialised in a specific way, such as: `'OBJECT_NAME[@type=TYPE_OF_OBJECT][/{NAMESPACE}[TAG]]'` -* For OBJECT_NAME we can use `'message'` or `'iq'`. +* OBJECT_NAME can be `'message'` or `'iq'`. * For TYPE_OF_OBJECT, when iq is specified, `'get, set, error or result'` can be used. When object is a message, then the message type can be used, like `'chat'`. * NAMESPACE should always be a namespace from tag extension class. * TAG should contain the tag, in this case:`'example_tag'`. @@ -552,8 +552,8 @@ Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The nam logging.info(msg) # Message is standalone object, it can be replied, but no error is returned if not. #<<<<<<<<<<<< -The messages can be replied, but nothing will happen if we don't. -However, when we receive the Iq object, we should always reply. Otherwise, the error occurs on the client side due to the target timeout if the cell Iq won't reply with Iq with the same Id. +The messages can be replied, but nothing will happen otherwise. +The Iq object, on the other hand, should always be replied. Otherwise, the error occurs on the client side due to the target timeout if the cell Iq won't reply with Iq with the same Id. Useful methods and misc. ----------------------- @@ -805,7 +805,7 @@ There are many ways to set up a xml from a string, xml-containing file or lxml ( self.xml.append(inner_tag) #<<<<<<<<<<<< -To test this, we need an example file with xml, example xml string and example lxml (ET) object: +To test this, an example file with xml, example xml string and example lxml (ET) object is needed: .. code-block:: xml @@ -1185,7 +1185,7 @@ The following code presents exactly this: def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) - iq['example_tag'].set_boolean(True) # For example, the condition to receive the error respond is the example_tag the without boolean value. + iq['example_tag'].set_boolean(True) # For example, the condition to receive the error respond is the example_tag without the boolean value. iq.send() def send_example_iq_tag_from_string(self, to, string): @@ -1256,9 +1256,9 @@ As shown in the previous examples, it is possible to create a new element as mai def add_inside_tag(self, tag, attributes, text=""): #If more tags is needed inside the element, they can be added like that: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialise ET with tag, for example: - itemXML.attrib.update(attributes) #~ There we add some fields inside tag, for example: + itemXML.attrib.update(attributes) #~ Here we add some fields inside tag, for example: itemXML.text = text #~ Fill field inside tag, for example: our_text - self.xml.append(itemXML) #~ Add that all what we set, as inner tag inside `example_tag` tag. + self.xml.append(itemXML) #~ Add that is all, what needs to be set as an inner tag inside the `example_tag` tag. There is a way to do this with a dictionary and name for the nested element tag. In that case, the insides of the function fields should be transferred to the ET element. -- cgit v1.2.3 From f84bfce5f386a310613f8cada75c86efff55894d Mon Sep 17 00:00:00 2001 From: Paulina Date: Fri, 10 Apr 2020 12:37:31 +0200 Subject: Correction and editing of the tutorials. [100%] English version [100%] Polish version [100%] Both version consistency check [98 %] Final sanity check + formating --- ...make_plugin_extension_for_message_and_iq.pl.rst | 689 ++++++++++----------- .../make_plugin_extension_for_message_and_iq.rst | 681 ++++++++++---------- 2 files changed, 684 insertions(+), 686 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst index 8911ea14..b85c01f5 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -1,13 +1,13 @@ Jak stworzyć własny plugin rozszerzający obiekty Message i Iq w Slixmpp -==================================================================== +======================================================================== Wstęp i wymagania ------------------ +------------------ * `'python3'` Kod użyty w tutorialu jest kompatybilny z pythonem w wersji 3.6 lub nowszej. -Dla wstecznej kompatybilności z wcześniejszymi wersjami należy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. +Dla uzyskania kompatybilności z wcześniejszymi wersjami należy zastąpić f-strings starszym formatowaniem napisów `'"{}".format("content")'` lub `'%s, "content"'`. Instalacja dla Ubuntu linux: @@ -43,7 +43,7 @@ Wynik w terminalu: ~ $ python3 -c "import argparse; print(argparse.__version__)" 1.1 ~ $ python3 -c "import logging; print(logging.__version__)" - 0.5.1.2 + 0.5.1.2 ~ $ python3 -m subprocess # Nie powinno nic zwrócić ~ $ python3 -m threading # Nie powinno nic zwrócić @@ -61,12 +61,11 @@ Jeśli jakaś biblioteka zwróci NameError, należy zainstalować pakiet ponowni * `Konta dla Jabber` -Do testowania niezbędne będą dwa prywatne konta jabbera. Można je stworzyć na jednym z dostępnych darmowych serwerów: - +Do testowania niezbędne będą dwa prywatne konta jabbera. Można je stworzyć na jednym z dostępnych darmowych serwerów: https://www.google.com/search?q=jabber+server+list Skrypt uruchamiający klientów ------------------------------ +------------------------------ Skrypt pozwalający testować klientów powinien zostać stworzony poza lokalizacją projektu. Pozwoli to szybko sprawdzać wyniki skryptów oraz uniemożliwi przypadkowe wysłanie swoich danych na gita. @@ -86,10 +85,10 @@ Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawie import subprocess import threading import time - + def start_shell(shell_string): subprocess.run(shell_string, shell=True, universal_newlines=True) - + if __name__ == "__main__": #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala #~ prefix = "xterm -e" @@ -97,24 +96,24 @@ Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawie #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet postfix = "" - + sender_path = "./example/sender.py" sender_jid = "SENDER_JID" sender_password = "SENDER_PASSWORD" - + example_file = "./test_example_tag.xml" - + responder_path = "./example/responder.py" responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - + # Pamiętaj o nadaniu praw do wykonywania (`chmod +x ./file.py`) SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" - + try: responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) @@ -132,7 +131,7 @@ Skrypt uruchamiający powinien być dostosowany do potrzeb urzytkownika: można W przypadku testowania większych aplikacji, w tworzeniu pluginu szczególnie użyteczne jest nadanie unikalnych nazwy dla każdego klienta (w konsekwencji: różne linie poleceń). Pozwala to szybko określić, który klient co zwraca, bądź który powoduje błąd. Stworzenie klienta i pluginu ----------------------------- +----------------------------- W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w przykładach: `'sender'` i `'responder'`), aby sprawdzić czy skrypt uruchamiający działa poprawnie. Poniżej przedstawiona została minimalna niezbędna implementacja, która może testować plugin w trakcie jego projektowania: @@ -143,36 +142,36 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) - def start(self, event): - # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online. - self.send_presence() - self.get_roster() + def start(self, event): + # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online. + self.send_presence() + self.get_roster() if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -181,17 +180,17 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin. @@ -210,16 +209,16 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz import logging from argparse import ArgumentParser from getpass import getpass - + import slixmpp import example_plugin - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) - + def start(self, event): # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() @@ -227,34 +226,34 @@ W stosownej dla nas lokalizacji powinniśmy stworzyć dwa klienty slixmpp (w prz if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") parser.add_argument("-t", "--to", dest="to", help="JID to send the message to") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Responder(args.jid, args.password) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy example_plugin - + xmpp.connect() try: xmpp.process() @@ -268,35 +267,35 @@ Następny plik, który należy stworzyć to `'example_plugin'`. Powinien być w .. code-block:: python - #File: $WORKDIR/example/example plugin.py + #File: $WORKDIR/example/example_plugin.py import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin self.xep = "ope" ##~ Napis czytelny dla człowieka i dla znalezienia pluginu przez inny plugin poprzez dodanie tego do `slixmpp/plugins/__init__.py`, w polu `__all__` z prefixem xep 'xep_OPE'. - + namespace = ExampleTag.namespace class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML w tym rozszerzeniu. namespace = "https://example.net/our_extension" ##~ Namespace obiektu jest definiowana w tym miejscu, powinien się odnosić do nazwy portalu xmpp; w wiadomości wygląda tak: - + plugin_attrib = "example_tag" ##~ Nazwa pod którą można odwoływać się do danych zawartych w tym pluginie. Bardziej szczegółowo: tutaj rejestrujemy nazwę obiektu by móc się do niego odwoływać z zewnątrz. Można się do niego odwoływać jak do słownika: stanza_object['example_tag'], gdzie `'example_tag'` jest nazwą pluginu i powinno być takie samo jak name. - + interfaces = {"boolean", "some_string"} ##~ Zbiór kluczy dla słownika atrybutów elementu które mogą być użyte w elemencie. Na przykład `stanza_object['example_tag']` poda informacje o: {"boolean": "some", "some_string": "some"}, tam gdzie `'example_tag'` jest elementu. Jeżeli powyższy plugin nie jest w domyślnej lokalizacji, a klienci powinni pozostać poza repozytorium, możemy w miejscu klientów dodać dowiązanie symboliczne do lokalizacji pluginu: @@ -339,14 +338,14 @@ Przykład: .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -355,28 +354,28 @@ Przykład: self.get_roster() #>>>>>>>>>>>> self.send_example_message(self.to, "example_message") - + def send_example_message(self, to, body): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Domyślnie mtype == "chat"; + # Domyślnie mtype == "chat"; msg = self.make_message(mto=to, mbody=body) msg.send() #<<<<<<<<<<<< -W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. +W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie został przypisany żaden inny event. Przykład takiego kodu: .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) - + #>>>>>>>>>>>> self.add_event_handler("message", self.message) #<<<<<<<<<<<< @@ -385,7 +384,7 @@ Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> def message(self, msg): #Pokazuje cały XML wiadomości @@ -395,19 +394,19 @@ Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: #<<<<<<<<<<<< Rozszerzenie Message o nowy tag -------------------------- +-------------------------------- Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestrowany jako rozszerzenie dla obiektu Message: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. - + namespace = ExampleTag.namespace #>>>>>>>>>>>> register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i pod-elementów. @@ -416,15 +415,15 @@ Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestro class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML dla tego rozszerzenia.. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. #>>>>>>>>>>>> def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< @@ -434,14 +433,14 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -449,13 +448,13 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. self.send_presence() self.get_roster() self.send_example_message(self.to, "example_message") - + def send_example_message(self, to, body): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Default mtype == "chat"; + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) #>>>>>>>>>>>> - msg['example_tag'].set_some_string("Work!") + msg['example_tag']['some_string'] = "Work!" logging.info(msg) #<<<<<<<<<<<< msg.send() @@ -463,19 +462,19 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , oraz z napisem `'Work'` i nadanym namespace. Nadanie oddzielnego sygnału dla rozszerzonej wiadomości -------------------------- +-------------------------------------------------------- Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. - + namespace = ExampleTag.namespace self.xmpp.register_handler( @@ -501,14 +500,14 @@ Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany name .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -517,10 +516,10 @@ Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany name self.get_roster() #>>>>>>>>>>>> self.send_example_message(self.to, "example_message", "example_string") - + def send_example_message(self, to, body, some_string=""): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Default mtype == "chat"; + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) if some_string: msg['example_tag'].set_some_string(some_string) @@ -532,11 +531,11 @@ Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja handlera @@ -546,92 +545,92 @@ Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W # Metody niewymagane, ale pozwalające na zobaczenie dostępności online. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> def example_tag_message(self, msg): logging.info(msg) # Message jest obiektem który nie wymaga wiadomości zwrotnej, ale nic się nie stanie, gdy zostanie wysłana. #<<<<<<<<<<<< -Można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. +Można odesłać wiadomość, ale nic się nie stanie jeśli to nie zostanie zrobione. Natomiast obiekt komunikacji (Iq) już będzie wymagał odpowiedzi, więc obydwaj klienci powinni pozostawać online. W innym wypadku, klient otrzyma automatyczny error z powodu timeoutu, jeśli cell Iq nie odpowie za pomocą Iq o tym samym Id. Użyteczne metody i inne ------------------------ +------------------------ Modyfikacja przykładowego obiektu `Message` na obiekt `Iq` -------------------------- +---------------------------------------------------------- -Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `"Rozszerzenie Message o tag"`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error, zawierające informacje o przekroczonym czasie oczekiwania (timeout). +Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `,,Rozszerzenie Message o tag''`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error. .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. - + namespace = ExampleTag.namespace #>>>>>>>>>>>> self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag self.__handle_get_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. - + self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag self.__handle_result_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. - + self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag self.__handle_error_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacka StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Iq z example_tag self.__handle_message)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. - + register_stanza_plugin(Iq, ExampleTag) ##~ Rejestruje rozszerzenie taga dla obiektu Iq. W przeciwnym wypadku, Iq['example_tag'] będzie polem string zamiast kontenerem. #<<<<<<<<<<<< register_stanza_plugin(Message, ExampleTag) ##~ Rejestruje rozszerzenie taga dla obiektu Message. W przeciwnym wypadku, message['example_tag'] będzie polem string zamiast kontenerem. - + #>>>>>>>>>>>> # Wszystkie możliwe typy Iq to: get, set, error, result def __handle_get_iq(self, iq): # Zrób coś z otrzymanym iq self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. - + def __handle_result_iq(self, iq): # Zrób coś z otrzymanym Iq self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. - + def __handle_error_iq(self, iq): # Zrób coś z otrzymanym Iq self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. - + def __handle_message(self, msg): # Zrób coś z otrzymanym message self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. - + .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_message", self.example_tag_message) #>>>>>>>>>>>> self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) #<<<<<<<<<<<< - + #>>>>>>>>>>>> def example_tag_get_iq(self, iq): # Iq stanza powinno zawsze zostać zwrócone, w innym wypadku wysyłający dostanie informacje z błędem. logging.info(str(iq)) @@ -644,31 +643,31 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) #<<<<<<<<<<<< - + def start(self, event): # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() - #>>>>>>>>>>>> + #>>>>>>>>>>>> self.send_example_iq(self.to) # Info_inside_tag #<<<<<<<<<<<< - - #>>>>>>>>>>>> + + #>>>>>>>>>>>> def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -677,11 +676,11 @@ Domyślnie parametr `'clear'` dla `'Iq.reply'` jest ustawiony na True. Wtedy to, iq['example_tag'].text = "Info_inside_tag" iq.send() #<<<<<<<<<<<< - + #>>>>>>>>>>>> def example_tag_result_iq(self, iq): logging.info(str(iq)) - + def example_tag_error_iq(self, iq): logging.info(str(iq)) #<<<<<<<<<<<< @@ -694,7 +693,7 @@ Jest kilka możliwości dostania się do pól wewnątrz Message lub Iq. Po pierw .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): #... def example_tag_result_iq(self, iq): @@ -716,44 +715,44 @@ Z rozszerzenia ExampleTag, dostęp do elementów jest podobny, tyle że, nie wym class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. - + #>>>>>>>>>>>> def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text #<<<<<<<<<<<< -Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. +Atrybut `'self.xml'` jest dziedziczony z klasy `'ElementBase'` i jest to dosłownie `'Element'` z pakietu `'ElementTree'`. Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewno podany argument spełnia normy pluginu lub konwersję na pożądany typ. Dodatkowo, kod staje się bardziej przejrzysty w standardach programowania obiektowego, jak na poniższym przykładzie: - + .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -765,7 +764,7 @@ Kiedy odpowiednie gettery i settery są tworzone, można sprawdzić, czy na pewn iq.send() Wczytanie ExampleTag ElementBase z pliku XML, łańcucha znaków i innych obiektów -------------------------- +-------------------------------------------------------------------------------- Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku albo lxml (ElementTree). Poniższy przykład wykorzystuje parsowanie typu tekstowego do lxml (ElementTree) i przekazanie atrybutów. @@ -780,22 +779,22 @@ Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku al class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. - + #>>>>>>>>>>>> def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -806,7 +805,7 @@ Jest wiele możliwości na wczytanie wcześniej zdefiniowanego napisu z pliku al #<<<<<<<<<<<< Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z tagiem, przykładowy napis z xml oraz przykładowy lxml (ET): - + .. code-block:: xml #File: $WORKDIR/test_example_tag.xml @@ -820,69 +819,69 @@ Do przetestowania tej funkcjonalności, potrzebny jest pliku zawierający xml z #... from slixmpp.xmlstream import ET #... - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() - + #>>>>>>>>>>>> - self.disconnect_counter = 3 # Ta zmienna służy tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. - + self.disconnect_counter = 3 # Ta zmienna służy tylko do rozłączenia klienta po otrzymaniu odpowiedniej ilości odpowiedzi z Iq. + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() #<<<<<<<<<<<< Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowiedziach, wtedy wszystko działa tak, jak powinno. Łatwość użycia pluginu dla programistów --------------------------------------- +---------------------------------------- Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. @@ -896,46 +895,46 @@ Poniżej przykład kodu podyktowanego tymi zasadami: import logging from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ Tekst czytelny dla człowieka oraz do znalezienia pluginu przez inny plugin. self.xep = "ope" ##~ Tekst czytelny dla człowieka oraz do znalezienia pluginu przez inny plugin poprzez dodanie go do `slixmpp/plugins/__init__.py` do funkcji `__all__` z 'xep_OPE'. - + namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. - + self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. - + self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacku StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Message z example_tag self.__handle_message)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. - + register_stanza_plugin(Iq, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Iq. Bez tego, iq['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. - + # Wszystkie możliwe typy iq: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: @@ -946,37 +945,37 @@ Poniżej przykład kodu podyktowanego tymi zasadami: error.send() # Zrób coś z otrzymanym Iq self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. - + def __handle_result_iq(self, iq): # Zrób coś z otrzymanym Iq self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. - + def __handle_error_iq(self, iq): # Zrób coś z otrzymanym Iq self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. - + def __handle_message(self, msg): # Zrób coś z otrzymanym Message self.xmpp.event('example_tag_message', msg) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. - + class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. namespace = "https://example.net/our_extension" ##~ Nazwa obiektu, np. . Powinna zostać zmieniona na własną. - + plugin_attrib = "example_tag" ##~ Nazwa, którą można odwołać się do obiektu. W szczególności, do zarejestrowanego obiektu można odwołać się przez: nazwa_obiektu['tag']. gdzie `'tag'` jest nazwą ElementBase extension. Nazwa powinna być taka sama jak "name" wyżej. - + interfaces = {"boolean", "some_string"} ##~ Lista kluczy słownika, które mogą być użyte z obiektem. Na przykład: `stanza_object['example_tag']` zwraca {"another": "some", "data": "some"}, gdzie `'example_tag'` jest nazwą rozszerzenia ElementBase. - + def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -988,25 +987,25 @@ Poniżej przykład kodu podyktowanego tymi zasadami: def setup_from_dict(self, data): #Poprawnośc kluczy słownika powinna być sprawdzona self.xml.attrib.update(data) - + def get_boolean(self): return self.xml.attrib.get("boolean", None) - + def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text - + def fill_interfaces(self, boolean, some_string): #Jakaś walidacja, jeśli jest potrzebna self.set_boolean(boolean) @@ -1019,63 +1018,63 @@ Poniżej przykład kodu podyktowanego tymi zasadami: import logging from argparse import ArgumentParser from getpass import getpass - + import slixmpp import example_plugin - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) self.add_event_handler("example_tag_message", self.example_tag_message) - + def start(self, event): # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() - + def example_tag_get_iq(self, iq): # Iq zawsze powinien odpowiedzieć. Jeżeli użytkownik jest offline, zostanie zwrócony error. logging.info(iq) reply = iq.reply() reply["example_tag"].fill_interfaces(True, "Reply_string") reply.send() - + def example_tag_message(self, msg): logging.info(msg) # Na Message można odpowiedzieć, ale nie trzeba. - - + + if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") parser.add_argument("-t", "--to", dest="to", help="JID to send the message to") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Responder(args.jid, args.password) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPluggin jest nazwa klasy example_plugin - + xmpp.connect() try: xmpp.process() @@ -1093,65 +1092,65 @@ Poniżej przykład kodu podyktowanego tymi zasadami: from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Dwie niewymagane metody pozwalające innym użytkownikom zobaczyć dostępność online self.send_presence() self.get_roster() - + self.disconnect_counter = 5 # Aplikacja rozłączy się po odebraniu takiej ilości odpowiedzi. - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Przykład rozłączania się aplikacji po uzyskaniu odpowiedniej ilości odpowiedzi. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1159,7 +1158,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1167,44 +1166,44 @@ Poniżej przykład kodu podyktowanego tymi zasadami: msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # Kiedy, aby otrzymać odpowiedż z błędem, potrzebny jest example_tag bez wartości bool. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1213,20 +1212,20 @@ Poniżej przykład kodu podyktowanego tymi zasadami: help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin jest nazwą klasy z example_plugin. - + xmpp.connect() try: xmpp.process() @@ -1238,7 +1237,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: Tagi i atrybuty zagnieżdżone wewnątrz głównego elementu --------------------------------------- +--------------------------------------------------------- Aby stworzyć zagnieżdżony tag, wewnątrz głównego tagu, rozważmy atrybut `'self.xml'` jako Element z ET (ElementTree). W takim wypadku, aby stworzyć zagnieżdżony element można użyć funkcji 'append'. @@ -1249,11 +1248,11 @@ Można powtórzyć poprzednie działania inicjalizując nowy element jak główn #File: $WORKDIR/example/example_plugin.py #(...) - + class ExampleTag(ElementBase): - + #(...) - + def add_inside_tag(self, tag, attributes, text=""): #Można rozszerzyć tag o tagi wewnętrzne do tagu, na przykład tak: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Inicjalizujemy Element z wewnętrznym tagiem, na przykład: @@ -1269,17 +1268,17 @@ Kompletny kod tutorialu W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angielskim. .. code-block:: python - + #!/usr/bin/python3 #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - + import subprocess import threading import time - + def start_shell(shell_string): subprocess.run(shell_string, shell=True, universal_newlines=True) - + if __name__ == "__main__": #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal @@ -1287,24 +1286,24 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet postfix = "" - + sender_path = "./example/sender.py" sender_jid = "SENDER_JID" sender_password = "SENDER_PASSWORD" - + example_file = "./test_example_tag.xml" - + responder_path = "./example/responder.py" responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - + # Remember about rights to run your python files. (`chmod +x ./file.py`) SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" - + try: responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) @@ -1320,48 +1319,48 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel #File: $WORKDIR/example/example_plugin.py import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. - + namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object, otherwise iq['example_tag'] will be string field instead container where we can manage our fields and create sub elements. register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container where we can manage our fields and create sub elements. - + # All iq types are: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: @@ -1372,37 +1371,37 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel error.send() # Do something with received iq self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_result_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_error_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_message(self, msg): # Do something with received message self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace our stanza object lives in, like . You should change it for your own namespace - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - + def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -1410,34 +1409,34 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel self.xml.tail = lxml.tail for inner_tag in lxml: self.xml.append(inner_tag) - + def setup_from_dict(self, data): #There should keys should be also validated self.xml.attrib.update(data) - + def get_boolean(self): return self.xml.attrib.get("boolean", None) - + def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text - + def fill_interfaces(self, boolean, some_string): #Some validation if it is necessary self.set_boolean(boolean) self.set_some_string(some_string) - + def add_inside_tag(self, tag, attributes, text=""): #If we want to fill with additionaly tags our element, then we can do it that way for example: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialize ET with our tag, for example: @@ -1450,73 +1449,73 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel .. code-block:: python #File: $WORKDIR/example/sender.py - + import logging from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_iq_with_inner_tag(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1524,18 +1523,18 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_iq_with_inner_tag(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=1) iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - + inner_attributes = {"first_field": "1", "secound_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - + iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1543,44 +1542,44 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1589,20 +1588,20 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + xmpp.connect() try: xmpp.process() @@ -1622,68 +1621,68 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_iq_with_inner_tag(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1691,18 +1690,18 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_iq_with_inner_tag(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=1) iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - + inner_attributes = {"first_field": "1", "secound_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - + iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1710,44 +1709,44 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # For example, our condition to receive error respond is example_tag without boolean value. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1756,20 +1755,20 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + xmpp.connect() try: xmpp.process() @@ -1790,7 +1789,7 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel Info_inside_tag Źródła i bibliogarfia ---------------------- +---------------------- Slixmpp - opis projektu: @@ -1804,4 +1803,4 @@ Oficjalna dokumentacja PDF: * https://buildmedia.readthedocs.org/media/pdf/slixmpp/latest/slixmpp.pdf -Note: Dokumentacje w formie Web i PDF różnią się; pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. +Dokumentacje w formie Web i PDF różnią się; pewne szczegóły potrafią być wspomniane tylko w jednej z dwóch. diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index 501bbe0a..70167592 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -2,7 +2,7 @@ How to make a slixmpp plugins for Messages and IQ extensions ==================================================================== Introduction and requirements ------------------ +------------------------------ * `'python3'` @@ -21,7 +21,7 @@ Ubuntu linux installation steps: * `'subprocess'` * `'threading'` -Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happened that some of them may not be installed. +Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happen that some of them may not be installed. .. code-block:: python @@ -43,7 +43,7 @@ Example output: ~ $ python3 -c "import argparse; print(argparse.__version__)" 1.1 ~ $ python3 -c "import logging; print(logging.__version__)" - 0.5.1.2 + 0.5.1.2 ~ $ python3 -m subprocess #Should return nothing ~ $ python3 -m threading #Should return nothing @@ -62,8 +62,7 @@ If some of the libraries throws NameError, reinstall the whole package once agai * `Jabber accounts` For the testing purposes, two private jabber accounts are required. They can be created on one of many available sites: - -[https://www.google.com/search?q=jabber+server+list](https://www.google.com/search?q=jabber+server+list) +https://www.google.com/search?q=jabber+server+list Client launch script ----------------------------- @@ -86,10 +85,10 @@ This file should be readable and writable only with superuser permission. This f import subprocess import threading import time - + def start_shell(shell_string): subprocess.run(shell_string, shell=True, universal_newlines=True) - + if __name__ == "__main__": #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client; can be replaced with other terminal #~ prefix = "xterm -e" @@ -97,24 +96,24 @@ This file should be readable and writable only with superuser permission. This f #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet postfix = "" - + sender_path = "./example/sender.py" sender_jid = "SENDER_JID" sender_password = "SENDER_PASSWORD" - + example_file = "./test_example_tag.xml" - + responder_path = "./example/responder.py" responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - + # Remember about the executable permission. (`chmod +x ./file.py`) SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" - + try: responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) @@ -125,16 +124,16 @@ This file should be readable and writable only with superuser permission. This f except: print ("Error: unable to start thread") -The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatibility is needed, replace it with `'subprocess.call'` method and adjust accordingly. +The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatibility is needed, replace it with `'subprocess.call'` method and adjust accordingly. The launch script should be convenient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. Logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more things can be defined inside. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. -In case of manually testing the larger applications, it would be a good practise to introduce the unique names (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. +In case of manually testing the larger applications, it would be a good practice to introduce the unique names (consequently, different commands) for each client. In case of any errors, it will be easier to find the client that caused it. Creating the client and the plugin ----------------------------- +----------------------------------- -Two slimxmpp clients should be created in order to check if everything works correctly (here: the `'sender'` and the `'responder'`). The minimal amount of code needed for effective building and testing of the plugin is the following: +Two slixmpp clients should be created in order to check if everything works correctly (here: the `'sender'` and the `'responder'`). The minimal amount of code needed for effective building and testing of the plugin is the following: .. code-block:: python @@ -143,36 +142,36 @@ Two slimxmpp clients should be created in order to check if everything works cor from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) - def start(self, event): - # Two, not required methods, but allows another users to see if the client is online. - self.send_presence() - self.get_roster() + def start(self, event): + # Two, not required methods, but allows another users to see if the client is online. + self.send_presence() + self.get_roster() if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -181,17 +180,17 @@ Two slimxmpp clients should be created in order to check if everything works cor help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is the example_plugin class name. @@ -210,16 +209,16 @@ Two slimxmpp clients should be created in order to check if everything works cor import logging from argparse import ArgumentParser from getpass import getpass - + import slixmpp import example_plugin - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) - + def start(self, event): # Two, not required methods, but allows another users to see if the client is online. self.send_presence() @@ -227,34 +226,34 @@ Two slimxmpp clients should be created in order to check if everything works cor if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") parser.add_argument("-t", "--to", dest="to", help="JID to send the message to") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Responder(args.jid, args.password) #xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is the example_plugin class name. - + xmpp.connect() try: xmpp.process() @@ -264,39 +263,39 @@ Two slimxmpp clients should be created in order to check if everything works cor except: pass -Next file to create is `'example_plugin.py'`. It can be placed in the same catalogue as the clients, so the problems with unknown paths can be avoided. +Next file to create is `'example_plugin.py'`. It can be placed in the same folder as the clients, so the problems with unknown paths can be avoided. .. code-block:: python - #File: $WORKDIR/example/example plugin.py + #File: $WORKDIR/example/example_plugin.py import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. self.xep = "ope" ##~ String data readable by humans and to find plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` field, with 'xep_OPE' prefix. - + namespace = ExampleTag.namespace class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element for that extension. namespace = "" ##~ The namespace of the object, like . Should be changed to your namespace. - + plugin_attrib = "example_tag" ##~ The name under which the data in plugin can be accessed. In particular, this object is reachable from the outside with: stanza_object['example_tag']. The `'example_tag'` is name of ElementBase extension and should be that same as the name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. If the plugin is not in the same directory as the clients, then the symbolic link to the localisation reachable by the clients should be established: @@ -330,23 +329,23 @@ The `'def start(self, event):'` method should look like this: If everything works fine, this line can be commented out. Building the message object -------------------------- +------------------------------ -The example sender class should get a recipient name and address (jid of responder) from command line arguments, stored in test_slixmpp. An access to this argument is stored in the `'self.to'`attribute. +The example sender class should get a recipient name and address (jid of responder) from command line arguments, stored in test_slixmpp. An access to this argument is stored in the `'self.to'` attribute. Code example: .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -355,10 +354,10 @@ Code example: self.get_roster() #>>>>>>>>>>>> self.send_example_message(self.to, "example_message") - + def send_example_message(self, to, body): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Default mtype == "chat"; + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) msg.send() #<<<<<<<<<<<< @@ -370,13 +369,13 @@ To receive this message, the responder should have a proper handler to the signa .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) - + #>>>>>>>>>>>> self.add_event_handler("message", self.message) #<<<<<<<<<<<< @@ -385,7 +384,7 @@ To receive this message, the responder should have a proper handler to the signa # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> def message(self, msg): #Show all inside msg @@ -395,19 +394,19 @@ To receive this message, the responder should have a proper handler to the signa #<<<<<<<<<<<< Expanding the Message with a new tag -------------------------- +------------------------------------- To expand the Message object with a tag, the plugin should be registered as the extension for the Message object: .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data readable by humans and to find plugin by another plugin. self.xep = "ope" ##~ String data readable by humans and to find plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. - + namespace = ExampleTag.namespace #>>>>>>>>>>>> register_stanza_plugin(Message, ExampleTag) ##~ Register the tag extension for Message object, otherwise message['example_tag'] will be string field instead container and managing fields and create sub elements would be impossible. @@ -416,15 +415,15 @@ To expand the Message object with a tag, the plugin should be registered as the class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace for stanza object, like . - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as 'name' above. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. #>>>>>>>>>>>> def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string #<<<<<<<<<<<< @@ -434,14 +433,14 @@ Now, with the registered object, the message can be extended. .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -449,13 +448,13 @@ Now, with the registered object, the message can be extended. self.send_presence() self.get_roster() self.send_example_message(self.to, "example_message") - + def send_example_message(self, to, body): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Default mtype == "chat"; + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) #>>>>>>>>>>>> - msg['example_tag'].set_some_string("Work!") + msg['example_tag']['some_string'] = "Work!" logging.info(msg) #<<<<<<<<<<<< msg.send() @@ -463,19 +462,19 @@ Now, with the registered object, the message can be extended. After running, the logging should print the Message with tag `'example_tag'` stored inside , string `'Work'` and given namespace. Giving the extended message the separate signal -------------------------- +------------------------------------------------ If the separate event is not defined, then both normal and extended message will be cached by signal `'message'`. In order to have the special event, the handler for the namespace and tag should be created. Then, make a unique name combination, which allows the handler can catch only the wanted messages (or Iq object). .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data readable by humans and to find the plugin by another plugin. self.xep = "ope" ##~ String data readable by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. - + namespace = ExampleTag.namespace self.xmpp.register_handler( @@ -501,14 +500,14 @@ Now every message containing the defined namespace inside `'example_tag'` is cac .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) def start(self, event): @@ -517,10 +516,10 @@ Now every message containing the defined namespace inside `'example_tag'` is cac self.get_roster() #>>>>>>>>>>>> self.send_example_message(self.to, "example_message", "example_string") - + def send_example_message(self, to, body, some_string=""): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) - # Default mtype == "chat"; + # Default mtype == "chat"; msg = self.make_message(mto=to, mbody=body) if some_string: msg['example_tag'].set_some_string(some_string) @@ -532,11 +531,11 @@ Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The nam .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> self.add_event_handler("example_tag_message", self.example_tag_message) #Registration of the handler @@ -546,7 +545,7 @@ Now, remember the line: `'self.xmpp.event('example_tag_message', msg)'`. The nam # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> def example_tag_message(self, msg): logging.info(msg) # Message is standalone object, it can be replied, but no error is returned if not. @@ -556,62 +555,62 @@ The messages can be replied, but nothing will happen otherwise. The Iq object, on the other hand, should always be replied. Otherwise, the error occurs on the client side due to the target timeout if the cell Iq won't reply with Iq with the same Id. Useful methods and misc. ------------------------ +------------------------- Modifying the example `Message` object to the `Iq` object -------------------------- +---------------------------------------------------------- -To convert the Message into the Iq object, a new handler for the Iq should be registered, in the same manner as in the `,,Extend message with tags''`part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender receives the Iq with the timeout error. +To allow our custom element into Iq payloads, a new handler for Iq can be registered, in the same manner as in the `,,Extend message with tags''` part. The following example contains several types of Iq different types to catch. It can be used to check the difference between the Iq request and Iq response or to verify the correctness of the objects. All of the Iq messages should be passed to the sender with the same ID parameter, otherwise the sender will receive an error message. .. code-block:: python #File: $WORKDIR/example/example plugin.py - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data readable by humans and to find the plugin by another plugin. self.xep = "ope" ##~ String data readable by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. - + namespace = ExampleTag.namespace #>>>>>>>>>>>> self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'get' and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'result' and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'error' and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. #<<<<<<<<<<<< register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Message object, otherwise message['example_tag'] will be string field instead container, where it is impossible to manage fields and create sub elements. - + #>>>>>>>>>>>> # All iq types are: get, set, error, result def __handle_get_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_get_iq', iq) ##~ Calls the event which can be handled by clients. - + def __handle_result_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_result_iq', iq) ##~ Calls the event which can be handled by clients. - + def __handle_error_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_error_iq', iq) ##~ Calls the event which can be handled by clients. - + def __handle_message(self, msg): # Do something with received message self.xmpp.event('example_tag_message', msg) ##~ Calls the event which can be handled by clients. @@ -621,17 +620,17 @@ The events called by the example handlers can be caught like in the`'example_tag .. code-block:: python #File: $WORKDIR/example/responder.py - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_message", self.example_tag_message) #>>>>>>>>>>>> self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) #<<<<<<<<<<<< - + #>>>>>>>>>>>> def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it calls an error. logging.info(str(iq)) @@ -639,36 +638,36 @@ The events called by the example handlers can be caught like in the`'example_tag reply.send() #<<<<<<<<<<<< -By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that case, the content of the Iq should be set again. After using the reply method, only the Id and the Jid parameters will still be set. +By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that case, the content of the Iq should be set again. After using the reply method, only the Id and the Jid parameters will still be set. .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) #<<<<<<<<<<<< - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - #>>>>>>>>>>>> + #>>>>>>>>>>>> self.send_example_iq(self.to) # Info_inside_tag #<<<<<<<<<<<< - - #>>>>>>>>>>>> + + #>>>>>>>>>>>> def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -677,24 +676,24 @@ By default, the parameter `'clear'` in the `'Iq.reply'` is set to True. In that iq['example_tag'].text = "Info_inside_tag" iq.send() #<<<<<<<<<<<< - + #>>>>>>>>>>>> def example_tag_result_iq(self, iq): logging.info(str(iq)) - + def example_tag_error_iq(self, iq): logging.info(str(iq)) #<<<<<<<<<<<< Different ways to access the elements -------------------------- +-------------------------------------- There are several ways to access the elements inside the Message or Iq stanza. The first one: the client can access them like a dictionary: .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): #... def example_tag_result_iq(self, iq): @@ -716,21 +715,21 @@ The access to the elements from extended ExampleTag is similar. However, definin class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace for stanza object, like . Should be changed to own namespace. - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'], the `'example_tag'` is the name of ElementBase extension. And this should be the same as name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. - + #>>>>>>>>>>>> def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text #<<<<<<<<<<<< @@ -742,18 +741,18 @@ When the proper setters and getters are used, it is easy to check whether some a .. code-block:: python #File: $WORKDIR/example/sender.py - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -765,7 +764,7 @@ When the proper setters and getters are used, it is easy to check whether some a iq.send() Message setup from the XML files, strings and other objects -------------------------- +------------------------------------------------------------ There are many ways to set up a xml from a string, xml-containing file or lxml (ElementTree) file. One of them is parsing the strings to lxml object, passing the attributes and other information, which may look like this: @@ -780,22 +779,22 @@ There are many ways to set up a xml from a string, xml-containing file or lxml ( class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The stanza object namespace, like . Should be changed to your own namespace - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. - + #>>>>>>>>>>>> def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -820,62 +819,62 @@ To test this, an example file with xml, example xml string and example lxml (ET) #... from slixmpp.xmlstream import ET #... - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + #>>>>>>>>>>>> self.disconnect_counter = 3 # Disconnects when all replies from Iq are received. - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_tag_from_string(self.to, string) - # Info_inside_tag + # Info_inside_tag def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after receiving the maximum number of responses. - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() #<<<<<<<<<<<< @@ -896,46 +895,46 @@ The following code presents exactly this: import logging from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data to read by humans and to find the plugin by another plugin. self.xep = "ope" ##~ String data to read by humans and to find the plugin by another plugin by adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. - + namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'get' and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'result' and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type 'error' and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. - + # All iq types are: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: @@ -946,37 +945,37 @@ The following code presents exactly this: error.send() # Do something with received iq self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something else. - + def __handle_result_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something else. - + def __handle_error_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something else. - + def __handle_message(self, msg): # Do something with received message self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something else. - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The namespace stanza object lives in, like . You should change it for your own namespace. - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ElementBase extension. And this should be that same as name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ElementBase extension. - + def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -988,25 +987,25 @@ The following code presents exactly this: def setup_from_dict(self, data): #There keys from dict should be also validated self.xml.attrib.update(data) - + def get_boolean(self): return self.xml.attrib.get("boolean", None) - + def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text - + def fill_interfaces(self, boolean, some_string): #Some validation, if necessary self.set_boolean(boolean) @@ -1019,63 +1018,63 @@ The following code presents exactly this: import logging from argparse import ArgumentParser from getpass import getpass - + import slixmpp import example_plugin - + class Responder(slixmpp.ClientXMPP): def __init__(self, jid, password): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_get_iq", self.example_tag_get_iq) self.add_event_handler("example_tag_message", self.example_tag_message) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + def example_tag_get_iq(self, iq): # Iq stanza always should have a respond. If user is offline, it call an error. logging.info(iq) reply = iq.reply() reply["example_tag"].fill_interfaces(True, "Reply_string") reply.send() - + def example_tag_message(self, msg): logging.info(msg) # Message is standalone object, it can be replied, but no error arrives if not. - - + + if __name__ == '__main__': parser = ArgumentParser(description=Responder.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", help="password to use") parser.add_argument("-t", "--to", dest="to", help="JID to send the message to") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Responder(args.jid, args.password) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + xmpp.connect() try: xmpp.process() @@ -1093,65 +1092,65 @@ The following code presents exactly this: from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + self.disconnect_counter = 5 # # Disconnect after receiving the maximum number of responses. - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after receiving the maximum number of responses. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after receiving the maximum number of responses. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1159,7 +1158,7 @@ The following code presents exactly this: iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1167,44 +1166,44 @@ The following code presents exactly this: msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # For example, the condition to receive the error respond is the example_tag without the boolean value. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1213,20 +1212,20 @@ The following code presents exactly this: help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin. - + xmpp.connect() try: xmpp.process() @@ -1248,11 +1247,11 @@ As shown in the previous examples, it is possible to create a new element as mai #File: $WORKDIR/example/example_plugin.py #(...) - + class ExampleTag(ElementBase): - + #(...) - + def add_inside_tag(self, tag, attributes, text=""): #If more tags is needed inside the element, they can be added like that: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialise ET with tag, for example: @@ -1263,20 +1262,20 @@ As shown in the previous examples, it is possible to create a new element as mai There is a way to do this with a dictionary and name for the nested element tag. In that case, the insides of the function fields should be transferred to the ET element. Complete code from tutorial -------------------------- +---------------------------- .. code-block:: python #!/usr/bin/python3 #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - + import subprocess import threading import time - + def start_shell(shell_string): subprocess.run(shell_string, shell=True, universal_newlines=True) - + if __name__ == "__main__": #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal @@ -1284,24 +1283,24 @@ Complete code from tutorial #~ postfix = " -d" # Debug #~ postfix = " -q" # Quiet postfix = "" - + sender_path = "./example/sender.py" sender_jid = "SENDER_JID" sender_password = "SENDER_PASSWORD" - + example_file = "./test_example_tag.xml" - + responder_path = "./example/responder.py" responder_jid = "RESPONDER_JID" responder_password = "RESPONDER_PASSWORD" - + # Remember about rights to run your python files. (`chmod +x ./file.py`) SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ " -t {responder_jid} --path {example_file} {postfix}" - + RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ " -p {responder_password} {postfix}" - + try: responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) @@ -1317,48 +1316,48 @@ Complete code from tutorial #File: $WORKDIR/example/example_plugin.py import logging - + from slixmpp.xmlstream import ElementBase, ET, register_stanza_plugin - + from slixmpp import Iq from slixmpp import Message - + from slixmpp.plugins.base import BasePlugin - + from slixmpp.xmlstream.handler import Callback from slixmpp.xmlstream.matcher import StanzaPath - + log = logging.getLogger(__name__) - + class OurPlugin(BasePlugin): def plugin_init(self): self.description = "OurPluginExtension" ##~ String data for Human readable and find plugin by another plugin with method. self.xep = "ope" ##~ String data for Human readable and find plugin by another plugin with adding it into `slixmpp/plugins/__init__.py` to the `__all__` declaration with 'xep_OPE'. Otherwise it's just human readable annotation. - + namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Handle only Iq with type get and example_tag self.__handle_get_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Handle only Iq with type result and example_tag self.__handle_result_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Name of this Callback StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Handle only Iq with type error and example_tag self.__handle_error_iq)) ##~ Method which catch proper Iq, should raise proper event for client. - + self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Name of this Callback StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Handle only Message with example_tag self.__handle_message)) ##~ Method which catch proper Message, should raise proper event for client. - + register_stanza_plugin(Iq, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. register_stanza_plugin(Message, ExampleTag) ##~ Register tags extension for Iq object. Otherwise the iq['example_tag'] will be string field instead of container and it would not be possible to manage the fields and sub elements. - + # All iq types are: get, set, error, result def __handle_get_iq(self, iq): if iq.get_some_string is None: @@ -1369,37 +1368,37 @@ Complete code from tutorial error.send() # Do something with received iq self.xmpp.event('example_tag_get_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_result_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_result_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_error_iq(self, iq): # Do something with received iq self.xmpp.event('example_tag_error_iq', iq) ##~ Call event which can be handled by clients to send or something other what you want. - + def __handle_message(self, msg): # Do something with received message self.xmpp.event('example_tag_message', msg) ##~ Call event which can be handled by clients to send or something other what you want. - + class ExampleTag(ElementBase): name = "example_tag" ##~ The name of the root XML element of that extension. namespace = "https://example.net/our_extension" ##~ The stanza object namespace, like . Should be changed for your namespace. - + plugin_attrib = "example_tag" ##~ The name to access this type of stanza. In particular, given a registration stanza, the Registration object can be found using: stanza_object['example_tag'] now `'example_tag'` is name of ours ElementBase extension. And this should be that same as name. - + interfaces = {"boolean", "some_string"} ##~ A list of dictionary-like keys that can be used with the stanza object. For example `stanza_object['example_tag']` gives us {"another": "some", "data": "some"}, whenever `'example_tag'` is name of ours ElementBase extension. - + def setup_from_string(self, string): """Initialize tag element from string""" et_extension_tag_xml = ET.fromstring(string) self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_file(self, path): """Initialize tag element from file containing adjusted data""" et_extension_tag_xml = ET.parse(path).getroot() self.setup_from_lxml(et_extension_tag_xml) - + def setup_from_lxml(self, lxml): """Add ET data to self xml structure.""" self.xml.attrib.update(lxml.attrib) @@ -1407,34 +1406,34 @@ Complete code from tutorial self.xml.tail = lxml.tail for inner_tag in lxml: self.xml.append(inner_tag) - + def setup_from_dict(self, data): #There should keys should be also validated self.xml.attrib.update(data) - + def get_boolean(self): return self.xml.attrib.get("boolean", None) - + def get_some_string(self): return self.xml.attrib.get("some_string", None) - + def get_text(self, text): return self.xml.text - + def set_boolean(self, boolean): self.xml.attrib['boolean'] = str(boolean) - + def set_some_string(self, some_string): self.xml.attrib['some_string'] = some_string - + def set_text(self, text): self.xml.text = text - + def fill_interfaces(self, boolean, some_string): #Some validation if it is necessary self.set_boolean(boolean) self.set_some_string(some_string) - + def add_inside_tag(self, tag, attributes, text=""): #If more tags is needed inside the element, they can be added like that: itemXML = ET.Element("{{{0:s}}}{1:s}".format(self.namespace, tag)) #~ Initialise ET with tag, for example: @@ -1447,73 +1446,73 @@ Complete code from tutorial .. code-block:: python #File: $WORKDIR/example/sender.py - + import logging from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sent Iq - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_iq_with_inner_tag(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1521,18 +1520,18 @@ Complete code from tutorial iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_iq_with_inner_tag(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=1) iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - + inner_attributes = {"first_field": "1", "second_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - + iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1540,44 +1539,44 @@ Complete code from tutorial msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # For example, the condition to receive error respond is the example_tag without boolean value. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1586,20 +1585,20 @@ Complete code from tutorial help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + xmpp.connect() try: xmpp.process() @@ -1619,68 +1618,68 @@ Complete code from tutorial from argparse import ArgumentParser from getpass import getpass import time - + import slixmpp from slixmpp.xmlstream import ET - + import example_plugin - + class Sender(slixmpp.ClientXMPP): def __init__(self, jid, password, to, path): slixmpp.ClientXMPP.__init__(self, jid, password) - + self.to = to self.path = path - + self.add_event_handler("session_start", self.start) self.add_event_handler("example_tag_result_iq", self.example_tag_result_iq) self.add_event_handler("example_tag_error_iq", self.example_tag_error_iq) - + def start(self, event): # Two, not required methods, but allows another users to see us available, and receive that information. self.send_presence() self.get_roster() - + self.disconnect_counter = 6 # This is only for disconnect when we receive all replies for sended Iq - + self.send_example_iq(self.to) # Info_inside_tag - + self.send_example_iq_with_inner_tag(self.to) # Info_inside_tag - + self.send_example_message(self.to) # Info_inside_tag_message - + self.send_example_iq_tag_from_file(self.to, self.path) # Info_inside_tag - + string = 'Info_inside_tag' et = ET.fromstring(string) self.send_example_iq_tag_from_element_tree(self.to, et) # Info_inside_tag - + self.send_example_iq_to_get_error(self.to) # # OUR ERROR Without boolean value returns error. # OFFLINE ERROR User session not found - + self.send_example_iq_tag_from_string(self.to, string) # Info_inside_tag - - + + def example_tag_result_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def example_tag_error_iq(self, iq): self.disconnect_counter -= 1 logging.info(str(iq)) if not self.disconnect_counter: self.disconnect() # Example disconnect after first received iq stanza extended by example_tag with result type. - + def send_example_iq(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get") @@ -1688,18 +1687,18 @@ Complete code from tutorial iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") iq.send() - + def send_example_iq_with_inner_tag(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=1) iq['example_tag'].set_some_string("Another_string") iq['example_tag'].set_text("Info_inside_tag") - + inner_attributes = {"first_field": "1", "second_field": "2"} iq['example_tag'].add_inside_tag(tag="inside_tag", attributes=inner_attributes) - + iq.send() - + def send_example_message(self, to): #~ make_message(mfrom=None, mto=None, mtype=None, mquery=None) msg = self.make_message(mto=to) @@ -1707,44 +1706,44 @@ Complete code from tutorial msg['example_tag'].set_some_string("Message string") msg['example_tag'].set_text("Info_inside_tag_message") msg.send() - + def send_example_iq_tag_from_file(self, to, path): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=2) iq['example_tag'].setup_from_file(path) - + iq.send() - + def send_example_iq_tag_from_element_tree(self, to, et): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=3) iq['example_tag'].setup_from_lxml(et) - + iq.send() - + def send_example_iq_to_get_error(self, to): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=4) iq['example_tag'].set_boolean(True) # For example, the condition for receivingg error respond is example_tag without boolean value. iq.send() - + def send_example_iq_tag_from_string(self, to, string): #~ make_iq(id=0, ifrom=None, ito=None, itype=None, iquery=None) iq = self.make_iq(ito=to, itype="get", id=5) iq['example_tag'].setup_from_string(string) - + iq.send() - + if __name__ == '__main__': parser = ArgumentParser(description=Sender.__doc__) - + parser.add_argument("-q", "--quiet", help="set logging to ERROR", action="store_const", dest="loglevel", const=logging.ERROR, default=logging.INFO) parser.add_argument("-d", "--debug", help="set logging to DEBUG", action="store_const", dest="loglevel", const=logging.DEBUG, default=logging.INFO) - + parser.add_argument("-j", "--jid", dest="jid", help="JID to use") parser.add_argument("-p", "--password", dest="password", @@ -1753,20 +1752,20 @@ Complete code from tutorial help="JID to send the message/iq to") parser.add_argument("--path", dest="path", help="path to load example_tag content") - + args = parser.parse_args() - + logging.basicConfig(level=args.loglevel, format=' %(name)s - %(levelname)-8s %(message)s') - + if args.jid is None: args.jid = input("Username: ") if args.password is None: args.password = getpass("Password: ") - + xmpp = Sender(args.jid, args.password, args.to, args.path) xmpp.register_plugin('OurPlugin', module=example_plugin) # OurPlugin is a class name from example_plugin - + xmpp.connect() try: xmpp.process() @@ -1787,7 +1786,7 @@ Complete code from tutorial Info_inside_tag Sources and references ---------------------- +----------------------- The Slixmpp project description: -- cgit v1.2.3 From 1314e704605a92f18eb81236b7ebdb25dabb497c Mon Sep 17 00:00:00 2001 From: Paulina Date: Tue, 14 Apr 2020 21:21:35 +0200 Subject: Changing the use of 'threading' in python for more suitable 'subprocesses'. Change of English names to Polish equivalents, as requested by the authors. --- ...make_plugin_extension_for_message_and_iq.pl.rst | 269 ++++++++++----------- .../make_plugin_extension_for_message_and_iq.rst | 185 +++++++------- 2 files changed, 220 insertions(+), 234 deletions(-) (limited to 'docs/howto') diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst index b85c01f5..fb00cbf7 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.pl.rst @@ -19,7 +19,6 @@ Instalacja dla Ubuntu linux: * `'argparse'` * `'logging'` * `'subprocess'` -* `'threading'` Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do standardowej biblioteki pythona. Zdarza się, że kompilując źródła samodzielnie, część z nich może nie zostać zainstalowana. @@ -30,7 +29,6 @@ Wszystkie biblioteki wymienione powyżej, za wyjątkiem slixmpp, należą do sta python3 -c "import argparse; print(argparse.__version__)" python3 -c "import logging; print(logging.__version__)" python3 -m subprocess - python3 -m threading Wynik w terminalu: @@ -45,7 +43,6 @@ Wynik w terminalu: ~ $ python3 -c "import logging; print(logging.__version__)" 0.5.1.2 ~ $ python3 -m subprocess # Nie powinno nic zwrócić - ~ $ python3 -m threading # Nie powinno nic zwrócić Jeśli któraś z bibliotek zwróci `'ImportError'` lub `'no module named ...'`, należy je zainstalować zgodnie z przykładem poniżej: @@ -75,56 +72,53 @@ Przykładowo, można stworzyć plik o nazwie `'test_slixmpp'` w lokalizacji `'/u /usr/bin $ chmod 711 test_slixmpp -Taki plik powinien wymagać uprawnień superuser do odczytu i edycji. Plik zawiera prostą strukturę, która pozwoli nam zapisać dane logowania. +Plik zawiera prostą strukturę, która pozwoli nam zapisać dane logowania. .. code-block:: python - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Oddzielny terminal dla każdego klienta, można zastąpić własnym emulatorem terminala - #~ prefix = "xterm -e" - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Pamiętaj o nadaniu praw do wykonywania (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") - -Funkcja `'subprocess.run()'` jest kompatybilna z Pythonem 3.5+. Dla uzyskania wcześniejszej kompatybilności można podmienić ją metodą `'subprocess.call()'` i dostosować argumenty. +#!/usr/bin/python3 +#File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + +import subprocess +import time + +if __name__ == "__main__": + #~ prefix = ["x-terminal-emulator", "-e"] # Osobny terminal dla kazdego klienta, może być zastąpiony inną konsolą. + #~ prefix = ["xterm", "-e"] + prefix = [] + #~ suffix = ["-d"] # Debug + #~ suffix = ["-q"] # Quiet + suffix = [] + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about the executable permission. (`chmod +x ./file.py`) + SENDER_TEST = prefix + [sender_path, "-j", sender_jid, "-p", sender_password, "-t", responder_jid, "--path", example_file] + suffix + RESPON_TEST = prefix + [responder_path, "-j", responder_jid, "-p", responder_password] + suffix + + try: + responder = subprocess.Popen(RESPON_TEST) + sender = subprocess.Popen(SENDER_TEST) + responder.wait() + sender.wait() + except: + try: + responder.terminate() + except NameError: + pass + try: + sender.terminate() + except NameError: + pass + raise Skrypt uruchamiający powinien być dostosowany do potrzeb urzytkownika: można w nim pobierać ścieżki do projektu z linii komend (przez `'sys.argv[...]'` lub `'os.getcwd()'`), wybierać z jaką flagą mają zostać uruchomione programy oraz wiele innych. Jego należyte przygotowanie pozwoli zaoszczędzić czas i nerwy podczas późniejszych prac. @@ -306,12 +300,12 @@ Jeżeli powyższy plugin nie jest w domyślnej lokalizacji, a klienci powinni po Jeszcze innym wyjściem jest import relatywny z użyciem kropek '.' aby dostać się do właściwej ścieżki. -Pierwsze uruchomienie i przechwytywanie eventów ------------------------------------------------ +Pierwsze uruchomienie i przechwytywanie zdarzeń +------------------------------------------------- -Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisany event `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. +Aby sprawdzić czy wszystko działa prawidłowo, można użyć metody `'start'`. Jest jej przypisane zdarzenie `'session_start'`. Sygnał ten zostanie wysłany w momencie, w którym klient będzie gotów do działania. Stworzenie własnej metoda pozwoli na zdefiniowanie działania tego sygnału. -W metodzie `'__init__'` zostało stworzone przekierowanie eventu `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a następnie użyć komendy `'test_slixmpp'`. +W metodzie `'__init__'` zostało stworzone przekierowanie zdarzenia `'session_start'`. Kiedy zostanie on wywołany, metoda `'def start(self, event):'` zostanie wykonana. Jako pierwszy krok procesie tworzenia, można dodać linię `'logging.info("I'm running")'` w obu klientach (sender i responder), a następnie użyć komendy `'test_slixmpp'`. Metoda `'def start(self, event):'` powinna wyglądać tak: @@ -364,7 +358,7 @@ Przykład: W przykładzie powyżej, używana jest wbudowana metoda `'make_message'`, która tworzy wiadomość o treści `'example_message'` i wysyła ją pod koniec działania metody start. Czyli: wiadomość ta zostanie wysłana raz, zaraz po uruchomieniu skryptu. -Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiedni event: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie został przypisany żaden inny event. Przykład takiego kodu: +Aby otrzymać tę wiadomość, responder powinien wykorzystać odpowiednie zdarzenie: metodę, która określa co zrobić, gdy zostanie odebrana wiadomość której nie zostało przypisane żadne inne zdarzenie. Przykład takiego kodu: .. code-block:: python @@ -404,8 +398,8 @@ Aby rozszerzyć obiekt Message o wybrany tag, plugin powinien zostać zarejestro class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. - self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. + self.description = "OurPluginExtension" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> @@ -459,12 +453,12 @@ Teraz, po rejestracji tagu, można rozszerzyć wiadomość. #<<<<<<<<<<<< msg.send() -Po uruchomieniu, logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , oraz z napisem `'Work'` i nadanym namespace. +Po uruchomieniu, obiekt logging powinien wyświetlić Message wraz z tagiem `'example_tag'` zawartym w środku , oraz z napisem `'Work'` i nadaną przestrzenią nazw. Nadanie oddzielnego sygnału dla rozszerzonej wiadomości -------------------------------------------------------- -Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielny event, należy zarejestrować odpowiedni handler dla namespace'a i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). +Jeśli zdarzenie nie zostanie sprecyzowane, to zarówno rozszerzona jak i podstawowa wiadomość będą przechwytywane przez sygnał `'message'`. Aby nadać im oddzielne zdarzenie, należy zarejestrować odpowiedni uchwyt dla przestrzeni nazw i tagu, aby stworzyć unikalną kombinację, która pozwoli na przechwycenie wyłącznie pożądanych wiadomości (lub Iq object). .. code-block:: python @@ -472,30 +466,30 @@ Jeśli event nie zostanie sprecyzowany, to zarówno rozszerzona jak i podstawowa class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. - self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. + self.description = "OurPluginExtension" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callback - StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytuje wyłącznie Message z tagiem example_tag i namespace takim jaki zdefiniowaliśmy w ExampleTag - self.__handle_message)) ##~ Metoda do której zostaje przypisany przechwycony odpowiedni obiekt, powinna wywołać odpowiedni event dla klienta. + StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Przechwytuje wyłącznie Message z tagiem example_tag i przestrzenią nazw taką, jaką zdefiniowaliśmy w ExampleTag + self.__handle_message)) ##~ Metoda do której zostaje przypisany przechwycony odpowiedni obiekt, powinna wywołać odpowiedni dla klienta wydarzenie. register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowany rozszerzony tag dla obiektu Message. Jeśli to nie zostanie zrobione, message['example_tag'] będzie polem tekstowym, a nie rozszerzeniem i nie będzie mogło zawierać atrybutów i pod-elementów. def __handle_message(self, msg): # Tu można coś zrobić z przechwyconą wiadomością zanim trafi do klienta. - self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może zostać przechwycony i obsłużony przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do eventu. + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje zdarzenie, które może zostać przechwycone i obsłużone przez klienta, jako argument przekazujemy obiekt który chcemy dopiąć do wydarzenia. Obiekt StanzaPath powinien być poprawnie zainicjalizowany, według schematu: `'NAZWA_OBIEKTU[@type=TYP_OBIEKTU][/{NAMESPACE}[TAG]]'` * Dla NAZWA_OBIEKTU można użyć `'message'` lub `'iq'`. -* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można użyć typu spośród: `'get, set, error or result'`. Jeśli obiektem jest message, można sprecyzować typ dla message, np. `'chat'`.. -* Dla NAMESPACE powinien to być namespace zgodny z rozszerzeniem tagu. +* Dla TYP_OBIEKTU, jeśli obiektem jest iq, można użyć typu spośród: `'get, set, error or result'`. Jeśli obiektem jest Message, można sprecyzować typ np. `'chat'`.. +* Dla NAMESPACE powinna to byc przestrzeń nazw zgodna z rozszerzeniem tagu. * TAG powinien zawierać tag, tutaj: `'example_tag'`. -Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany namespace wewnątrz `'example_tag'`. Można też sprawdzić co message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomość jest wysyłana do klienta za pośrednictwem eventu `'example_tag_message'`. +Teraz program przechwyci wszystkie wiadomości typu message, które zawierają sprecyzowaną przestrzeń nazw wewnątrz `'example_tag'`. Można też sprawdzić co Message zawiera, czy na pewno posiada wymagane pola itd. Następnie wiadomość jest wysyłana do klienta za pośrednictwem wydarzenia `'example_tag_message'`. .. code-block:: python @@ -526,7 +520,7 @@ Teraz, program przechwyci wszystkie message, które zawierają sprecyzowany name msg.send() #<<<<<<<<<<<< -Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa eventu do przechwycenia wewnątrz pliku "responder.py". Tutaj to: `'example_tag_message'`. +Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W tej linii została zdefiniowana nazwa zdarzenia do przechwycenia wewnątrz pliku "responder.py". Tutaj to: `'example_tag_message'`. .. code-block:: python @@ -538,7 +532,7 @@ Należy zapamiętać linię: `'self.xmpp.event('example_tag_message', msg)'`. W self.add_event_handler("session_start", self.start) #>>>>>>>>>>>> - self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja handlera + self.add_event_handler("example_tag_message", self.example_tag_message) # Rejestracja uchwytu #<<<<<<<<<<<< def start(self, event): @@ -560,7 +554,7 @@ Użyteczne metody i inne Modyfikacja przykładowego obiektu `Message` na obiekt `Iq` ---------------------------------------------------------- -Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy handler dla Iq, podobnie jak zostało to przedstawione w rozdziale `,,Rozszerzenie Message o tag''`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error. +Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować nowy uchwyt (handler) dla Iq, podobnie jak zostało to przedstawione w rozdziale `,,Rozszerzenie Message o tag''`. Tym razem, przykład będzie zawierał kilka rodzajów Iq o oddzielnych typami. Poprawia to czytelność kodu oraz usprawnia weryfikację poprawności działania. Wszystkie Iq powinny odesłać odpowiedź z tym samym Id i odpowiedzią do wysyłającego. W przeciwnym wypadku, wysyłający dostanie Iq zwrotne typu error. .. code-block:: python @@ -568,30 +562,30 @@ Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować class OurPlugin(BasePlugin): def plugin_init(self): - self.description = "OurPluginExtension" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. - self.xep = "ope" ##~ String zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. + self.description = "OurPluginExtension" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin. + self.xep = "ope" ##~ Napis zrozumiały dla ludzi oraz do znalezienia pluginu przez inny plugin przez dodanie go do `slixmpp/plugins/__init__.py` w metodzie `__all__` z 'xep_OPE'. namespace = ExampleTag.namespace #>>>>>>>>>>>> self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag - self.__handle_get_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. + self.__handle_get_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać zdarzenie dla klienta. self.xmpp.register_handler( Callback('ExampleResult Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=result/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag - self.__handle_result_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. + self.__handle_result_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać zdarzenie dla klienta. self.xmpp.register_handler( Callback('ExampleError Event:example_tag', ##~ Nazwa tego Callbacka StanzaPath(f"iq@type=error/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag - self.__handle_error_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. + self.__handle_error_iq)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać zdarzenie dla klienta. self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacka StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Iq z example_tag - self.__handle_message)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać event dla klienta. + self.__handle_message)) ##~ Metoda obsługująca odpowiednie Iq, powinna wywołać zdarzenie dla klienta. register_stanza_plugin(Iq, ExampleTag) ##~ Rejestruje rozszerzenie taga dla obiektu Iq. W przeciwnym wypadku, Iq['example_tag'] będzie polem string zamiast kontenerem. #<<<<<<<<<<<< @@ -601,21 +595,21 @@ Aby przerobić przykładowy obiekt Message na obiekt Iq, należy zarejestrować # Wszystkie możliwe typy Iq to: get, set, error, result def __handle_get_iq(self, iq): # Zrób coś z otrzymanym iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. + self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołuje zdarzenie, który może być obsłużony przez klienta lub inaczej. def __handle_result_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. + self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołuje zdarzenie, który może być obsłużony przez klienta lub inaczej. def __handle_error_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. + self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołuje zdarzenie, który może być obsłużony przez klienta lub inaczej. def __handle_message(self, msg): - # Zrób coś z otrzymanym message - self.xmpp.event('example_tag_message', msg) ##~ Wywołuje event, który może być obsłużony przez klienta lub inaczej. + # Zrób coś z otrzymaną wiadomością + self.xmpp.event('example_tag_message', msg) ##~ Wywołuje zdarzenie, który może być obsłużony przez klienta lub inaczej. -Eventy wywołane przez powyższe handlery mogą zostać przechwycone tak, jak w przypadku eventu `'example_tag_message'`. +Wydarzenia wywołane przez powyższe uchwyty mogą zostać przechwycone tak, jak w przypadku wydarzenia `'example_tag_message'`. .. code-block:: python @@ -883,7 +877,7 @@ Jeśli Responder zwróci wysłane Iq, a Sender wyłączy się po trzech odpowied Łatwość użycia pluginu dla programistów ---------------------------------------- -Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich eventów. +Każdy plugin powinien posiadać pewne obiektowe metody: wczytanie danych, jak w przypadku metod `setup` z poprzedniego rozdziału, gettery, settery, czy wywoływanie odpowiednich wydarzeń. Potencjalne błędy powinny być przechwytywane z poziomu pluginu i zwracane z odpowiednim opisem błędu w postaci odpowiedzi Iq o tym samym id do wysyłającego. Aby uniknąć sytuacji kiedy plugin nie robi tego co powinien, a wiadomość zwrotna nigdy nie nadchodzi, wysyłający dostaje error z komunikatem timeout. Poniżej przykład kodu podyktowanego tymi zasadami: @@ -915,25 +909,25 @@ Poniżej przykład kodu podyktowanego tymi zasadami: self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'get' oraz example_tag - self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać zdarzenie u klienta. self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'result' oraz example_tag - self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać zdarzenie u klienta. self.xmpp.register_handler( Callback('ExampleGet Event:example_tag', ##~ Nazwa tego Callbacku StanzaPath(f"iq@type=get/{{{namespace}}}example_tag"), ##~ Obsługuje tylko Iq o typie 'error' oraz example_tag - self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. + self.__handle_get_iq)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać zdarzenie u klienta. self.xmpp.register_handler( Callback('ExampleMessage Event:example_tag',##~ Nazwa tego Callbacku StanzaPath(f'message/{{{namespace}}}example_tag'), ##~ Obsługuje tylko Message z example_tag - self.__handle_message)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać event u klienta. + self.__handle_message)) ##~ Metoda przechwytuje odpowiednie Iq, powinna wywołać zdarzenie u klienta. register_stanza_plugin(Iq, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Iq. Bez tego, iq['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. - register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. + register_stanza_plugin(Message, ExampleTag) ##~ Zarejestrowane rozszerzenia tagu dla wiadomości Message. Bez tego, message['example_tag'] będzie polem tekstowym, a nie kontenerem i nie będzie można zmieniać w nim pól i tworzyć pod-elementów. # Wszystkie możliwe typy iq: get, set, error, result def __handle_get_iq(self, iq): @@ -944,19 +938,19 @@ Poniżej przykład kodu podyktowanego tymi zasadami: error["error"]["text"] = "Without some_string value returns error." error.send() # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. + self.xmpp.event('example_tag_get_iq', iq) ##~ Wywołanie zdarzenia, które może być przesłane do klienta lub zmienione po drodze. def __handle_result_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. + self.xmpp.event('example_tag_result_iq', iq) ##~ Wywołanie zdarzenia, które może być przesłany do klienta lub zmienione po drodze. def __handle_error_iq(self, iq): # Zrób coś z otrzymanym Iq - self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. + self.xmpp.event('example_tag_error_iq', iq) ##~ Wywołanie zdarzenia, które może być przesłane do klienta lub zmienione po drodze. def __handle_message(self, msg): - # Zrób coś z otrzymanym Message - self.xmpp.event('example_tag_message', msg) ##~ Wywołanie eventu, który może być przesłany do klienta lub zmieniony po drodze. + # Zrób coś z otrzymaną wiadomością + self.xmpp.event('example_tag_message', msg) ##~ Wywołanie zdarzenia, które może być przesłane do klienta lub zmienione po drodze. class ExampleTag(ElementBase): name = "example_tag" ##~ Nazwa głównego pliku XML tego rozszerzenia. @@ -1042,7 +1036,7 @@ Poniżej przykład kodu podyktowanego tymi zasadami: reply.send() def example_tag_message(self, msg): - logging.info(msg) # Na Message można odpowiedzieć, ale nie trzeba. + logging.info(msg) # Na wiadomość Message można odpowiedzieć, ale nie trzeba. if __name__ == '__main__': @@ -1269,50 +1263,49 @@ W poniższym kodzie zostały pozostawione oryginalne komentarze w języku angiel .. code-block:: python - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal - #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") +#!/usr/bin/python3 +#File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + +import subprocess +import time + +if __name__ == "__main__": + #~ prefix = ["x-terminal-emulator", "-e"] # Separate terminal for every client; can be replaced with other terminal + #~ prefix = ["xterm", "-e"] + prefix = [] + #~ suffix = ["-d"] # Debug + #~ suffix = ["-q"] # Quiet + suffix = [] + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about the executable permission. (`chmod +x ./file.py`) + SENDER_TEST = prefix + [sender_path, "-j", sender_jid, "-p", sender_password, "-t", responder_jid, "--path", example_file] + suffix + RESPON_TEST = prefix + [responder_path, "-j", responder_jid, "-p", responder_password] + suffix + + try: + responder = subprocess.Popen(RESPON_TEST) + sender = subprocess.Popen(SENDER_TEST) + responder.wait() + sender.wait() + except: + try: + responder.terminate() + except NameError: + pass + try: + sender.terminate() + except NameError: + pass + raise .. code-block:: python diff --git a/docs/howto/make_plugin_extension_for_message_and_iq.rst b/docs/howto/make_plugin_extension_for_message_and_iq.rst index 70167592..3a7784b8 100644 --- a/docs/howto/make_plugin_extension_for_message_and_iq.rst +++ b/docs/howto/make_plugin_extension_for_message_and_iq.rst @@ -19,7 +19,6 @@ Ubuntu linux installation steps: * `'argparse'` * `'logging'` * `'subprocess'` -* `'threading'` Check if these libraries and the proper python version are available at your environment. Every one of these, except the slixmpp, is a standard python library. However, it may happen that some of them may not be installed. @@ -30,7 +29,6 @@ Check if these libraries and the proper python version are available at your env python3 -c "import argparse; print(argparse.__version__)" python3 -c "import logging; print(logging.__version__)" python3 -m subprocess - python3 -m threading Example output: @@ -45,7 +43,6 @@ Example output: ~ $ python3 -c "import logging; print(logging.__version__)" 0.5.1.2 ~ $ python3 -m subprocess #Should return nothing - ~ $ python3 -m threading #Should return nothing If some of the libraries throw `'ImportError'` or `'no module named ...'` error, install them with: @@ -75,56 +72,53 @@ As the example, a file `'test_slixmpp'` can be created in `'/usr/bin'` directory /usr/bin $ chmod 711 test_slixmpp -This file should be readable and writable only with superuser permission. This file contains a simple structure for logging credentials: +This file contains a simple structure for logging credentials: .. code-block:: python - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client; can be replaced with other terminal - #~ prefix = "xterm -e" - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Remember about the executable permission. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") - -The `'subprocess.run()'`function is compatible with Python 3.5+. If the backward compatibility is needed, replace it with `'subprocess.call'` method and adjust accordingly. +#!/usr/bin/python3 +#File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + +import subprocess +import time + +if __name__ == "__main__": + #~ prefix = ["x-terminal-emulator", "-e"] # Separate terminal for every client; can be replaced with other terminal + #~ prefix = ["xterm", "-e"] + prefix = [] + #~ suffix = ["-d"] # Debug + #~ suffix = ["-q"] # Quiet + suffix = [] + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about the executable permission. (`chmod +x ./file.py`) + SENDER_TEST = prefix + [sender_path, "-j", sender_jid, "-p", sender_password, "-t", responder_jid, "--path", example_file] + suffix + RESPON_TEST = prefix + [responder_path, "-j", responder_jid, "-p", responder_password] + suffix + + try: + responder = subprocess.Popen(RESPON_TEST) + sender = subprocess.Popen(SENDER_TEST) + responder.wait() + sender.wait() + except: + try: + responder.terminate() + except NameError: + pass + try: + sender.terminate() + except NameError: + pass + raise The launch script should be convenient in use and easy to reconfigure again. The proper preparation of it now, can help saving time in the future. Logging credentials, the project paths (from `'sys.argv[...]'` or `'os.getcwd()'`), set the parameters for the debugging purposes, mock the testing xml file and many more things can be defined inside. Whichever parameters are used, the script testing itself should be fast and effortless. The proper preparation of it now, can help saving time in the future. @@ -307,7 +301,7 @@ If the plugin is not in the same directory as the clients, then the symbolic lin The other solution is to relative import it (with dots '.') to get the proper path. First run and the event handlers ------------------------------------------------ +------------------------------------------------- To check if everything is okay, the `'start'` method can be used(which triggers the `'session_start'` event). Right after the client is ready, the signal will be sent. @@ -1236,7 +1230,7 @@ The following code presents exactly this: pass Tags and strings nested inside the tag --------------------------------------- +--------------------------------------------------------- To create the nested element inside IQ tag, `self.xml` field can be considered as an Element from ET (ElementTree). Therefore adding the nested Elements is appending the Element. @@ -1266,50 +1260,49 @@ Complete code from tutorial .. code-block:: python - #!/usr/bin/python3 - #File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) - - import subprocess - import threading - import time - - def start_shell(shell_string): - subprocess.run(shell_string, shell=True, universal_newlines=True) - - if __name__ == "__main__": - #~ prefix = "x-terminal-emulator -e" # Separate terminal for every client, you can replace xterm with your terminal - #~ prefix = "xterm -e" # Separate terminal for every client, you can replace xterm with your terminal - prefix = "" - #~ postfix = " -d" # Debug - #~ postfix = " -q" # Quiet - postfix = "" - - sender_path = "./example/sender.py" - sender_jid = "SENDER_JID" - sender_password = "SENDER_PASSWORD" - - example_file = "./test_example_tag.xml" - - responder_path = "./example/responder.py" - responder_jid = "RESPONDER_JID" - responder_password = "RESPONDER_PASSWORD" - - # Remember about rights to run your python files. (`chmod +x ./file.py`) - SENDER_TEST = f"{prefix} {sender_path} -j {sender_jid} -p {sender_password}" + \ - " -t {responder_jid} --path {example_file} {postfix}" - - RESPON_TEST = f"{prefix} {responder_path} -j {responder_jid}" + \ - " -p {responder_password} {postfix}" - - try: - responder = threading.Thread(target=start_shell, args=(RESPON_TEST, )) - sender = threading.Thread(target=start_shell, args=(SENDER_TEST, )) - responder.start() - sender.start() - while True: - time.sleep(0.5) - except: - print ("Error: unable to start thread") +#!/usr/bin/python3 +#File: /usr/bin/test_slixmpp & permissions rwx--x--x (711) + +import subprocess +import time + +if __name__ == "__main__": + #~ prefix = ["x-terminal-emulator", "-e"] # Separate terminal for every client; can be replaced with other terminal + #~ prefix = ["xterm", "-e"] + prefix = [] + #~ suffix = ["-d"] # Debug + #~ suffix = ["-q"] # Quiet + suffix = [] + + sender_path = "./example/sender.py" + sender_jid = "SENDER_JID" + sender_password = "SENDER_PASSWORD" + + example_file = "./test_example_tag.xml" + + responder_path = "./example/responder.py" + responder_jid = "RESPONDER_JID" + responder_password = "RESPONDER_PASSWORD" + + # Remember about the executable permission. (`chmod +x ./file.py`) + SENDER_TEST = prefix + [sender_path, "-j", sender_jid, "-p", sender_password, "-t", responder_jid, "--path", example_file] + suffix + RESPON_TEST = prefix + [responder_path, "-j", responder_jid, "-p", responder_password] + suffix + + try: + responder = subprocess.Popen(RESPON_TEST) + sender = subprocess.Popen(SENDER_TEST) + responder.wait() + sender.wait() + except: + try: + responder.terminate() + except NameError: + pass + try: + sender.terminate() + except NameError: + pass + raise .. code-block:: python -- cgit v1.2.3