Creating Python Scripts with ScriptForge

Differences between Basic and Python

The ScriptForge library is available both for Basic and Python. Most services, methods and properties work identically in both programming languages. However, due to differences in how each language works, ScriptForge users must be aware of some characteristics of the library when using Python:

Methods and Property names: In Python, all methods and properties can be used in lowercased, ProperCased or camelCased formats.
Arguments: All keyword arguments passed on to methods are lowercased.
Dates: All date objects are passed and returned as datetime.datetime native Python objects.
Arrays: One-dimensional arrays are passed and returned as tuples (which is an immutable object). Two-dimensional arrays are passed and returned as tuples of tuples.
None: Python's None keyword is equivalent to Basic's Null, Empty or Nothing.
UNO objects: All UNO structures are exchanged between Basic and Python without any changes.
Debugging: Whenever an error occurs in Python scripts that use ScriptForge, the error message provided by the Python execution stack displays the line of code that triggered the error. In Basic error messages do not display this information.

Visit LibreOfficeDev Python Scripts Help for more information on Python scripting using LibreOfficeDev.

Editing Python scripts in IDEs

Python typing hints - relating to ScriptForge services public methods and properties - can be obtained from IDEs that support such facility. Visually, while editing a user script:

hovering an object instance, a method or a property displays its detailed description.
a "." after an object instance displays a drop-down box listing all available interfaces.
brackets after a method-name start code-completion by displaying its arguments.

Typing hints are displayed when editing methods and properties with propercase letters.

Running Python scripts on LibreOfficeDev

Wótwisujucy wót togo, co cośo dojśpiś, móžośo jadno ze slědujucych póstupowanjow wubraś, aby skripty Python w LibreOfficeDev wuwjadł.

Skripty w aktualnem procesu LibreOfficeDev wuwjasć: Skripty Python se z procesa LibreOfficeDev wuwjedu,gaž meni Rědy – Makra – Makro wuwjasć… abo rozšyrjenje APSO wužywaśo, aby wužywaŕske skripty wuwołał, kótarež su w zarědniku skriptow Python skłaźone. Móžośo teke shell APSO Python wužywaś, aby skripty Python interaktiwnje wuwjadł.
Skripty separatnje wót procesa LibreOfficeDev wuwjasć: Skripty Python se z eksternego procesa wuwjedu, kótaryž se z běžnym procesom LibreOfficeDev z pomocu pipe abo socket zwězujo.

Jolic cośo skripty w procesu LibreOfficeDev wuwjasć, pórucujo se, rozšyrjenje APSO (Alternative Script Organizer for Python) instalěrowaś. Ale, aby skripty Python zwenka LibreOfficeDev wuwijał, móžośo swóju preferěrowanu IDE wubraś.

Skripty w procesu LibreOfficeDev wuwjasć

Rozšyrjenje APSO wužywaś

Nejlažčejša móžnosć, aby z napóranim skriptow w LibreOfficeDev zachopił, jo instalěrowanje rozšyrjenja APSO. Wócyńśo pó instalaciji komponentu LibreOfficeDev a źiśo k Rědy – Makra – Skripty zastojaś – Python… (rozšyrjenje APSO njejo pśełožone do serbskeju rěcowu, togodla se engelski znamjenjowy rjeśazk pokazujo)

Źiśo w głownem woknje APSO k Menu – Python shell

Abo wócynjaśo APSO z pomocu standardneje tastoweje skrotconki Alt + ⇧ + F11.

Něnto móžośo zachopiś pśikaze Python zapódawaś a shell wótpowědne wudaśe wudawa, za tym až jo se kužda kodowa smužka wuwjadła.

Aby biblioteku ScriptForge wužywał, musyśo metodu CreateScriptService importěrowaś, z kótarejuž móžośo pśistup k słužbam dostaś, kótarež biblioteka k dispoziciji staja. Slědujucy pśikład słužbu Basic wužywa, aby pólo powěźeńki pokazał.


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

Aby pśikład górjejce wuwjadł, zapódajśo kuždu smužku jadnu pó drugej do pówjercha Python a tłocćo tastu Enter, za tym až sćo kuždu kodowu smužku zapódał.

Něnto móžośo zachopiś, pśikaze Python z pomocu słužbow ScriptForge wuwjasć. Slědujuca kodowy kusk na pśikład słužbu UI wužywa, aby prozny dokument Writer napórał.


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

Skriptowe dataje Python napóraś

Móžośo swójske dataje Python napóraś a je ze swójim preferěrowanym tekstowym editorom wobźěłaś. Pózdźej móžośo je w komponenśe LibreOfficeDev wuwołaś.

Prědny kšac jo wuslěźiś, źož su se waše wužywaŕske skripty składli. Lej za to bok pomocy Organizacija a městno skriptow Python.

Něnto móžośo tekstowu dataju w zarědniku swójich wužywaŕskich skriptow Python napóraś, na pśikład mój_skript.py a zachopśo swóje skripty pisaś.

Pśiducy jo jadnory pśikład, kótaryž se numerisku gódnotu z cele Calc wobstarujo a ju wó 1 pówušujo. Zapódajśo jadnorje slědujucy kod do dataje mój_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, )

Toś ten pśikład funkciju increment_cell napórajo. Źiwajśo na to, až g_exportedScript jo tupel, kótaryž k wěsći da, kótare funkcije se w LibreOfficeDev ako wužywaŕske skripty pokazuju.

Aby toś ten skript z dokumenta Calc wuwjadł:

