Erstellen von Python-Skripten mit ScriptForge

Unterschiede zwischen Basic und Python

Die Bibliothek ScriptForge ist sowohl für Basic als auch für Python verfügbar. Die meisten Dienste, Methoden und Eigenschaften funktionieren in beiden Programmiersprachen identisch. Aufgrund der Unterschiede in der Funktionsweise der einzelnen Sprachen müssen Benutzer von ScriptForge jedoch einige Eigenschaften der Bibliothek beachten, wenn sie Python verwenden:

Methoden- und Eigenschaftsnamen: In Python können alle Methoden und Eigenschaften in Kleinbuchstaben, mit Kapitälchen oder BinnenVersal verwendet werden.
Arguments: Alle an Methoden übergebenen Schlüsselwortargumente werden in Kleinbuchstaben geschrieben.
Daten: Alle Datumsobjekte werden als native Python-Objekte datetime.datetime übergeben und zurückgegeben.
Matrizen: Eindimensionale Matrizen werden als Tupel übergeben und zurückgegeben (was ein unveränderliches Objekt ist). Zweidimensionale Matrizen werden als Tupel von Tupeln übergeben und zurückgegeben.
None: Das Schlüsselwort None von Python entspricht Null, Empty oder Nothing von Basic.
UNO-Objekte: Alle UNO-Strukturen werden unverändert zwischen Basic und Python ausgetauscht.
Debugging: Immer wenn ein Fehler in Python-Skripten auftritt, die ScriptForge verwenden, zeigt die vom Python-Ausführungsstapel bereitgestellte Fehlermeldung die Codezeile an, die den Fehler ausgelöst hat. In Basic-Fehlermeldungen werden diese Informationen nicht angezeigt.

Weitere Informationen zur Python-Skripterstellung mit LibreOffice finden Sie in der Hilfe zu LibreOffice Python-Skripte.

Bearbeiten von Python-Skripten in IDEs

Python-Tipphinweise – in Bezug auf öffentliche Methoden und Eigenschaften von Diensten ScriptForge – können von IDEs bezogen werden, die diese Funktion unterstützen. Visuell, während Sie ein Benutzerskript bearbeiten:

Wenn Sie mit der Maus über eine Objektinstanz, eine Methode oder eine Eigenschaft fahren, wird deren detaillierte Beschreibung angezeigt.
Ein "." nach einer Objektinstanz zeigt eine Dropdown-Box mit allen verfügbaren Schnittstellen an.
Klammern nach einem Methodennamen starten die Codevervollständigung durch Anzeige seiner Argumente.

Beim Bearbeiten von Methoden und Eigenschaften mit Groß- und Kleinbuchstaben werden Tipphinweise angezeigt.

Ausführen von Python-Skripten in LibreOffice

Je nachdem, was erreicht werden soll, kann einer der folgenden Ansätze für die Ausführung von Python-Skripten in LibreOffice gewählt werden:

Skripte innerhalb des aktuellen LibreOffice-Prozesses ausführen: Um Python-Skripte innerhalb des LibreOffice-Prozesses auszuführen, Extras – Makros – Makro ausführen… wählen oder die APSO-Erweiterung verwenden, um Benutzerskripte aufzurufen, die im Ordner für Python-Skripte gespeichert sind. Die APSO-Python-Shell kann auch verwendet werden, um Python-Skripte interaktiv auszuführen.
Skripte getrennt vom LibreOffice-Prozess ausführen: Python-Skripte werden von einem externen Prozess ausgeführt, der über eine Pipe oder einen Socket eine Verbindung zu einem laufenden LibreOffice-Prozess herstellt.

Um Skripte innerhalb des LibreOffice-Prozesses auszuführen, wird empfohlen, die APSO-Erweiterung (Alternative Script Organizer for Python) zu installieren. Um jedoch Python-Skripte außerhalb von LibreOffice zu entwickeln, kann die bevorzugte Python-IDE verwendet werden.

Skripte innerhalb des LibreOffice-Prozesses ausführen

Verwenden der APSO-Erweiterung

