マクロ/Pythonの基本設定

From The Document Foundation Wiki
Jump to navigation Jump to search
This page is a translated version of the page Macros/Python Basics and the translation is 69% complete.
Other languages:
English • ‎français • ‎italiano • ‎日本語 • ‎한국어

はじめに

このページでは、統合開発環境(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  # Your code goes here

g_exportedScripts = my_1st_macro,  # Published macros

if __name__ == '__main__':
    from IDE_utils import Runner, XSCRIPTCONTEXT
    with Runner() as jesse_owens:  # Start/Stop, Connect/Adapt
        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...