Vytváření skriptů Pythonu s knihovnouScriptForge

Rozdíly mezi jazyky Basic a Python

Knihovna Scriptforge je k dispozici pro jazyky Basic a Python. Většina služeb, metod a vlastností funguje v obou programovacích jazycích stejně. Vzhledem k odlišnostem mezi nimi si však uživatel používající ScriptForge v Pythonu musí být vědom některých charakteristik této knihovny:

Názvy metod a vlastností: V Pythonu lze pro názvy metod a vlastností použít formát s malými písmeny (lowercased), s velkými písmeny na začátku slov (ProperCased) nebo s prvním písmenem malým a ostatními velkými (camelCased).
Argumenty: Všechny názvy argumentů předávaných do metod jsou malými písmeny (lowercased).
Data: Všechny objekty představující datum jsou předávány a vraceny jako nativní objekty Pythonu typu datetime.datetime.
Pole: Jednorozměrná pole jsou předávána a vracena jako n-tice (což je nezměnitelný objekt). Dvourozměrná pole jsou předávána a vracena jako n-tice n-tic.
None: Klíčové slovo Pythonu None odpovídá v Basicu Null, Empty nebo Nothing.
Objekty UNO: Všechny struktury UNO se mezi Basicem a Pythonem předávají bez jakýchkoliv změn.
Ladění: Nastane-li ve skriptu Pythonu využívajícím knihovnu ScriptForge chyba, chybová zpráva poskytnutá prostředím Pythonu obsahuje řádek kódu, který chybu vyvolal. V chybových zprávách Basicu tato informace není.

Další informace o skriptech Pythonu v LibreOffice naleznete na stránce Nápověda pro skripty Pythonu v LibreOffice.

Spouštění skriptů Pythonu v LibreOffice

Podle toho, čeho hodláte dosáhnout, můžete zvolit jeden z následujících přístupů, jak spouštět skripty Pythonu v LibreOffice:

Spouštět skripty v rámci aktuálního procesu LibreOffice: Skripty Pythonu jsou spouštěny v rámci procesu LibreOffice volbou z nabídky Nástroje - Makra - Spustit makro nebo pomocí rozšíření APSO, který se volají uživatelské skripty uložené ve složce se skripty Pythonu. Shell Pythonu APSO můžete také využít pro interaktivní spouštění skriptů Pythonu.
Spouštět skripty odděleně od procesu LibreOffice: Skripty Pythonu se spouští z externího procesu, který se připojí k běžícímu procesu LibreOffice pomocí socketu.

Plánujete-li spouštět skripty v rámci procesu LibreOffice, doporučuje se nainstalovat rozšíření APSO (Alternative Script Organizer for Python). K vývoji skriptů Pythonu mimo LibreOffice však můžete zvolit svoje oblíbené integrované vývojové prostředí (IDE).

Spouštění skriptů v rámci procesu LibreOffice

Pomocí rozšíření APSO

Nejsnazším způsobem jak začít v LibreOffice se skripty Pythonu, je nainstalovat rozšíření APSO. Po instalaci otevřete nějakou aplikaci LibreOffice a zvolte Nástroje - Makra - Organize Python scripts.

V hlavním okně APSO zvolte Menu - Python shell.

APSO můžete otevřít také výchozí zkratkou Alt+Shift+F11.

Poté můžete začít psát příkazy Pythonu, po provedení každého řádku kódu se v shellu vypíše odpovídající výstup.

Abyste mohli začít používat knihovnu ScriptForge, je nutné importovat metodu CreateScriptService, díky níž budete moci přistupovat k službám poskytovaným touto knihovnou. V níže uvedeném příkladu se používá služba Basic pro zobrazení dialogu.


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

Výše uvedený příklad spustíte tak, že postupně po jedné zadáte řádky do shellu Pythonu a po každé stisknete klávesu Enter.

Spouštět můžete příkazy Pythonu používající libovolnou službu ScriptForge. Následující část kódu například vytvoří prázdné okno Writeru pomocí služby UI.


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

Vytváření souborů se skripty Pythonu

Vlastní skripty Pythonu můžete vytvářet a upravovat ve svém oblíbeném textovém editoru. Později je zavoláte z jakékoliv aplikace LibreOffice.

Prvním krokem je zjistit, kde jsou uloženy uživatelské skripty. To je popsáno na stránce Uspořádání a umístění skriptů Pythonu.

Poté můžete ve složce s uživatelskými skripty Pythonu vytvořit textový soubor, například sf_test.py, a začít se psaním skriptů.

