Python-scripts met ScriptForge

Verschillen tussen Basic en Python

De bibliotheek ScriptForge is zowel in Basic als in Python beschikbaar. De meeste services, methodes en eigenschappen werken in beide programmeertalen gelijk. Maar, er zijn natuurlijk wel wat verschillen hoe de talen werken. Als u in Python ScriptForge gebruikt, let dan op het volgende:

Namen van methodes en eigenschappen: In Python, kunnen deze namen de opmaken lowercased, ProperCased en camelCased hebben.
Arguments: All keyword arguments passed on to methods are lowercased.
Datums: Alle objecten die een datum zijn worden doorgegeven en ontvangen als datetime.datetime Python-objecten.
Matrixen: Een eendimensionale matrix wordt doorgegeven en ontvangen als een tupel (dat is een object dat niet te wijzigen is). Een tweedimensionale matrix als een tupel van tupels.
None: Het Python sleutelwoord None is gelijkwaardig aan Basic's Null, Empty en Nothing.
UNO-objecten: Alle UNO-structuren zijn tussen Python en Basic uitwisselbaar.
Debuggen: Als er in een Python-script, dat ScriptForge gebruikt, een fout optreedt dan is er op de stack een foutboodschap beschikbaar met de regel in de code waar de fout is opgetreden. In Basic is dit regelnummer niet beschikbaar.

Meer informatie vind u op Hulp bij LibreOffice Python-scripts over het gebruik van Python scripts in LibreOffice.

Python-scripts bewerken in IDE's

Python-typtips - met betrekking tot openbare methoden en eigenschappen van ScriptForge-services - kunnen worden verkregen van IDE's die een dergelijke faciliteit ondersteunen. Visueel, tijdens het bewerken van een gebruikersscript:

Als u met de muis over een objectinstantie, een methode of een eigenschap beweegt, wordt een gedetailleerde beschrijving ervan weergegeven.
Een "." na een objectinstantie geeft een keuzelijst weer met een lijst van alle beschikbare interfaces.
haakjes na een methodenaam starten de code-aanvulling door de argumenten ervan weer te geven.

Bij het bewerken van methoden en eigenschappen met de juiste hoofdletters en kleine letters worden typtips weergegeven.

Uitvoeren van Python-scripts in LibreOffice

Afhankelijk van wat u wilt bereiken, kunt u een van de volgende methoden kiezen om Python-scripts uit te voeren in LibreOffice:

Scripts uitvoeren binnen het huidige LibreOffice-proces: Python-scripts worden uitgevoerd vanuit het LibreOffice-proces door gebruik te maken van het menu Extra - Macro's - Macro uitvoeren of de APSO-extensie om gebruikersscripts aan te roepen die zijn opgeslagen in de map Python-scripts. U kunt ook de APSO Python-shell gebruiken om interactief Python-scripts uit te voeren.
Scripts uitvoeren los van het LibreOffice-proces: Python-scripts worden uitgevoerd vanuit een extern proces dat verbinding maakt met een lopend LibreOffice-proces via een pipe of een socket.

Als u van plan bent scripts uit te voeren vanuit het LibreOffice-proces, is het raadzaam de APSO (Alternative Script Organizer for Python)-extensie te installeren. Om Python-scripts te ontwikkelen vanuit een ander proces dan LibreOffice, kunt u echter uw favoriete Python IDE gebruiken.

Scripts vanuit het LibreOffice-proces uitvoeren

De APSO-extensie gebruiken

De eenvoudigste manier om aan de slag te gaan met Python-scripting in LibreOffice is door de APSO-extensie te installeren. Open na de installatie een willekeurige LibreOffice-component en ga naar Extra - Macro's - Macro's beheren - Python.

Ga, in het hoofdmenu van APSO's naar Menu - Python Shell.

U kunt APSO ook openen met de toetscombinatie Alt+Shift+F11.

Nu kunt u Python-opdrachten typen en de shell zal na elke uitgevoerde regel code de bijbehorende uitvoer afdrukken.

Om de ScriptForge-bibliotheek te gaan gebruiken, moet u de CreateScriptService-methode importeren. Hiermee krijgt u toegang tot de services die de bibliotheek biedt. Het onderstaande voorbeeld gebruikt de BASIC-service om een berichtvenster weer te geven.


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

Om het bovenstaande voorbeeld uit te voeren, typt u elke regel één voor één in de Python-shell en drukt u na elke regel op de Enter-toets.

Nu kunt u Python-opdrachten uitvoeren met behulp van alle ScriptForge-services. Het onderstaande codefragment gebruikt bijvoorbeeld de GI-service om een leeg writer-document te maken.


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

Python-scriptbestanden maken

Je kunt je eigen Python-bestanden maken en deze bewerken met je favoriete tekstverwerker. Later kun je ze aanroepen vanuit elk LibreOffice-component.

De eerste stap is het vinden van de locatie waar uw gebruikersscripts zijn opgeslagen. Raadpleeg hiervoor de help-pagina Python Scripts Organization and Location.

Nu kunt u een tekstbestand aanmaken in uw Python-gebruikersscriptsmap, bijvoorbeeld my_script.py, en beginnen met het typen van uw scripts.

