目次

# ScriptForgeを利用したPythonスクリプトの作成

## BasicとPythonの違い

ScriptForgeライブラリは、BasicとPython両方に対応しており、ほとんどのサービス、メソッド、プロパティは、どちらのプラグラミング言語でも同じように動作します。ですが、言語により動作が異なるのでPythonからScriptForgeを使う場合、ライブラリの特性に注意する必要があります。

- メソッドとプロパティ名: Pythonでは、すべてのメソッドとプロパティの名前に小文字のみ、先頭の文字を大文字、キャメルケースの形式が使えます。

- 引数: メソッドに渡されるすべてのキーワード引数は小文字です。

- 日付: すべての日付オブジェクトは、Pythonネイティブのdatetime.datetimeオブジェクトとして渡され、返されます。

- 配列: 1次元配列はタプル(Immutableオブジェクト)として渡され、返されます。2次元配列は、タプルのタプルとして渡され、返されます。

- None: PythonのNoneキーワードは、BasicのNull、Empty、Nothingと同じです。

- UNOオブジェクト: すべてのUNO構造体は、BasicとPythonの間で変更なく交換されます。

- デバッグ: ScriptForgeを使用したPythonスクリプトでエラーが発生した場合、Python実行スタックからのエラーメッセージは、エラーの原因となったコードの行を表示します。Basicのエラーメッセージでは、このメッセージは表示されません。

LibreOfficeで利用するPythonスクリプトの詳細については、 LibreOffice Pythonスクリプトヘルプをご覧ください。

## Editing Python scripts in IDEs

Python typing hints - relating to ScriptForge services public methods and properties - can be obtained from IDEs that support such facility. Visually, while editing a user script:

- hovering an object instance, a method or a property displays its detailed description.

- a "." after an object instance displays a drop-down box listing all available interfaces.

- brackets after a method-name start code-completion by displaying its arguments.

Typing hints are displayed when editing methods and properties with propercase letters.

## LibreOfficeでPythonスクリプトを実行する

LibreOfficeでPythonスクリプトを実行するには、目的に応じて以下のどちらかの方法で実行します。

- 現在のLibreOfficeプロセス内で実行する: LibreOfficeプロセス内からPythonスクリプトを実行するには、メニューの[ツール] - [マクロ] - [マクロの実行]を選ぶか、拡張機能APSOからPythonスクリプトフォルダにあるユーザースクリプトを呼び出して実行します。また、APSOのPythonシェルを使ってインタラクティブにPythonスクリプトを実行できます。

- LibreOfficeプロセスとは別にスクリプトを実行する: Pythonスクリプトをソケットを使って実行中のLibreOfficeプロセスに接続して外部プロセスとして実行します。

LibreOfficeプロセス内でスクリプトを実行する場合は、APSO(Alternative Script Organizer for Python)拡張機能のインストールをお勧めします。APSOを使ったPythonスクリプトの開発は、LibreOfficeの外部から好みのPython IDEを使い、開発します。

## LibreOfficeプロセス内でスクリプトを実行する

### APSO拡張機能を使う

The easiest way to get started with Python scripting in LibreOffice is by installing the APSO extension. After installing it, open any LibreOffice component and go to Tools - Macros - Organize Python Scripts.

In APSO's main window go to Menu - Python Shell.

Alternatively you can open APSO using the default shortcut Alt + Shift + F11.

Now you can start typing Python commands and the shell will print the corresponding output after each line of code is executed.

To start using the ScriptForge library, you need to import the CreateScriptService method, with which you will be able to access the services provided by the library. The example below uses the Basic service to display a message box.

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

To run the example above, enter each line in the Python shell, one by one, pressing the Enter key after you type each line of code.

Now you can start executing Python commands using any of the ScriptForge services. For example, the code snippet below uses the UI service to create a blank Writer document.

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

### Creating Python script files

You can create your own Python files and edit them with your preferred text editor. Later you can call them from within any LibreOffice component.

The first step is to locate where your user scripts are stored. For that, refer to Python Scripts Organization and Location help page.

Now you can create a text file inside your Python user scripts folder, for instance sf_test.py, and start typing your scripts.

Next is a simple example that gets the numeric value from a Calc cell and increments it by 1. Simply type the following code into the sf_test.py file.

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

This example creates the increment_cell function. Note that g_exportedScripts is a tuple that tells which functions will be displayed in LibreOffice as user scripts.

To run this script from within a Calc document:

1. Create or open a Calc file.

2. Enter some numeric value into cell "A1" in the current sheet.

3. Go to Tools - Macros - Run Macros .

4. Choose My Macros - sf_test in the library selector. Then choose the increment_cell function under the Macro Name list.

5. Click Run. Note that the value in cell "A1" was incremented by 1.

You can also use APSO to run Python scripts in a similar manner:

1. First open APSO by going to Tools - Macros - Organize Python Scripts.

2. In the macro list, navigate to My Macros - sf_test - increment_cell.

3. Click Execute.

## Running Scripts separately from the LibreOffice process

### Determining the Installation Path

The first step to run scripts from a separate process is to find the folder where LibreOffice is installed. There are several ways to do that, but ScriptForge provides a quick way to identify your installation path. For that, open APSO's Python shell and type:

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

The output from the code above is the base directory where LibreOffice is installed. Now you need to add the "program" subfolder to the resulting path. This is the base folder from which you will run Python scripts from a separate process.

For example, suppose you get /usr/lib/libreoffice/ as the result from running the Python code above. Then you need to consider /usr/lib/libreoffice/program as the path to run your Python scripts.

### Start LibreOffice with socket settings

To run Python scripts from a separate process, you need to start LibreOffice with a few additional options that specify the hostname and port through which the external process will communicate with the LibreOffice component process.

Open the your operating system's command prompt, navigate to the program folder of your LibreOffice installation directory and type:

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

The command above will start LibreOffice with a communication channel open so that other processes can exchange messages with it.

Note that the previous example opens LibreOffice start center. If you want to open a specific component, for instance Writer, you can add the --writer flag to the command, as follows.

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

Take note of the host and port parameters, which in this example are localhost and 2021, respectively.

### Running an External Python Shell

Start the Python shell from within the program folder inside your LibreOffice installation path. Follow the steps above to learn how to find your installation path.

On Linux / Mac OS:

$ cd /usr/lib/libreoffice/program

$ python

On Windows:

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

$ python.exe

This will open the Python shell and now you can start typing commands that will be executed by LibreOffice. But first you need to set up the socket connection.

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

Read the section Setting PYTHONPATH below in case of errors importing scriptforge.py or uno.py.

The second line of code above defines the host and port settings so that the Python shell can communicate with an ongoing LibreOffice process opened with the same socket settings.

Now you can run other Python commands and they will be able to communicate with the LibreOffice process. For example:

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

### Setting PYTHONPATH

Depending on your operating system's configuration you will need to set the environment variable PYTHONPATH in order to import the scriptforge.py library, which in turn requires importing the uno.py library.

Use your operating system's file search tool to determine the directory where both these files are located.

For instance, on a default Ubuntu installation both files may be located at:

- scriptforge.py: Located in /usr/lib/libreoffice/program

- uno.py: Located in /usr/lib/python3/dist-packages

In this case, set the environment variable PYTHONPATH as follows before starting the Python interpreter:

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

The location of these files will be different for each operating system and LibreOffice installation method.

関連項目

ScriptForgeライブラリ

LibreOffice Pythonスクリプトヘルプ

Starting LibreOffice Software With Parameters