Der einfachste Einstieg in die Python-Skripterstellung in LibreOffice ist die Installation der APSO-Erweiterung. Nach der Installation eine beliebige LibreOffice-Komponente öffnen und Extras – Makros – Python-Skripte verwalten… wählen.

Im Hauptfenster der APSO Menü – Python-Shell… wählen.

Alternativ APSO mit dem Standard-Tastaturkürzel [Umschalt+Alt+F11] öffnen.

Jetzt kann mit der Eingabe von Python-Befehlen begonnen werden und die Shell gibt die entsprechende Ausgabe nach der Ausführung jeder Codezeile aus.

Um die Bibliothek ScriptForge zu verwenden, muss die Methode CreateScriptService importiert werden, mit der auf die von der Bibliothek bereitgestellten Dienste zugegriffen werden kann. Das folgende Beispiel verwendet den Dienst Basic, um ein Meldungsfeld anzuzeigen.


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

Um das obige Beispiel auszuführen, die einzelnen Zeilen nacheinander in die Python-Shell eingeben und nach jeder Codezeile [Eingabetaste] drücken.

Nun kann mit der Ausführung von Python-Befehlen unter Verwendung der Dienste von ScriptForge begonnen werden. Das folgende Code-Beispiel verwendet beispielsweise den Dienst UI, um ein leeres Writer-Dokument zu erstellen.


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

Python-Skriptdateien erstellen

Eigenen Python-Dateien können erstellt und mit dem bevorzugten Texteditor bearbeitet werden. Später können diese aus jeder beliebigen LibreOffice-Komponente heraus aufgerufen werden.

Der erste Schritt besteht darin, den Speicherort der Benutzerskripte zu ermitteln. Für Informationen dazu sei auf der Hilfeseite Verwaltung und Speicherort von Python-Skripten verwiesen.

Jetzt kann im Ordner für Python-Benutzerskripte eine Textdatei erstellt, beispielsweise Mein_Skript.py, und mit dem Schreiben der Skripte begonnen werden.

Als nächstes folgt ein einfaches Beispiel, das den numerischen Wert aus einer Calc-Zelle abruft und um 1 erhöht. Dazu einfach den folgenden Code in die Datei Mein_Skript.py schreiben.


    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, )

Dieses Beispiel erstellt die Funktion increment_cell. Beachten, dass g_exportedScripts ein Tupel ist, das angibt, welche Funktionen in LibreOffice als Benutzerskripte angezeigt werden.

Um dieses Skript aus einem Calc-Dokument heraus auszuführen:

Eine Calc-Datei erstellen oder öffnen.
Einen numerischen Wert in die Zelle "A1" in der aktuellen Tabelle eingeben.
Extras – Makros – Makros ausführen… wählen.
Meine Makros – Mein_Skript in der Auswahl „Bibliothek“ wählen. Dann die Funktion increment_cell aus der Liste Makroname wählen.
Ausführen anklicken. Nachsehen, dass der Wert in Zelle "A1" um 1 erhöht wurde.

Auch die APSO kann verwendet werden, um Python-Skripte auf ähnliche Weise auszuführen:

Zuerst die APSO öffnen, hierzu Extras – Makros – Python-Skripte verwalten wählen.
In der Makroliste zu Meine Makros – Mein_Skript – increment_cell navigieren.
Ausführen anklicken.

Skripte getrennt vom LibreOffice-Prozess ausführen

Den Installationspfad bestimmen

Der erste Schritt zum Ausführen von Skripten aus einem separaten Prozess besteht darin, den Ordner zu finden, in dem LibreOffice installiert ist. Dafür gibt es mehrere Möglichkeiten, aber ScriptForge bietet eine schnelle Möglichkeit, den Installationspfad zu identifizieren. Dazu die Python-Shell von APSO öffnen und Folgendes eingeben:


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

Die Ausgabe des obigen Codes ist das Basisverzeichnis, in dem LibreOffice installiert ist. Jetzt muss der Unterordner "program" zum resultierenden Pfad hinzugefügt werden. Dies ist der Basisordner, von dem aus Python-Skripte in einem separaten Prozess ausgeführt werden.

