Macros/Python Basics/en

Preamble
This page presents the steps enabling to develop LibreOffice Python macros within an Integrated Development Environment (IDE). Configuration or preferences setup are presented for a limited set of free and open source (FOSS) IDEs. Direct editing and debugging of Python macros within LibreOffice requires solely the Alternative Python Script Organizer (APSO) extension. In which case Start, Connect, & Stop chapter content can be skipped.

( ... Documents, Configuration, Object Inspection ... )

Useful LibreOffice Packages

 * LibreOffice 7.x
 * LibreOffice Portable 6.x, winPenPack LibreOffice 6.x
 * AppImage, Flatpak or Snap Linux images are available

For those wishing to explore cross-compatibility:
 * Apache OpenOffice 4.x, Apache OpenOffice Portable 4.x, winPenPack Apache OpenOffice 4.x
 * OpenOffice.org Portable 3.2 (in french)

IDE Project Setup
Each IDE requires a different configuration or setup.

Geany
Libreoffice or OpenOffice embedded Python interpreters require to be defined explicity in Geany  P rojects -  P roperties -  B uild dialogs:

Example values:
 * 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
Pyzo configuration dialog for embedded Python interpreters as of Shell - Edit shell configurations... menu:

PyCharm
LibreOffice Python interpreter configuration with PyCharm default settings dialog:

What's in a Macro
A LibreOffice Python macro may look like: Executing the above requires bridging together the IDE and LibreOffice. Once done UNO objects become accessible.

Up to five steps can be necessary to achieve this:
 * 1) Start LibreOffice as a service
 * 2) Connect to a service
 * 3) create a XSCRIPTCONTEXT Adaptor
 * 4) Run the macro
 * 5) Stop LibreOffice as a service

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.

Start, Connect, Adapt, Run & Stop
The table below lists a few public (Libre/Open)Office Python macro examples. Their usage of the Start, Connect, Adapt, Run, Stop steps is indicated.

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