マクロ/Pythonの基本設定

    From The Document Foundation Wiki
    This page is a translated version of the page Macros/Python Basics and the translation is 69% complete.
    Other languages:

    はじめに

    このページでは、統合開発環境(IDE)を使ってLibreOfficeのPythonマクロを開発するための手順を解説します。解説する環境設定などは、自由ソフトウエアまたはオープンソース(FLOSS)のIDEのみ紹介しています。PythonマクロをLibreOfficeから直接、編集やデバッグするにはAlternative Python Script Organizer(APSO)拡張機能が必要です。APSOを使う場合は、開始、接続、停止の章を読み飛ばせます。

    ( ... ドキュメント、設定、オブジェクト調査 ... )

    役に立つLibreOfficeパッケージ

    互換性を確保したい場合はこちらも

    IDEプロジェクトの設定

    設定はIDEによって異なります。

    Geany

    Geanyのプロジェクト(P) - プロパティ(P) - ビルド(B)ダイアログからLibreOfficeまたはOpenOfficeに内蔵のPythonインタプリタを指定する必要があります。

    設定例

    • MacOS
      • P1. Compile = /Applications/LibreOffice.app/Contents/Resources/python -m py_compile "%f"
      • E1. Execute = /Applications/LibreOffice.app/Contents/Resources/python "%f"
    • Linux
      • P1. Compile = opt/openoffice4/program/python -m py_compile "%f"
      • E1. Execute = opt/openoffice4/program/python "%f"
    • Windows
      • Python commands
        • 1. Compile = "D:\Program Files\LibreOffice 5\program\python" -m py_compile "%f"
        • 2. Interpret = "D:\Program Files\LibreOffice 5\program\python"
      • Execute commands
        • 1. Execute = "D:\Program Files\LibreOffice 5\program\python" "%f"
        • 2. Unit Tests = "D:\Program Files\LibreOffice 5\program\python" -m unittest discover

    Pyzo

    LibreOffice内蔵Pythonインタープリタを設定した、Pyzo設定ダイアログ(メニューのShell - Edit shell configurations...)

    Pyzo - Shell - Shell configurations...

    PyCharm

    LibreOffice内蔵Pythonインタープリタを設定したPyCharmのデフォルト設定ダイアログ

    PyCharm - Default Settings - Project Interpreter

    マクロとは

    LibreOfficeのPythonマクロは以下のようになります。

    import uno
    def my_1st_macro():
        # Anaconda, Geany, KDevelop, PyCharmなどでは直接実行できません
        doc = XSCRIPTCONTEXT.getDocument()
        doc.getText().setString("Hello World!")
    
    g_exportedScripts = my_1st_macro,

    上のプログラムを実行するにはIDEとLibreOfficeを接続の必要があります。一度、接続できればUNOオブジェクトはアクセスできるようになります。

    これを実現するには最大で5つの段階が必要になります

    1. サービスとしてLibreOfficeを開始
    2. サービスに接続
    3. XSCRIPTCONTEXTアダプターを作成
    4. マクロを実行
    5. LibreOfficeサービスを停止

    While examples available on the internet do not resort to all these steps, their study exhibits coding guidelines that IDE_utils module borrows from in order to innocuously integrate in IDEs.

    開始、接続、適合、実行、停止

    以下の表は、公開されている(Libre/Open)OfficeのPythonマクロの例です。開始、接続、適合、実行、停止、それぞれのステップでの利用についてのサンプルです。

    サンプルプログラム
    説明 開始 接続 適合 実行

    デバッグ

    停止
    a. LibreOfficeとOpenOfficeのofficehelper.pyモジュール x x
    b. Office.bridge.py A bridge for IDE with XSCRIPTCONTEXT revisité, Feb. 2017 (in french) x x x
    c. Interface-oriented programming in OpenOffice / LibreOffice: automate your office tasks with Python macros, Sep. 2013 x x
    d. unopy.py LibreOffice macro execution with PyCharm, Jan. 2014 (in japanese) x x x
    e. ooutils.py - Starting, Stopping and Connecting to OpenOffice with Python, Dec. 2008 x x x x
    f. Python UNO-bridge, Oct. 2008 x

    IDE enablement

    Based on these resources, requirements for Python macro enablement in IDEs can be summarised as:

    • start, connect, adapt, run and stop steps to be optional
    • Support multiple platforms i.e. essentially Linux, MacOS and Windows
    • on-demand startup --options
    • Permit pipe and/or socket connections
    • decoupled coding using injection
    • Provide Service pooling, context pooling
    • and KISS

    IDE_utils module proposal: A Runner() context manager class is responsible for starting and stopping soffice instances. An optional Runners.json configuration file contains service-options pairs holding the services to start and their running conditions. A connect() function bridges the actual IDE and LibreOffice instances. A ScriptContext() object is injected as XSCRIPTCONTEXT built-in. start() and stop() coding facilities are wrapping-up Runner() features. The module skeleton looks like:

    #!  # IDE_utils.py
    import officehelper
    RUNNERS = 'Runners.json'
    
    class Runner(soffice=None): pass
    class ScriptContext(): pass
    
    _ctx = officehelper.bootstrap()
    XSCRIPTCONTEXT = ScriptContext(_ctx)
    
    def connect(host='localhost', port=2002, pipe=None): pass
    def start(soffice=None): pass
    def _stop(): pass

    IDE_utils.py can be obtained from GitLab.

    Recommended Use

    import uno
    def my_1st_macro(): pass  # <span lang="en" dir="ltr" class="mw-content-ltr">Your code goes here</span>
    
    g_exportedScripts = my_1st_macro,  # <span lang="en" dir="ltr" class="mw-content-ltr">Published macros</span>
    
    if __name__ == '__main__':
        from IDE_utils import Runner, XSCRIPTCONTEXT
        with Runner() as jesse_owens:  # <span lang="en" dir="ltr" class="mw-content-ltr">Start/Stop, Connect/Adapt</span>
            my_1st_macro  # Run

    The example above should be your preferred use for IDE_utils. As starting and stopping a service may not fit all situations, these steps are optional. That same module allows the customization of LibreOffice - or OpenOffice - services running conditions. "Getting Started" user guide provides detailed description of the 3 different ways to use IDE_utils:

    • Resorting to (Libre/Open)Office default Python bootstrap() mechanism,
    • Letting Runner() and ScriptContext() objects take responsibility for start, connect, adapt, run and stop steps,
    • Deciding when to perform start, connect, adapt, run and stop steps.

    ドキュメントの管理(草稿)

    ドキュメントを開く

    ドキュメントの作成

    ドキュメントの保存

    ドキュメントを閉じる

    A General Purpose Converter

    バグの検知と報告

    調査(草稿)

    LibreOfficeを調べる

    設定のプロパティ

    パス設定

    ドキュメントプロパティの取得・設定

    Reporting OS File Properties

    Setting Document Properties

    Inspecting a Document for API Information

    MRI, xRay & ObjectInspector

    Listening (draft)

    ... catching document(s) events, catching URP bridge events...