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.

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 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.
Run Scripts separately from the LibreOffice process: Python scripts are executed from an external process that connects to an ongoing LibreOffice process using a pipe or a socket.

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.

Dieses Skript in einem Calc-Dokument ausfü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 – 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.

Start LibreOffice with pipe or socket settings

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.

Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type either:

./soffice --accept='pipe,name=libreoffice;urp;'

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

Either command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

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

Take note of the name, or host and port parameters, which in this example are libreoffice, or localhost and 2021, respectively.

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

This will open the Python shell and now you can start typing commands that will be executed by LibreOffice. But first you need to set up the pipe or the socket connection. The ScriptForge() statement below must precede the very first call to CreateScriptService().

Run either:


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


    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.

The second line of code above defines the pipe or host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same pipe or socket settings.

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