Tworzenie skryptów w języku Python za pomocą ScriptForge

Różnice między językiem Basic a językiem Python

Biblioteka ScriptForge jest dostępna zarówno dla języka Basic, jak i Pythona. Większość usług, metod i właściwości działa identycznie w obu językach programowania. Jednak ze względu na różnice w działaniu każdego języka, użytkownicy ScriptForge muszą zdawać sobie sprawę z pewnych cech biblioteki podczas korzystania z Pythona:

Nazwy metod i właściwości: w Pythonie wszystkie metody i właściwości mogą być używane w formacie pisanym małymi literami, ProperCased lub camelCased.
Argumenty: wszystkie argumenty słów kluczowych przekazywane do metod są pisane małymi literami.
Daty: wszystkie obiekty daty są przekazywane i zwracane jako datetime.datetime natywne obiekty Pythona.
Tablice: jednowymiarowe tablice są przekazywane i zwracane jako krotki (co jest obiektem niezmiennym). Tablice dwuwymiarowe są przekazywane i zwracane jako krotki krotek.
Brak: słowo kluczowe None w Pythonie jest odpowiednikiem słów Null, Empty lub Nothing w języku Basic.
Obiekty UNO: wszystkie struktury UNO są wymieniane pomiędzy językiem Basic i Pythonem bez żadnych zmian.
Debugowanie: za każdym razem, gdy w skryptach Pythona korzystających z ScriptForge wystąpi błąd, komunikat o błędzie dostarczony przez stos wykonawczy Pythona wyświetla linię kodu, która spowodowała błąd. W komunikatach o błędach Basic nie są wyświetlane te informacje.

Odwiedź Pomoc dotyczącą skryptów Pythona Collabora Office, aby uzyskać więcej informacji na temat skryptów Pythona przy użyciu Collabora Office.

Uruchamianie skryptów Pythona w Collabora Office

W zależności od tego, co zamierzasz osiągnąć, możesz wybrać jedno z poniższych podejść do uruchamiania skryptów Pythona w Collabora Office:

Uruchamiaj skrypty w bieżącym procesie Collabora Office: skrypty w języku Python są wykonywane w procesie Collabora Office przy użyciu menu Narzędzia - Makra - Wykonaj makro lub rozszerzenia APSO w celu wywołania skryptów użytkownika przechowywanych w folderze skryptów Pythona. Możesz także użyć powłoki APSO Python do interaktywnego uruchamiania skryptów Pythona.
Uruchamiaj skrypty niezależnie od procesu Collabora Office: skrypty Pythona są wykonywane przez proces zewnętrzny, który łączy się z trwającym procesem Collabora Office za pomocą gniazda.

Jeśli planujesz uruchamiać skrypty z poziomu procesu Collabora Office, zaleca się zainstalowanie Rozszerzenie APSO (Alternative Script Organizer for Python). Aby jednak tworzyć skrypty w języku Python spoza Collabora Office, możesz wybrać preferowane środowisko IDE języka Python.

Uruchamianie skryptów z poziomu procesu Collabora Office

Korzystanie z rozszerzenia APSO

Najłatwiejszym sposobem rozpoczęcia pracy ze skryptami w języku Python w Collabora Office jest zainstalowanie rozszerzenia APSO. Po zainstalowaniu otwórz dowolny komponent Collabora Office i przejdź do Narzędzia - Makra - Organizuj skrypty Pythona.

W głównym oknie APSO przejdź do Menu - Powłoka Python.

Ewentualnie możesz otworzyć APSO za pomocą domyślnego skrótu Alt + Shift + F11.

Teraz możesz zacząć wpisywać polecenia Pythona, a powłoka wyświetli odpowiednie dane wyjściowe po wykonaniu każdego wiersza kodu.