Hieronder volgt een eenvoudig voorbeeld dat de numerieke waarde uit een Calc-cel haalt en deze met 1 verhoogt. Typ hiervoor de volgende code in het bestand my_script.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, )

Dit voorbeeld maakt de functie increment_cell aan. Merk op datg_exportedScripts een tupel is die aangeeft welke functies in LibreOffice als gebruikersscripts worden weergegeven.

Om dit script vanuit een Calc-document uit te voeren:

Een Calc-bestand maken of openen.
Voer een numerieke waarde in cel "A1" in het huidige werkblad in.
Ga naar Extra - Macro's - Macro uitvoeren.
Kies Mijn macro's - my_script in de bibliotheekkiezer. Kies vervolgens de functie increment_cell onder de lijst MacroNaam.
Klik op Uitvoeren. Merk op dat de waarde in cel "A1" met 1 is verhoogd.

U kunt APSO ook gebruiken om Python-scripts op een vergelijkbare manier uit te voeren:

Open APSO eerst door naar Extra - Macro's - Macro's beheren - Python te gaan.
Ga in de macrolijst naar Mijn macro's - my_script - increment_cell.
Klik op Uitvoeren.

Scripts los van het LibreOffice-proces uitvoeren

Het installatiepad bepalen

De eerste stap om scripts vanuit een apart proces uit te voeren, is het vinden van de map waarin LibreOffice is geïnstalleerd. Er zijn verschillende manieren om dat te doen, maar ScriptForge biedt een snelle manier om uw installatiepad te achterhalen. Open hiervoor de Python-shell van APSO en typ:


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

De uitvoer van de bovenstaande code is de basismap waar LibreOffice is geïnstalleerd. Nu moet u de submap "program" toevoegen aan het resulterende pad. Dit is de basismap van waaruit u Python-scripts in een apart proces uitvoert.

Stel bijvoorbeeld dat u /usr/lib/libreoffice/ als resultaat krijgt na het uitvoeren van de bovenstaande Python-code. Dan moet u /usr/lib/libreoffice/program beschouwen als het pad waarnaar uw Python-scripts moeten worden uitgevoerd.

Start LibreOffice met pipe of socket-instellingen

Om Python-scripts vanuit een apart proces uit te voeren, moet u LibreOffice starten met een paar extra opties die de pipenaam of de hostnaam en poort specificeren waarmee het externe proces met het LibreOffice-componentproces zal communiceren.

Open de opdrachtprompt van uw besturingssysteem, navigeer naar de programmamap van uw LibreOffice-installatiemap en typ een van de volgende opties:

In Linux / Mac OS:

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

In Windows:

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

als een flatpak:

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

Beide bovenstaande opdrachten starten LibreOffice met een open communicatiekanaal, zodat andere processen er berichten mee kunnen uitwisselen.

Merk op dat het vorige voorbeeld het startcentrum LibreOffice opent. Als u een specifiek onderdeel wilt openen, bijvoorbeeld Writer, kunt u de vlag --writer aan de opdracht toevoegen, zoals hieronder.

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

Let op de parameters name, of host en port, die in dit voorbeeld respectievelijk aPipeName, of localhost en 2021 zijn.

Een externe Python-shell uitvoeren

Start de Python-shell vanuit de map program in het installatiepad van LibreOffice. Volg de stappen hierboven om te leren hoe u uw installatiepad kunt vinden.

In Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

In Windows:

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

$ python.exe

Hiermee wordt de Python-shell geopend en kunt u nu commando's typen die door LibreOffice worden uitgevoerd. Maar eerst moet u de pipe- of socket-verbinding instellen. De onderstaande instructie ScriptForge() moet voorafgaan aan de allereerste aanroep van CreateScriptService().

Eén van de volgende opties uitvoeren:


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


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

Lees het gedeelte PYTHONPATH instellen hieronder in geval van fouten bij het importeren van scriptforge.py of uno.py.

De tweede regel code hierboven definieert de pipe of host en port-instellingen, zodat de Python-shell kan communiceren met een actief LibreOffice-proces dat is geopend met dezelfde pipe- of socket-instellingen.

Nu kunt u andere Python-opdrachten uitvoeren en deze kunnen communiceren met het LibreOffice-proces. Bijvoorbeeld:


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

Instelling PYTHONPATH

Afhankelijk van de configuratie van uw besturingssysteem moet u de omgevingsvariabele PYTHONPATH instellen om de bibliotheek scriptforge.py te importeren, waarvoor op zijn beurt de bibliotheek uno.py moet worden geïmporteerd.

Gebruik de bestandszoekfunctie van uw besturingssysteem om de map te vinden waar beide bestanden zich bevinden.

Bijvoorbeeld, bij een standaard Ubuntu-installatie kunnen beide bestanden zich bevinden op:

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

Stel in dit geval de omgevingsvariabele PYTHONPATH als volgt in voordat u de Python-interpreter start:

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

De locatie van deze bestanden verschilt per besturingssysteem en installatiemethode van LibreOffice.

De ScriptForge bibliotheek

Hulp bij LibreOffice Python-scripts

LibreOffice-software starten met parameters