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

Ausführen von Python-Skripten in LibreOffice

Je nachdem, was Sie erreichen möchten, können Sie einen der folgenden Ansätze zum Ausführen von Python-Skripten in LibreOffice wählen:

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

Wenn Sie Skripte innerhalb des LibreOffice-Prozesses ausführen möchten, wird empfohlen, die APSO-Erweiterung (Alternative Script Organizer for Python) zu installieren. Um jedoch Python-Skripte außerhalb von LibreOffice zu entwickeln, können Sie Ihre bevorzugte Python-IDE verwenden.

Ausführen von Skripten innerhalb des LibreOffice-Prozesses

Verwenden der APSO-Erweiterung

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

Wählen Sie im Hauptfenster der APSO Menü – Python-Shell…

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

Jetzt können Sie anfangen, Python-Befehle einzugeben, und die Shell gibt die entsprechende Ausgabe aus, nachdem jede Codezeile ausgeführt wurde.

Um die Bibliothek ScriptForge zu verwenden, müssen Sie die Methode CreateScriptService importieren, mit der Sie auf die von der Bibliothek bereitgestellten Dienste zugreifen können. 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, geben Sie jede Zeile nacheinander in die Python-Shell ein und drücken [Eingabetaste], nachdem Sie jede Codezeile eingegeben haben.

Jetzt können Sie mit der Ausführung von Python-Befehlen über einen der Dienste von ScriptForge beginnen. Der folgende Code-Schnipsel verwendet beispielsweise den Dienst UI, um ein leeres Writer-Dokument zu erstellen.


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

Erstellen von Python-Skriptdateien

Sie können Ihre eigenen Python-Dateien erstellen und sie mit Ihrem bevorzugten Texteditor bearbeiten. Später können Sie diese von jeder LibreOffice-Komponente aus aufrufen.

Der erste Schritt besteht darin, herauszufinden, wo Ihre Benutzerskripte gespeichert sind. Lesen Sie dazu die Hilfeseite Verwaltung und Speicherort von Python-Skripten.

Jetzt können Sie eine Textdatei in Ihrem Python-Benutzerskriptordner erstellen, beispielsweise sf_test.py, und mit der Eingabe Ihrer Skripte beginnen.

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


    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 Sie, dass g_exportedScripts ein Tupel ist, das angibt, welche Funktionen in LibreOffice als Benutzerskripte angezeigt werden.

So führen Sie dieses Skript in einem Calc-Dokument aus:

Erstellen oder öffnen Sie eine Calc-Datei.
Geben Sie einen numerischen Wert in die Zelle "A1" in der aktuellen Tabelle ein.
Wählen Sie Extras – Makros – Makros ausführen…
Wählen Sie »Meine Makros – sf_test« in der Auswahl „Bibliothek“. Wählen Sie dann die Funktion increment_cell aus der Liste Makroname.
Klicken Sie auf Ausführen. Sehen Sie nach, dass der Wert in Zelle "A1" um 1 erhöht wurde.

Sie können die APSO auch verwenden, um Python-Skripte auf ähnliche Weise auszuführen:

Öffnen Sie zuerst die APSO, indem Sie Extras – Makros – Python-Skripte verwalten wählen.
Navigieren Sie in der Makroliste zu Meine Makros – sf_test – increment_cell.
Klicken Sie auf Ausführen.

Ausführen von Skripten getrennt vom LibreOffice-Prozess

Bestimmen des Installationspfads

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, Ihren Installationspfad zu identifizieren. Öffnen Sie dazu die Python-Shell von APSO und geben Sie Folgendes ein:


    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 müssen Sie den Unterordner "program" zum resultierenden Pfad hinzufügen. Dies ist der Basisordner, von dem aus Sie Python-Skripte in einem separaten Prozess ausführen.

Angenommen, Sie erhalten /usr/lib/libreoffice/ als Ergebnis der Ausführung des obigen Python-Codes. Dann müssen Sie /usr/lib/libreoffice/program als Pfad zum Ausführen Ihrer Python-Skripte verwenden.

Starten Sie LibreOffice mit den Socket-Einstellungen

Um Python-Skripte von einem separaten Prozess auszuführen, müssen Sie LibreOffice mit einigen zusätzlichen Optionen starten, die den Hostnamen und den Port festlegen, über die der externe Prozess mit dem LibreOffice-Komponentenprozess kommuniziert.

Öffnen Sie die Eingabeaufforderung Ihres Betriebssystems, navigieren Sie zum Programmordner Ihres LibreOffice-Installationsverzeichnisses und geben Sie Folgendes ein:

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

Der obige Befehl startet LibreOffice mit einem offenen Kommunikationskanal, sodass andere Prozesse Nachrichten damit austauschen können.

Beachten Sie, dass das vorherige Beispiel das LibreOffice-Startcenter öffnet. Wenn Sie eine bestimmte Komponente öffnen möchten, beispielsweise Writer, können Sie dem Befehl die Ergänzung --writer wie folgt hinzufügen.

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

Beachten Sie die Parameter host und port, die in diesem Beispiel jeweils localhost und 2021 sind.

Ausführen einer externen Python-Shell

Starten Sie die Python-Shell aus dem Ordner program in Ihrem LibreOffice-Installationspfad. Befolgen Sie die Schritte oben, um zu erfahren, wie Sie Ihren Installationspfad finden.

Unter Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

Unter Windows:

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

$ python.exe

Dies öffnet die Python-Shell und Sie können anschließend mit der Eingabe von Befehlen beginnen, die von LibreOffice ausgeführt werden. Aber zuerst müssen Sie die Socket-Verbindung einrichten.


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

Lesen Sie den Abschnitt Einstellen von PYTHONPATH unten, falls beim Importieren von scriptforge.py oder uno.py Fehler auftreten.

Die zweite Codezeile oben definiert die Einstellungen host und port, sodass die Python-Shell mit einem laufenden LibreOffice-Prozess kommunizieren kann, der mit denselben Socket-Einstellungen geöffnet wird.

Jetzt können Sie andere Python-Befehle ausführen und diese können mit dem LibreOffice-Prozess kommunizieren. Zum Beispiel:


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

PYTHONPATH festlegen

Abhängig von der Konfiguration Ihres Betriebssystems müssen Sie die Umgebungsvariable PYTHONPATH festlegen, um die Bibliothek scriptforge.py zu importieren, was wiederum den Import der Bibliothek uno.py erfordert.

Verwenden Sie die Dateisuchfunktion Ihres Betriebssystems, um das Verzeichnis zu ermitteln, in dem sich diese beiden Dateien befinden.

Bei einer standardmäßigen Ubuntu-Installation könnten sich beide Dateien beispielsweise unter folgender Adresse befinden:

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

Setzen Sie in diesem Fall die Umgebungsvariable PYTHONPATH wie folgt, bevor Sie den Python-Interpreter starten:

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

Der Speicherort dieser Dateien ist je nach Betriebssystem und LibreOffice-Installationsmethode unterschiedlich.

Die Bibliothek ScriptForge

LibreOffice Python-Skripte Hilfe

LibreOffice mit Parametern starten