Hoe voer je Python-scripts uit in macro's van LibreOffice Calc?

Ja. LibreOffice Calc kan Python-code uitvoeren als een macro binnen het LibreOffice-proces, en een LibreOffice Basic-macro kan ook een Python-functie aanroepen via het scriptframework van LibreOffice. Als u cellen in het geopende spreadsheet wilt lezen of wijzigen, is een Python-macro binnen het proces meestal het eenvoudigste startpunt. Gebruik een Basic-naar-Python-aanroep wanneer een bestaande Basic-macro een taak moet overdragen aan een herbruikbare Python-functie.

Deze benaderingen verschillen van het starten van een gewoon Python-script via een shell-opdracht. Een normaal extern Python-proces ontvangt niet automatisch het documentobject van Calc. Voor toegang tot een werkmap kunt u een Python-macro uitvoeren via LibreOffice of een extern proces bewust verbinden met een LibreOffice-instantie via UNO.

Wat betekent "Python uitvoeren binnen een Calc-macro"?

LibreOffice ondersteunt meerdere scripttalen via het scriptframework. In een Python-macro levert LibreOffice een UNO-contextobject waarmee het script toegang krijgt tot het huidige document en de bijbehorende werkbladen. Een Python-macro is een functie in een .pymodule; de g_exportedScripts​​tuple van de module identificeert functies die LibreOffice als uitvoerbare macro's moet weergeven.

Een Python-macro kan zelfstandig worden uitgevoerd vanuit het macromenu van Calc. Deze hoeft niet door Basic te worden aangeroepen. Als u al een Basic-macro hebt en deze wilt laten aanroepen door Python, Session.ExecutePythonScriptkunnen de scriptprovider van LibreOffice of de nieuwere ScriptForge-service de twee talen met elkaar verbinden.

Welke aanpak moet je kiezen?

• Gebruik een Python-macro direct wanneer de taak voornamelijk in Python wordt uitgevoerd en het huidige Calc-document nodig heeft. Dit voorkomt overdracht tussen programmeertalen en is het gemakkelijkst te debuggen als één script.
• Roep Python aan vanuit Basic wanneer je al Basic-code, knoppen of documentgebeurtenissen hebt die op hun plaats moeten blijven, en je een Python-helper wilt gebruiken om een ​​specifieke berekening of gegevensbewerking uit te voeren.
• Gebruik een extern Python-proces wanneer u een aparte ontwikkelomgeving nodig hebt of Python-pakketten die niet standaard in LibreOffice zijn opgenomen. Stel een expliciete UNO-verbinding in; ga er niet vanuit dat een script dat vanuit een terminal wordt gestart, de geopende spreadsheet kan zien.

Een klein hulpprogramma voor het opschonen van spreadsheets kan bijvoorbeeld volledig als Python-macro worden geschreven. Als een bestaande Basic-knop al een rapport genereert, behoud dan de macro van de knop en laat deze een Python-functie aanroepen die het totaalbedrag van het rapport berekent.

Hoe maak je een Python-macro waarmee je cellen in Calc kunt bewerken?

LibreOffice slaat persoonlijke Python-scripts op in het gebruikersprofiel, applicatiebrede scripts in de installatiemap en documentscripts bij een document. Voor een eerste test is een persoonlijk script handig, omdat het beschikbaar is vanuit elk geopend LibreOffice-document voor dezelfde gebruiker. Het wordt echter niet meegestuurd met een ODS-bestand, dus een andere gebruiker ontvangt het niet automatisch samen met het spreadsheet.

Zoek de map met persoonlijke Python-scripts voor uw systeem in de Help van LibreOffice onder 'Indeling en locatie van Python-scripts'. Veelvoorkomende locaties zijn onder andere %APPDATA%\LibreOffice\4\user\Scripts\pythonop Windows en ~/.config/libreoffice/4/user/Scripts/pythonop Linux. De daadwerkelijke locatie kan variëren; gebruik de locatie die voor uw installatie is gedocumenteerd in plaats van op goed geluk een tweede profielmap aan te maken.

