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 LibreOfficeDev finden Sie in der Hilfe zu LibreOfficeDev 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 LibreOfficeDev

Je nachdem, was Sie erreichen möchten, können Sie einen der folgenden Ansätze für die Ausführung von Python-Skripten in LibreOfficeDev wählen:

Skripte innerhalb des aktuellen LibreOfficeDev-Prozesses ausführen: Um Python-Skripte innerhalb des LibreOfficeDev-Prozesses auszuführen, wählen Sie Extras – Makros – Makro ausführen… oder verwenden die APSO-Erweiterung, um Benutzerskripte 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 LibreOfficeDev-Prozess ausführen: Python-Skripte werden von einem externen Prozess ausgeführt, der über eine Pipe oder einen Socket eine Verbindung zu einem laufenden LibreOfficeDev-Prozess herstellt.

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

Skripte innerhalb des LibreOfficeDev-Prozesses ausführen

Verwenden der APSO-Erweiterung

Der einfachste Einstieg in die Python-Skripterstellung in LibreOfficeDev ist die Installation der APSO-Erweiterung. Öffnen Sie nach der Installation eine beliebige LibreOfficeDev-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 mit der Eingabe von Python-Befehlen beginnen, 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 die einzelnen Zeilen nacheinander in die Python-Shell ein und drücken nach jeder Codezeile die [Eingabetaste].

Sie können nun mit der Ausführung von Python-Befehlen unter Verwendung der Dienste von ScriptForge beginnen. 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

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

Der erste Schritt besteht darin, den Speicherort Ihrer Benutzerskripte zu ermitteln. Informationen dazu finden Sie auf der Hilfeseite Verwaltung und Speicherort von Python-Skripten.

Jetzt können Sie in Ihrem Ordner für Python-Benutzerskripte eine Textdatei erstellen, beispielsweise Mein_Skript.py, und mit dem Schreiben Ihrer Skripte beginnen.

Als nächstes folgt ein einfaches Beispiel, das den numerischen Wert aus einer Calc-Zelle abruft und um 1 erhöht. Schreiben Sie dazu einfach den folgenden Code in die Datei Mein_Skript.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, )

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

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

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 – Mein_Skript 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 auch die APSO 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 – Mein_Skript – increment_cell.
Klicken Sie auf Ausführen.

Skripte getrennt vom LibreOfficeDev-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 LibreOfficeDev 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 LibreOfficeDev 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.

LibreOfficeDev mit den Einstellungen pipe oder socket starten.

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

Die Eingabeaufforderung des Betriebssystems öffnen, zum Programmordner des LibreOfficeDev-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 LibreOfficeDev mit einem offenen Kommunikationskanal, sodass andere Prozesse Nachrichten mit dem Programm austauschen können.

Das vorherige Beispiel öffnet das Startcenter von LibreOfficeDev. 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;'

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

Eine externe Python-Shell ausführen

Starten Sie die Python-Shell aus dem Ordner program in Ihrem LibreOfficeDev-Installationsverzeichnis. Befolgen Sie die oben beschriebenen Schritte, um zu erfahren, wie Sie Ihr Installationsverzeichnis finden.

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

Lesen Sie den folgenden Abschnitt PYTHONPATH festlegen, 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 LibreOfficeDev-Prozess kommunizieren kann, der mit denselben Pipe- oder Socket-Einstellungen gestartet wurde.

Jetzt können Sie weitere Python-Befehle ausführen, die mit dem LibreOfficeDev-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 Ihres Betriebssystems müssen Sie die Umgebungsvariable PYTHONPATH setzen, um die Bibliothek scriptforge.py zu importieren, was wiederum den Import der Bibliothek uno.py erfordert.

Verwenden Sie die Suchfunktion Ihres Betriebssystems, 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

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 variiert je nach Betriebssystem und Installationsmethode von LibreOfficeDev.

Die Bibliothek ScriptForge

LibreOfficeDev Python-Skripte Hilfe

LibreOfficeDev mit Parametern starten