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 Collabora Office naleznete na stránce Nápověda pro skripty Pythonu v Collabora Office.

Úprava skriptů Pythonu ve vývojových prostředích (IDE)

Ve vývojových prostředích (IDE) s příslušnou funkcí lze získat pro Python typovou nápovědu týkající se veřejných metod a vlastností knihovny ScriptForge. Při úpravě uživatelského skriptu se zobrazí:

se při najetí na instanci, metodu, nebo vlastnost objektu zobrazí podrobný popis.
po zapsání "." za instanci objektu se zobrazí rozbalovací pole s výpisem všech dostupných rozhraní.
po zapsání závorky za názvem metody se spustí doplňování kódu a zobrazí se argumenty této metody.

Typová nápověda se zobrazí pouze tehdy, je-li v názvech upravovaných metod a vlastností použita správná velikost písmen.

Spouštění skriptů Pythonu v Collabora Office

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 Collabora Office:

Spouštět skripty v rámci aktuálního procesu Collabora Office: Skripty Pythonu jsou spouštěny v rámci procesu Collabora Office 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 Collabora Office: Skripty Pythonu se spouští z externího procesu, který se připojí k běžícímu procesu Collabora Office pomocí soketu.

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

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

Pomocí rozšíření APSO

Nejsnazším způsobem jak začít v Collabora Office se skripty Pythonu, je nainstalovat rozšíření APSO. Po instalaci otevřete nějakou aplikaci Collabora Office 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 Collabora Office.

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 Collabora Office 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 Collabora Office

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 Collabora Office 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 Collabora Office 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í Collabora Office s nastavením soketů

Abyste mohli spouštět skripty Pythonu z odděleného procesu, je nutné spustit Collabora Office 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í Collabora Office.

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 Collabora Office a zadejte:

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

Tento příkaz spustí Collabora Office 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 Collabora Office. 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í Collabora Office. 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 Collabora Office. Nejprve je ale nutné nastavit soketové 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 Collabora Office, který byl otevřen se stejným nastavením soketů.

Poté můžete spouštět další příkazy Pythonu, budou moci komunikovat s procesem Collabora Office. 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 Collabora Office nainstalován.

Knihovna ScriptForge

Nápověda pro skripty Pythonu v Collabora Office

Spuštění Collabora Office s parametery