Macros/Bases pour un EDI Python

TDF LibreOffice Document Liberation Project Blogs communautaires Weblate Nextcloud Redmine Ask LibreOffice Donner

• Accueil
• Development
• Design
• QA
• Évènements
• Documentation
• Website
• Localisation
• Accessibility
• Marketing
• Diversity
• Aide

• Macros
• Macros générales
• Writer
• Calc
• Impress
• Draw
• Base
• Math
• Basic/Python

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 Projects - Properties - Build de Geany.

• 

  MacOS - Project Properties Build tab.

• 

  GNU/Linux - Propriétés du project onglet Construire.

• 

  Windows - Project Properties Build tab.

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 à :

import uno
def my_1st_macro():
    # <span lang="en" dir="ltr" class="mw-content-ltr">Won't run directly in Anaconda, Geany, KDevelop, PyCharm or else</span>
    doc = XSCRIPTCONTEXT.getDocument()
    doc.getText().setString("Hello World!")

g_exportedScripts = my_1st_macro,

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

1. Run the macro
2. 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.

Example codes

Description	Start	Connect	Adapt	Run Debug	Stop
a. LibreOffice and OpenOffice officehelper.py module	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  # <span lang="en" dir="ltr" class="mw-content-ltr">Your code goes here</span>

g_exportedScripts = my_1st_macro,  # <span lang="en" dir="ltr" class="mw-content-ltr">Published macros</span>

if __name__ == '__main__':
    from IDE_utils import Runner, XSCRIPTCONTEXT
    with Runner() as jesse_owens:  # <span lang="en" dir="ltr" class="mw-content-ltr">Start/Stop, Connect/Adapt</span>
        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 officehelper.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.

Managing Documents (draft)

Opening a Document

Creating a Document

Saving a Document

Closing a Document

A General Purpose Converter

Bug Detection & Reporting

Examining (draft)

Examining LibreOffice

Configuration Properties

Path Settings

Getting & Setting DocumentProperties

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