Následuje jednoduchý příklad, v němž se získá z buňky Calcu číselná hodnota a zvětší se o 1. Do souboru sf_test.py přepište následující kód.


    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, )

V příkladu je vytvořena funkce increment_cell. Proměnná g_exportedScripts je n-tice určující, které funkce se v LibreOffice zobrazí jako uživatelské skripty.

Chcete-li tento skript spustit v dokumentu Calcu:

Vytvořte nebo otevřete soubor Calcu.
Zadejte do buňky "A1" na aktuálním listu libovolnou číselnou hodnotu.
Zvolte Nástroje - Makra - Spustit makro.
Ve výběru knihovny zvolte Moje makra - sf_test. Poté vyberte ze seznamu Název makra funkci increment_cell.
Klepněte na Spustit. Hodnota v buňce "A1" se zvětšila o 1.

Pro spouštění skriptů Pythonu můžete použít také APSO:

Nejprve APSO otevřete volbou Nástroje - Makra - Organize Python scripts.
V seznamu maker přejděte na My macros - sf_test - increment_cell.
Klepněte na Execute.

Spouštění skriptů odděleně od procesu LibreOffice

Určení instalační složky

První krokem ke spouštění skriptů z odděleného procesu je najít složky, v níž je LibreOffice nainstalován. Lze to provést několika způsoby, ScriptForge ale nabízí rychlou možnost, jak cestu k instalaci identifikovat. Za tím účelem otevřete shell Pythonu APSO a zadejte do něj:


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

Výstupem výše uvedeného kódu je základní adresář, v němž je LibreOffice nainstalován. K výsledné cestě potřebujete přidat podsložku „program“, abyste získali základní složku, z níž budete spouštět v odděleném procesu skripty Pythonu.

Jako výsledek výše uvedeného kódu Pythonu jste získali například cestu /usr/lib/libreoffice/. Poté je cestou pro spouštění skriptů Pythonu /usr/lib/libreoffice/program.

Spuštění LibreOffice s nastavením socketů

Abyste mohli spouštět skripty Pythonu z odděleného procesu, je nutné spustit LibreOffice s několika dalšími parametry, které určují název hostitele a port, pomocí kterého bude externí proces komunikovat s procesem s aplikací LibreOffice.

Otevřete příkazový řádek operačního systému, přejděte v něm do složky „program“ v instalačním adresáři LibreOffice a zadejte:

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

Tento příkaz spustí LibreOffice s otevřeným komunikačním kanálem, prostřednictvím kterého s ním mohou jiné procesy vyměňovat zprávy.

Výše uvedený příkaz otevře úvodní obrazovku LibreOffice. Chcete-li otevřít určitou aplikaci, například Writer, přidejte k příkazu přepínač --writer.

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

Poznamenejte si parametry host a port, které mají v tomto příkladu hodnoty localhost a 2021.

Spuštění externího shellu Pythonu

Spusťte shell Pythonu ze složky program v cestě s instalací LibreOffice. Instalační cestu zjistíte podle postupu popsaného výše.

V systému Linux / MacOS:

$ cd /usr/lib/libreoffice/program

$ python

V systému Windows:

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

$ python.exe

Otevře se shell Pythonu, v němž můžete zadávat příkazy, které se provedou v LibreOffice. Nejprve je ale nutné nastavit socketové připojení.


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

V případě chyb při importu souborů scriptforge.py nebo uno.py si přečtete níže uvedenou část Nastavení PYTHONPATH.

Na druhém řádku výše uvedeného kódu je určeno nastavení host a port, díky němuž může shell Pythonu komunikovat se spuštěným procesem LibreOffice, který byl otevřen se stejným nastavením socketů.

Poté můžete spouštět další příkazy Pythonu, budou moci komunikovat s procesem LibreOffice. Například:


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

Nastavení PYTHONPATH

V závislosti na konfiguraci operačního systému bude potřeba nastavit proměnnou prostředí PYTHONPATH, aby bylo možné importovat knihovnu scriptforge.py, která dále vyžaduje import knihovny uno.py.

Pomocí vyhledávání v operačním systému zjistěte adresáře, kde se tyto soubory nacházejí.

Například ve výchozí instalaci systému Ubuntu se tyto soubory mohou nacházet v těchto umístěních:

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

V tomto případě nastavte před spuštěním interpretu Pythonu proměnnou prostředí PYTHONPATH následovně:

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

Umístění těchto souborů se liší v závislosti na operačním systému a způsobu, jakým byl LibreOffice nainstalován.

Knihovna ScriptForge

Nápověda pro skripty Pythonu v LibreOffice

Spuštění LibreOffice s parametery