Aby rozpocząć korzystanie z biblioteki ScriptForge należy zaimportować metodę CreateScriptService, dzięki której będziesz mieć dostęp do usług udostępnianych przez bibliotekę. Poniższy przykład wykorzystuje usługę Basic do wyświetlenia okna komunikatu.


    from scriptforge import CreateScriptService
    bas = CreateScriptService("Basic")
    bas.MsgBox("Hello!")

Aby uruchomić powyższy przykład, wprowadź każdy wiersz w powłoce Pythona, jeden po drugim, naciskając klawisz Enter po wpisaniu każdego wiersza kodu.

Teraz możesz rozpocząć wykonywanie poleceń Pythona, korzystając z dowolnej usługi ScriptForge. Na przykład poniższy fragment kodu wykorzystuje usługę UI do utworzenia pustego dokumentu programu Writer.


    ui = CreateScriptService("UI")
    doc = ui.CreateDocument("Writer")

Tworzenie plików skryptów w języku Python

Możesz tworzyć własne pliki Pythona i edytować je za pomocą preferowanego edytora tekstu. Później możesz je wywołać z poziomu dowolnego komponentu Collabora Office.

Pierwszym krokiem jest zlokalizowanie miejsca przechowywania skryptów użytkownika. W tym celu zapoznaj się ze stroną pomocy Organizacja i lokalizacja skryptów Pythona.

Teraz możesz utworzyć plik tekstowy w folderze skryptów użytkownika Pythona, na przykład sf_test.py i zacząć pisać swoje skrypty.

Następny jest prosty przykład, który pobiera wartość liczbową z komórki Calc i zwiększa ją o 1. Po prostu wpisz następujący kod do pliku sf_test.py.


    from scriptforge import CreateScriptService
    doc = CreateScriptService("Calc")
    
    def increment_cell(args=None):
        value = doc.GetValue("A1")
        value += 1
        doc.SetValue("A1", value)
    
    g_exportedScripts = (increment_cell, )

W tym przykładzie tworzona jest funkcja increment_cell. Należy pamiętać, że g_exportedScripts to krotka informująca, które funkcje będą wyświetlane w Collabora Office jako skrypty użytkownika.

Aby uruchomić ten skrypt z poziomu dokumentu programu Calc:

Utwórz lub otwórz plik Calc.
Wprowadź wartość liczbową do komórki "A1" w bieżącym arkuszu.
Przejdź do Narzędzia - Makra - Wykonaj makra.
Wybierz Moje makra - sf_test w selektorze bibliotek. Następnie wybierz funkcję increment_cell z listy Nazwa makra.
Kliknij Uruchom. Należy zauważyć, że wartość w komórce "A1" została zwiększona o 1.

Możesz także użyć APSO do uruchamiania skryptów Pythona w podobny sposób:

Najpierw otwórz APSO, przechodząc do Narzędzia - Makra - Organizuj skrypty Pythona.
Na liście makr przejdź do Moje makra - sf_test - increment_cell.
Kliknij Wykonaj.

Uruchamianie skryptów niezależnie od procesu Collabora Office

Określanie ścieżki instalacji

Pierwszym krokiem do uruchomienia skryptów z oddzielnego procesu jest znalezienie folderu, w którym jest zainstalowany Collabora Office. Można to zrobić na kilka sposobów, ale ScriptForge umożliwia szybkie określenie ścieżki instalacji. W tym celu otwórz powłokę Pythona APSO i wpisz:


    from scriptforge import CreateScriptService
    fs = CreateScriptService("FileSystem")
    fs.FileNaming = "SYS"
    inst_dir = fs.InstallFolder
    print(inst_dir)

Dane wyjściowe powyższego kodu to katalog podstawowy, w którym jest zainstalowany Collabora Office. Teraz do powstałej ścieżki dodaj podfolder "program". Jest to folder bazowy, z którego będą uruchamiane skrypty Pythona z osobnego procesu.

Załóżmy na przykład, że w wyniku uruchomienia powyższego kodu Pythona otrzymasz /usr/lib/libreoffice/. Następnie musisz rozważyć /usr/lib/libreoffice/program jako ścieżkę do uruchamiania skryptów Pythona.