Angenommen, /usr/lib/libreoffice/ wird als Ergebnis der Ausführung des obigen Python-Codes zurückgegeben. Dann muss /usr/lib/libreoffice/program als Pfad zum Ausführen der Python-Skripte verwendet werden.

LibreOffice mit den Einstellungen pipe oder socket starten.

Um Python-Skripte aus einem separaten Prozess heraus auszuführen, muss LibreOffice mit einigen zusätzlichen Optionen gestartet werden. Diese geben den Pipe-Namen oder den Hostnamen und Port an, über die der externe Prozess mit dem LibreOffice-Komponentenprozess kommuniziert.

Die Eingabeaufforderung des Betriebssystems öffnen, zum Programmordner des LibreOffice-Installationsverzeichnisses navigieren und Folgendes eingeben:

Unter Linux oder macOS:

libreoffice --accept='pipe,name=aPipeName;urp;'

Unter Windows:

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

Als Flatpak:

flatpak run org.libreOffice.LibreOffice accept='socket,host=localhost,port=2021;urp;'

Jeder der oben genannten Befehle startet LibreOffice mit einem offenen Kommunikationskanal, sodass andere Prozesse Nachrichten mit dem Programm austauschen können.

Das vorherige Beispiel öffnet das Startcenter von LibreOffice. Um eine bestimmte Komponente zu öffnen, beispielsweise Writer, dem Befehl den Parameter "--writer" folgendermaßen hinzufügen.

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

Die Parameter name beziehungsweise host und port beachten, die in diesem Beispiel aPipeName beziehungsweise localhost und 2021 lauten.

Eine externe Python-Shell ausführen

Die Python-Shell aus dem Ordner program im LibreOffice-Installationsverzeichnis starten. Die oben beschriebenen Schritte befolgen, um zu erfahren, wie das Installationsverzeichnis gefunden werden kann.

Unter Linux oder macOS:

$ cd /usr/lib/libreoffice/program

$ python

Unter Windows:

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

$ python.exe

Dadurch wird die Python-Shell geöffnet und es können Befehle eingegeben werden, die von LibreOffice ausgeführt werden. Zuerst muss jedoch die Verbindung Pipe oder Socket eingerichtet werden. Die unten stehende Anweisung ScriptForge() muss vor dem ersten Aufruf von CreateScriptService() stehen.

Entweder Folgendes ausführen:


   from scriptforge import ScriptForge, CreateScriptService
   ScriptForge(pipe='aPipeName')


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

Den folgenden Abschnitt PYTHONPATH festlegen lesen, falls beim Importieren von scriptforge.py oder uno.py Fehler auftreten.

Die zweite Codezeile oben definiert die Einstellungen für pipe bzw. host und port, damit die Python-Shell mit einem laufenden LibreOffice-Prozess kommunizieren kann, der mit denselben Pipe- oder Socket-Einstellungen gestartet wurde.

Jetzt können weitere Python-Befehle ausgeführt werden, die mit dem LibreOffice-Prozess kommunizieren können. Zum Beispiel:


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

PYTHONPATH festlegen

Je nach Konfiguration des Betriebssystems muss die Umgebungsvariable PYTHONPATH gesetzt werden, um die Bibliothek scriptforge.py zu importieren, was wiederum den Import der Bibliothek uno.py erfordert.

Die Suchfunktion des Betriebssystems verwenden, um das Verzeichnis zu ermitteln, in dem sich diese beiden Dateien befinden.

Bei einer standardmäßigen Ubuntu-Installation beispielsweise können sich beide Dateien an folgendem Ort befinden:

scriptforge.py: Befindet sich in /usr/lib/libreoffice/program
uno.py: Befindet sich in /usr/lib/python3/dist-packages

In diesem Fall die Umgebungsvariable PYTHONPATH wie folgt setzen, bevor der Python-Interpreter gestartet wird:

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

Der Speicherort dieser Dateien variiert je nach Betriebssystem und Installationsmethode von LibreOffice.

Die Bibliothek ScriptForge

LibreOffice Python-Skripte Hilfe

LibreOffice mit Parametern starten