Maak een bestand aan calc_tools.pyin de map met persoonlijke Python-scripts en voeg dit eenvoudige voorbeeld toe:

def double_a1(args=None):
    doc = XSCRIPTCONTEXT.getDocument()
    sheet = doc.getCurrentController().getActiveSheet()

    source = sheet.getCellRangeByName("A1")
    target = sheet.getCellRangeByName("B1")
    target.setValue(source.getValue() * 2)

g_exportedScripts = (double_a1,)

Deze functie leest de numerieke waarde in cel A1 van het actieve werkblad en schrijft tweemaal die waarde naar B1. XSCRIPTCONTEXTDe functie wordt tijdens de uitvoering aan een LibreOffice Python-macro doorgegeven; het is geen reguliere globale Python-variabele wanneer hetzelfde bestand buiten LibreOffice wordt geopend. De openbare functie is opgenomen in de lijst, g_exportedScriptszodat deze in de macroselector verschijnt.

Sla het bestand op en open vervolgens Calc of ga terug naar Calc en kies Extra > Macro's > Macro's uitvoeren . Afhankelijk van de LibreOffice-versie of platformvertaling kan het menulabel enkelvoudig zijn. Selecteer Mijn macro's > calc_tools > double_a1 en voer deze uit. Voer eerst een getal in A1 in en controleer vervolgens of B1 de verdubbelde waarde bevat. Als de module niet verschijnt, controleer dan of de bestandsextensie .cs is .py, of het bestand zich in de juiste Python-map van het profiel bevindt en of Python-scriptondersteuning is geïnstalleerd. Het opnieuw opstarten van LibreOffice na het toevoegen van een nieuwe module kan helpen om de scriptlijst te vernieuwen.

Hoe kan een Basic-macro een Python-functie aanroepen?

Voor een Basic-naar-Python-aanroep plaatst u een Python-module in de map met persoonlijke scripts en roept u de functie ervan aan via de Sessionservice van ScriptForge. Dit voorbeeld telt twee waarden op in Python en schrijft het resultaat naar cel B1 in het huidige Calc-blad.

Definieer in calc_tools.pyde functie:

def add_values(first, second):
    return float(first) + float(second)

g_exportedScripts = (add_values,)

Maak vervolgens een eenvoudige macro in Calc en gebruik deze:

Sub RunPythonHelper()
    Dim session As Object
    Dim result As Variant
    Dim sheet As Object

    session = CreateScriptService("Session")
    result = session.ExecutePythonScript( _
        session.SCRIPTISPERSONAL, _
        "calc_tools.py$add_values", _
        12, 30)

    sheet = ThisComponent.CurrentController.getActiveSheet()
    sheet.getCellRangeByName("B1").setValue(result)
End Sub

Voer RunPythonHelperde macro uit via de macroselector Basic. Als de aanroep slaagt, moet B1 42 weergeven. De scriptreferentie volgt de vorm <script> module.py$function_name; voor een module in een submap of een andere opslaglocatie, gebruik de syntaxis en locatieconstante die gedocumenteerd zijn voor die ScriptForge-versie. Houd argumenten en retourwaarden bij gegevenstypen die beide talen correct kunnen weergeven, zoals getallen, tekenreeksen en eenvoudige reeksen.

CreateScriptServiceDe gedocumenteerde ScriptForge-sessiehelpers zijn beschikbaar in moderne LibreOffice-versies, maar menunamen en meegeleverde componenten kunnen verschillen in oudere of distributie-gecompileerde versies. Als deze service niet beschikbaar is, gebruik dan de gedocumenteerde UNO-scriptprovider-methode van LibreOffice, die een script ophaalt XScriptvan een script-URI en dit aanroept. Vermijd het kopiëren van een codefragment voor een andere macrolocatie zonder de locatie-instelling te wijzigen.

Moet de Python-code persoonlijk, gedeeld of ingebed zijn?

