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 LibreOffice, aby uzyskać więcej informacji na temat skryptów Pythona przy użyciu LibreOffice.

Edycja skryptów języka Python w środowiskach IDE

Wskazówki dotyczące pisania w języku Python — odnoszące się do publicznych metod i właściwości usług ScriptForge — można uzyskać z IDE obsługujących takie udogodnienia. Wizualnie, podczas edycji skryptu użytkownika:

• najechanie kursorem na instancję obiektu, metodę lub właściwość powoduje wyświetlenie jej szczegółowego opisu.

• znak „.” po instancji obiektu wyświetla rozwijane pole zawierające listę wszystkich dostępnych interfejsów.

• nawiasy kwadratowe po nazwie metody rozpoczynają dopełnianie kodu poprzez wyświetlenie jej argumentów.

Podpowiedzi dotyczące pisania są wyświetlane podczas edycji metod i właściwości z użyciem liter pisanych właściwą wielkością.

Uruchamianie skryptów Pythona w LibreOffice

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

• Uruchamiaj skrypty w bieżącym procesie LibreOffice: skrypty w języku Python są wykonywane w procesie LibreOffice 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 LibreOffice: skrypty Pythona są wykonywane przez proces zewnętrzny, który łączy się z trwającym procesem LibreOffice za pomocą gniazda.

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

Uruchamianie skryptów z poziomu procesu LibreOffice

Korzystanie z rozszerzenia APSO

Najłatwiejszym sposobem rozpoczęcia pracy ze skryptami w języku Python w LibreOffice jest zainstalowanie rozszerzenia APSO. Po zainstalowaniu otwórz dowolny komponent LibreOffice 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 LibreOffice.

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 LibreOffice jako skrypty użytkownika.

Aby uruchomić ten skrypt z poziomu dokumentu programu Calc:

1. Utwórz lub otwórz plik Calc.

2. Wprowadź wartość liczbową do komórki "A1" w bieżącym arkuszu.

3. Przejdź do Narzędzia - Makra - Wykonaj makra.

4. Wybierz Moje makra - sf_test w selektorze bibliotek. Następnie wybierz funkcję increment_cell z listy Nazwa makra.

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

1. Najpierw otwórz APSO, przechodząc do Narzędzia - Makra - Organizuj skrypty Pythona.

2. Na liście makr przejdź do Moje makra - sf_test - increment_cell.

3. Kliknij Wykonaj.

Uruchamianie skryptów niezależnie od procesu LibreOffice

Określanie ścieżki instalacji

Pierwszym krokiem do uruchomienia skryptów z oddzielnego procesu jest znalezienie folderu, w którym jest zainstalowany LibreOffice. 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 LibreOffice. 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 LibreOffice z ustawieniami gniazd

Aby uruchamiać skrypty Pythona z oddzielnego procesu, należy uruchomić LibreOffice 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 LibreOffice.

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

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

Powyższe polecenie uruchomi LibreOffice 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 LibreOffice. 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 LibreOffice. 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 LibreOffice. 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 LibreOffice otwartym z tymi samymi ustawieniami gniazda.

Teraz możesz uruchamiać inne polecenia Pythona, które będą mogły komunikować się z procesem LibreOffice. 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 LibreOffice.