Macros/Python Basics/ja

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

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

役に立つLibreOfficeパッケージ

 * LibreOffice 7.x
 * LibreOfficeポータブル 6.x、 winPenPack LibreOffice 6.x
 * Linux用のAppImage、Flatpak、Snapイメージも利用可能です

互換性を確保したい場合はこちらも
 * Apache OpenOffice 4.x, Apache OpenOffice Portable 4.x, winPenPack Apache OpenOffice 4.x
 * OpenOffice.org Portable 3.2 (in french)

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



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



マクロとは
LibreOfficeのPythonマクロは以下のようになります. 上のプログラムを実行するには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マクロの例です. 開始、接続、適合、実行、停止、それぞれのステップでの利用についてのサンプルです.

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 can be obtained from GitLab.

Recommended Use
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.

Inspecting a Document for API Information
MRI, xRay & ObjectInspector

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