Voor een teamworkflow is het belangrijk om te bepalen hoe de ontvangers de code ontvangen en erop kunnen vertrouwen, voordat je een werkmap rond een persoonlijke macro bouwt. Als de Python-logica bij het spreadsheet moet worden meegeleverd, test dan de macroopslag en de beveiligingsmeldingen van het document op dezelfde LibreOffice-versies die je ontvangers gebruiken. Voor beheerde implementatie kan een beheerder scripts voor gebruikers verpakken of een extensie distribueren onder de normale softwarebeheerregels van de organisatie.

Waarom zou de macro ontbreken of niet werken?

• De Python-optie of -module ontbreekt. Op sommige GNU/Linux-distributies is het Python-scriptframework van LibreOffice een optioneel pakket. Raadpleeg de installatie-instructies van LibreOffice voor uw distributie als Python-macro's niet in het macrodialoogvenster verschijnen.
• Het script is opgeslagen in het verkeerde profiel. LibreOffice kan meerdere gebruikersprofielen gebruiken. Controleer het profielpad voor de actieve installatie en sla de module op in de bijbehorende Scripts/pythonmap.
• De functie wordt niet geëxporteerd. Voeg deze toe g_exportedScriptsaan een functie die u wilt uitvoeren vanuit de macroselector. Zorg ervoor dat de tuple-syntaxis de afsluitende komma bevat voor een tuple met één item.
• Het script wordt buiten LibreOffice uitgevoerd. XSCRIPTCONTEXT Het is bedoeld voor macro's die door LibreOffice worden gestart, niet wanneer hetzelfde bestand wordt geopend met een systeemopdracht python. Gebruik de macro-runner of configureer een gedocumenteerde UNO-verbinding.
• Macrobeveiliging blokkeert ingesloten code. Controleer de macrobeveiligingsinstellingen van LibreOffice en schakel alleen code in van een bron die u vertrouwt. Het verlagen van het algemene beveiligingsniveau is geen goede snelle oplossing voor problemen.
• Een geïmporteerde module kan de documentcontext niet zien. LibreOffice-documenten XSCRIPTCONTEXTworden niet doorgegeven aan geïmporteerde modules. Geef het benodigde document- of bladobject door aan hulpfuncties in plaats van te verwachten dat geïmporteerde modules deze globale informatie lezen.
• Er is geen zichtbare console-uitvoer. De standaarduitvoer van Python is niet beschikbaar wanneer een macro wordt uitgevoerd vanuit het menu Extra > Macro's. Voor feedback kunt u een resultaat in een cel schrijven, een LibreOffice-dialoogvensterservice gebruiken of loggen naar een opgegeven bestandspad.

Hoe kun je het resultaat op een veilige manier verifiëren?

Test met een kopie van het spreadsheet en een bekende invoer. Controleer of de Python-macro in de runner verschijnt, voer deze eenmaal uit en vergelijk de uitvoercel met een handmatig berekend resultaat. Test bij een Basic-naar-Python-aanroep één eenvoudige invoer en controleer of de geretourneerde waarde naar het beoogde werkblad wordt geschreven. Vermijd scripts die werkbladen verwijderen, grote bereiken overschrijven of besturingssysteemopdrachten uitvoeren.

Als de test succesvol is, bepaal dan hoe het script op andere computers wordt geïnstalleerd en documenteer alle benodigde Python-bibliotheken of LibreOffice-versievereisten. De meegeleverde Python-omgeving van LibreOffice wordt gebruikt voor macro's die binnen hetzelfde proces worden uitgevoerd; pakketten die zijn geïnstalleerd voor een aparte Python-interpreter van het systeem zijn mogelijk niet beschikbaar. Als u pakketten van een andere interpreter nodig hebt, gebruik dan de externe-process/UNO-aanpak en configureer die verbinding bewust.

Officiële referenties

• LibreOffice Help: Python-scripts maken met ScriptForge
• LibreOffice Help: Python-scripts aanroepen vanuit Basic
• LibreOffice Help: Programmeren met Python-scripts
• LibreOffice Help: Python-scripts organiseren en lokaliseren
• LibreOffice Help: Waarden lezen en schrijven naar bereiken
• LibreOffice SDK: XScript-interface