Macros/Python Basics/fr

Préambule
Cette page présente les principes de fonctionnement d'un EDI pour développer des scripts Python. Les options de configuration ou d'installation sont illustrées pour quelques EDIs libres à code source ouvert. L'édition directe et le débogage de macros Python ne nécessite que l'extension Alternative Python Script Organizer (APSO). Dans ce cas allez à la rubrique ...

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

Versions de LibreOffice utilisables

 * LibreOffice 6.x
 * LibreOffice Portable 6.x, winPenPack LibreOffice 6.x
 * Des images AppImage, Flatpak ou Snap pour Linux existent

Pour explorer la compatiblité avec des solutions apparentées :
 * Apache OpenOffice 4.x, Apache OpenOffice Portable 4.x, winPenPack Apache OpenOffice 4.x
 * OpenOffice.org Portable 3.2 (en français)

Config. Projet de l'IDE
Chaque EDI possède sa propre configuration.

Geany
Les interpréteurs Python de LibreOffice ou d'OpenOffice doivent être explicitement déclarés dans la fenêtre  P rojects -  P roperties -  B uild de Geany.

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:

Corps d'un Script Python
Un script Python Python ressemble à : Une passerelle est nécessaire entre l'EDI et LibreOffice pour l'exécuter. Une fois en place Les objets UNO sont utilisables.

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
Le tableau ci-après recense quelques exemples publics de scripts pour (Libre/Open)Office. Il détaille les étapes qu'ils intègrent.

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