Uruchom Collabora Office z ustawieniami gniazd

Aby uruchamiać skrypty Pythona z oddzielnego procesu, należy uruchomić Collabora Office z kilkoma dodatkowymi opcjami, które określają nazwę hosta i port, przez które proces zewnętrzny będzie komunikował się z procesem komponentu Collabora Office.

Otwórz wiersz poleceń systemu operacyjnego, przejdź do folderu programu w katalogu instalacyjnym Collabora Office i wpisz:

./soffice --accept='socket,host=localhost,port=2021;urp;'

Powyższe polecenie uruchomi Collabora Office z otwartym kanałem komunikacyjnym, dzięki czemu inne procesy będą mogły wymieniać z nim komunikaty.

Należy pamiętać, że w poprzednim przykładzie otwiera się centrum startowe Collabora Office. Jeśli chcesz otworzyć określony komponent, na przykład Writer, możesz dodać do polecenia flagę --writer w następujący sposób.

./soffice --writer --accept='socket,host=localhost,port=2021;urp;'

Zwróć uwagę na parametry host i port, które w tym przykładzie to odpowiednio localhost i 2021.

Uruchamianie zewnętrznej powłoki Pythona

Uruchom powłokę Pythona z folderu program znajdującego się w ścieżce instalacji Collabora Office. Postępuj zgodnie z instrukcjami powyżej aby dowiedzieć się, jak znaleźć ścieżkę instalacji.

W systemie Linux / MacOS:

$ cd /usr/lib/libreoffice/program

$ python

W systemie Windows:

$ cd C:\Program Files\LibreOffice\program\

$ python.exe

Spowoduje to otwarcie powłoki Pythona i możliwość wpisywania polecenia, które zostaną wykonane przez Collabora Office. Ale najpierw musisz skonfigurować połączenie z gniazdem.


    from scriptforge import ScriptForge, CreateScriptService
    ScriptForge(hostname='localhost', port=2021)

Przeczytaj sekcję Ustawianie PYTHONPATH poniżej w przypadku błędów podczas importowania pliku scriptforge.py lub uno.py.

Drugi wiersz kodu powyżej definiuje ustawienia host i port, dzięki czemu powłoka Pythona może komunikować się z trwającym procesem Collabora Office otwartym z tymi samymi ustawieniami gniazda.

Teraz możesz uruchamiać inne polecenia Pythona, które będą mogły komunikować się z procesem Collabora Office. Na przykład:


    ui = CreateScriptService("UI")
    bas = CreateScriptService("Basic")
    doc = ui.OpenDocument("~/Documents/myFile.ods")
    bas.MsgBox(doc.DocumentType)

Ustawianie PYTHONPATH

W zależności od konfiguracji systemu operacyjnego będziesz musiał ustawić zmienną środowiskową PYTHONPATH, aby zaimportować bibliotekę scriptforge.py, co z kolei wymaga zaimportowania biblioteki uno.py.

Użyj narzędzia wyszukiwania plików w systemie operacyjnym, aby określić katalog, w którym znajdują się oba te pliki.

Na przykład w domyślnej instalacji Ubuntu oba pliki mogą znajdować się w:

scriptforge.py: znajduje się w /usr/lib/libreoffice/program
uno.py: znajduje się w /usr/lib/python3/dist-packages

W takim przypadku przed uruchomieniem interpretera Pythona ustaw zmienną środowiskową PYTHONPATH w następujący sposób:

export PYTHONPATH=/usr/lib/libreoffice/program:/usr/lib/python3/dist-packages

Lokalizacja tych plików będzie inna dla każdego systemu operacyjnego i metody instalacji Collabora Office.

Biblioteka ScriptForge

Pomoc skryptów Pythona Collabora Office

Uruchamianie oprogramowania Collabora Office z parametrami