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 LibreOffice Python Scripts Help for more information on Python scripting using LibreOffice.

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 LibreOffice

Според това какво се опитвате да постигнете, може да изберете един от следните подходи за изпълнение на скриптове на Python в LibreOffice:

Изпълнение на скриптове в текущия процес на LibreOffice: скриптовете на Python се изпълняват в процеса на LibreOffice с командата Инструменти - Макроси - Стартиране на макрос или разширението APSO, които извикват потребителски скриптове, съхранявани в папката за скриптове на Python. Можете да използвате и обвивката на Python в APSO, за да стартирате скриптове на Python интерактивно.
Изпълнение на скриптове отделно от процеса на LibreOffice: скриптовете на Python се изпълняват от външен процес, който се свързва със съществуващ процес на LibreOffice чрез канал или сокет (pipe / socket).

Ако планирате скриптовете да се изпълняват в рамките на процеса на LibreOffice, препоръчва се да инсталирате разширението APSO (Alternative Script Organizer for Python). За да разработвате скриптовете на Python извън LibreOffice обаче, можете да изберете предпочитана от вас развойна среда за Python.

Изпълнение на скриптове от процеса на LibreOffice

Използване на разширението APSO

Най-лесният начин да започнете работа със скриптове на Python в LibreOffice, е да инсталирате разширението APSO. След това отворете произволен компонент на LibreOffice и изберете Инструменти - Макроси - Организиране на скриптове на Python.

В главния прозорец на APSO изберете Menu - Python Shell.

Можете вместо това да отворите APSO с подразбираната клавишна комбинация Alt + Shift + F11.

Сега можете да въвеждате команди на Python и обвивката ще печата съответния изход след изпълнението на всеки ред код.

За да започнете да използвате библиотеката ScriptForge, трябва да импортирате метода CreateScriptService, с който ще можете да осъществите достъп до услугите, предоставяни от библиотеката. В примера по-долу е използвана услугата Basic, за да се покаже диалогов прозорец със съобщение.


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

За да се изпълни горният пример, въведете всички редове в обвивката на Python един по един, като натискате Enter след всеки ред код.

Сега вече можете да стартирате команди на Python, използващи всички услуги на ScriptForge. Например в откъса код по-долу е използвана услугата UI, за да се създаде празен документ на Writer.


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

Създаване на файлове със скриптове на Python

Можете да създавате свои собствени файлове на Python и да ги редактирате с предпочитания от вас текстов редактор. След това можете да ги извиквате от който и да е компонент на LibreOffice.

Първата стъпка е да намерите къде се съхраняват потребителските ви скриптове. За тази цел вижте страницата Организация и местоположение на скриптовете на Python в помощта.

Сега можете да създадете текстов файл в папката за потребителски скриптове на Python, например my_script.py, и да започнете да въвеждате скриптовете си.

Следва пример, който извлича числовата стойност от клетка на Calc и я увеличава с 1. Просто въведете долния код във файла 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, )

В този пример е създадена функцията increment_cell. Обърнете внимание, че g_exportedScripts е кортеж, който описва кои функции да се показват в LibreOffice като потребителски скриптове.

За да стартирате този скрипт от документ на Calc:

Създайте или отворете файл на Calc.
Въведете числова стойност в клетката „A1“ на текущия лист.
Изберете Инструменти - Макроси - Стартиране на макрос.
Изберете Моите макроси - my_script в списъка с библиотеки. После изберете функцията increment_cell в списъка Име на макрос.
Щракнете върху Изпълняване. Забележете, че стойността в клетката „A1“ се е увеличила с 1.

По подобен начин можете да използвате APSO за изпълнение на скриптове на Python.

Първо отворете APSO, като изберете Инструменти - Макроси - Organize Python Scripts.
В списъка с макроси намерете My Macros - my_script - increment_cell.
Щракнете върху Execute.

Изпълнение на скриптове отделно от процеса на LibreOffice

Определяне на инсталационния път

Първата стъпка за изпълнение на скриптове от отделен процес е да се намери папката, в която е инсталиран LibreOffice. Има няколко варианта за това, но ScriptForge предлага бърз начин да намерите пътя на инсталацията. За тази цел отворете обвивката на Python в APSO и въведете:


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

Изходът от горния код е основната директория, в която е инсталиран LibreOffice. Сега трябва да добавите подпапката "program" към получения път. Това е базовата папка, от която ще се изпълняват в отделен процес скриптовете на Python.

Например, да кажем, че получите /usr/lib/libreoffice/ като резултат от изпълнението на горния код на Python. Тогава трябва да разглеждате /usr/lib/libreoffice/program като път за изпълнение на скриптовете ви на Python.

Стартиране на LibreOffice с настройка pipe или socket

За да се изпълняват скриптове на Python от отделен процес, трябва да стартирате LibreOffice с няколко допълнителни настройки, които задават името на канала или името на хост и порта, през които външният процес ще комуникира с процеса на компонента на LibreOffice.

Отворете командния прозорец на операционната система, отидете в папката program на инсталационната директория на LibreOffice и въведете някое от следните:

В Linux или macOS:

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

В Windows:

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

Като Flatpak:

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

Всяка от горните команди стартира LibreOffice с отворен канал за комуникация, така че останалите процеси да могат да обменят съобщения с него.

Забележете, че предходният пример отваря началния екран на LibreOffice. Ако искате да отворите конкретен компонент, например Writer, можете да добавите към командата флага --writer, както следва.

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

Обърнете внимание на параметрите name или host и port, които в примера са съответно aPipeName или localhost и 2021.

Работа с външна обвивка на Python

Стартирайте обвивката на Python от папката program в инсталационния път на LibreOffice. За да намерите инсталационния път, следвайте стъпките по-горе.

В Linux или macOS:

$ cd /usr/lib/libreoffice/program

$ python

В Windows:

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

$ python.exe

Това ще отвори обвивката на Python и можете да започнете да въвеждате команди, които ще бъдат изпълнявани от LibreOffice. Но първо трябва да настроите връзката през pipe или socket. Обръщението към ScriptForge() по-долу трябва да предхожда първото извикване на CreateScriptService().

Подайте една от долните команди:


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


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

Прочетете раздела Задаване на PYTHONPATH по-долу в случай на грешки при импортиране от scriptforge.py или uno.py.

Вторият ред от горния код дефинира настройките на канала (pipe) или хоста и порта (host и port), за да може обвивката на Python да комуникира с текущ процес на LibreOffice, отворен със същите настройки за канал или сокет.

Сега можете да подавате други команди на Python и те ще могат да комуникират с процеса на LibreOffice. Например:


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

Задаване на PYTHONPATH

Depending on your operating system's configuration you will need to set the environment variable PYTHONPATH in order to import the scriptforge.py library, which in turn requires importing the uno.py library.

Use your operating system's file search tool to determine the directory where both these files are located.

For instance, on a default Ubuntu installation both files may be located at:

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

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

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

The location of these files will be different for each operating system and LibreOffice installation method.

Библиотеката ScriptForge

Помощ за скриптовете на Python в LibreOffice

Стартиране на LibreOffice с параметри