Napórajśo abo wócyńśo dataju Calc.
Zapódajśo někaku numerisku gódnotu do cele "A1" w aktualnej tabeli.
Źiśo k Rědy – Makra – Makra wuwjasć….
Wubjeŕśo Móje makra – mój_skript w selektorje biblioteki. Wubjeŕśo funkciju increment_cell pód lisćinu Mě makra.
Klikniśo na Wuwjasć. Źiwajśo na to, až jo se gódnota w celi "A1" wó 1 pówušyła.

Móžośo teke APSO wužywaś, aby skripty Python na pódobnu wašnju wuwjadł:

Źiśo nejpjerwjej k Rědy – Makra – Makra zastojaś – Python…, aby APSO wócynił.
Nawigěrujśo w lisćinje makrow do Móje makra – mój_skript – increment_cell.
Klikniśo na Execute.

Skripty separatnje wót procesa LibreOfficeDev wuwjasć

Instalacisku sćažku póstajiś

Prědny kšac, aby se skripty ze separatnego procesa wuwjadli, jo, zarědnik namakaś, źož LibreOfficeDev jo instalěrowany. Daju někotare móžnosći, aby wy to cynił, ale ScriptForge malsnu móžnosć k dispoziciji staja, aby instalacisku sćažku identificěrował. Wócyńśo za to shell Python APSO a zapódajśo:


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

Wudaśe koda górjejce jo bazowy zapis, źož LibreOfficeDev jo instalěrowany. Něnto musyśo rezultěrowacej sćažce pódzarědnik "program" pśidaś. To jo bazowy zarědnik, z kótaregož skripty Python ze separatnego procesa wuwjeźośo.

Wujźmy na přikład z togo, až /usr/lib/libreoffice/ ako wuslědk wuwjeźenja górnego koda dostawaśo. Pótom musyśo /usr/lib/libreoffice/program ako sćažku wužywaś, aby swóje skripty Python wuwjadł.

LibreOfficeDev z nastajenjami pipe abo socket startowaś

Aby skripty Python ze separatnego procesa wuwjadł, musyśo LibreOfficeDev z mało pśidatnymi nastajenjami startowaś, kótarež mě datowego kanala abo hostmě a port pódawaju, pśez kótarež eksterny proces z komponentowym procesom LibreOfficeDev komunicěrujo.

Wócyńśo pśikazowu smužku swójogo źěłowego systema, nawigěrujśo k programowemu zarědnikoju swójogo instalaciskego zapisa a zapódajśo:

Na Linux / Mac OS:

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

Na Windows:

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

ako flatpak:

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

Jaden z pśikazow górjejce buźo LibreOfficeDev z wócynjonym komunikaciskim kanalom startowaś, aby druge procese powěsći z nim wuměniś mógli.

Źiwajśo na to, až pjerwjejšny pśikład startowy centrum LibreOfficeDev wócynja. Jolic cośo wěstu komponentu wócyniś, na pśikład Writer, móžośo pśikazoju wobznamjenje --writer pśidaś:

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

Źiwajśo na parametry mě abo host a port, kótarež su w toś tom pśikłaźe aPipeName abo localhost resp. 2021.

Eksterny shell Python wuwjasć

Startujśo pówjerch Python z programowego zarědnika w swójej instalaciskej sćažce LibreOfficeDev. Slědujśo kšacam górjejce, aby zgónił, kak móžośo swóju instalacisku sćažku namakaś.

Na Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

Na Windows:

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

$ python.exe

To shell Python wócynijo a něnto móžośo zachopiś pśikaze zapódawaś, kótarež se pśez LibreOfficeDev wuwjedu. Ale nejpjerwjej musyśo zwisk pipe abo socket konfigurěrowaś. Instrukcija ScriptForge() dołojce musy se pśed prědnym wuwołanim CreateScriptService() wuwjasć.

Wuwjeźćo jaden ze slědujuceju kodowu:


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


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

Cytajśo wótrězk PYTHONPATH nastajiś dołojce, jolic daju zmólki pśi importěrowanju scriptforge.py abo uno.py.

Druga kodowa smužka górjejce nastajenja pipe abo host a port definěrujo, aby shell Python mógał z běžnym procesom LibreOfficeDev komunicěrowaś, kótaryž jo se ze samskimi nastajenjami pipe abo socket wócynił.

Něnto móžośo druge pśikaze Python wuwjasć a mógu z procesom LibreOfficeDev komunicěrowaś. Na pśikład:


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

PYTHONPATH nastajiś

Wótwisujucy wót konfiguracije wašogo źěłowego systema musyśo wokolinowu wariablu PYTHONPATH stajiś, aby biblioteku scriptforge.py importěrował, kótaraž se ze swójogo boka import biblioteki uno.py pomina.

Wužywajśo datajowy pytański rěd swójogo źěłowego systema, aby zapis zwěsćił, źož toś tej wobej dataji stej.

Pśi instalaciji Ubuntu na pśikład móžotej wobej dataji how byś:

scriptforge.py: Jo w /usr/lib/libreoffice/program
uno.py: Jo w /usr/lib/python3/dist-packages

Stajśo w toś tom paźe wokolinowu wariablu PYTHONPATH kaž slědujo, nježli až interpreter Python startujośo:

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

Městno toś teju datajow jo za kuždy źěłowy system a instalacisku metodu LibreOfficeDev rozdźělne.

The ScriptForge Library

LibreOfficeDev Pomoc wó skriptach Python

LibreOfficeDev z parametrami startowaś