Macros/Python Guide/fr/Guide/general

⇐ Introduction au développement en Python Identifier son système ⇒
 * Table des matières|

Principes Généraux

= Conception et Développement d'Applications Python = Pour parler de conception et de développement il faut s'instruire sur ce que sont les paradigmes de programmation et leur périmètre sur le langage Python

Ce tutoriel vous propose comme paradigme une approche procédurale du développement pour des raisons pédagogiques. Il est souvent plus facile de comprendre un cheminement que de percevoir une globalité. Le processus étape par étape est une approche procédurale, alors que la gestion d'états possibles, qu'est l'objet, demande une vision d'ensemble que nous aborderons à la fin de chaque parties du tutoriel. Et comme le diraient les anciens, il faut commencer par des fondations avant de faire la maison, puis il faut avoir fait une maison pour pouvoir en parler.

Si vous souhaitez vous lancer dans un développement lourd de macros python, je vous conseille de lire concevoir des projets LibreOffice complexes et/ou collaboratifs

= Analyse du code = Pour commencer à coder des macros il faut s'équiper avec des outils d'analyse du code. Ces outils vont nous aider à comprendre nos erreurs et à deviner comment programmer pour aboutir au résultat recherché.

En mode interactif
Propre aux langage interactif, Python nous permet d'exécuter notre code au fur et à mesure.

D'abord nous allons exécuter Python en mode interactif avec LibreOffice dans un terminal shell :

Sous Linux : libreoffice --accept="socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" & python3 Sous macOS : /Applications/LibreOffice.app/Contents/MacOS/soffice --accept="socket,host=localhost,port=2002;urp;StarOffice.ServiceManager" & /Applications/LibreOffice.app/Contents/MacOS/python Sous Windows : "C:\\Program Files (x86)\LibreOffice 5\program\soffice.exe" --accept="socket,host=localhost,port=2002;urp;" "C:\\Program Files (x86)\LibreOffice 5\program\python.exe"

L'interpréteur python s'exécute dans son environnement : Python 3.5.2+ (default, Sep 22 2016, 12:18:14) [GCC 6.2.0 20160927] on linux Type "help", "copyright", "credits" or "license" for more information. >>>

Importons la librairie UNO >>> import uno

Nous pouvons optenir de l'aide sur la gestion de la librairie uno >>> help(uno)

Ce qui nous affiche : Help on module uno: NAME uno CLASSES builtins.object Any Bool ByteSequence Char Enum Type class Any(builtins.object) | use only in connection with uno.invoke to pass an explicit typed any |       |  Methods defined here: |       |  __init__(self, type, value) |     Initialize self. See help(type(self)) for accurate signature. |       |  --      |  Data descriptors defined here: |       |  __dict__ |     dictionary for instance variables (if defined) |       |  __weakref__ |     list of weak references to the object (if defined) class Bool(builtins.object) | Represents a UNO boolean, use an instance of this class to explicitly :

Déplacez-vous avec les flêches vers le haut «↑» et vers le bas «↓» du clavier pour consulter l'aide. Tapez la touche «q» pour sortir de l'aide.

Nous pouvons aussi visuliser l'objet avec la commande dir >>> dir(uno) ['Any', 'Bool', 'ByteSequence', 'Char', 'Enum', 'Type', '_ConstantGroup', '__builtin__', '__builtins__', '__cached__', '__doc__', '__file__', '__loader__', '__name__', '__package__', '__spec__', '_g_ctx', '_g_delegatee', '_impl_extractName', '_impl_getConstantGroupByName', '_uno_extract_printable_stacktrace', '_uno_import', '_uno_struct__eq__', '_uno_struct__getattr__', '_uno_struct__init__', '_uno_struct__repr__', '_uno_struct__setattr__', '_uno_struct__str__', 'absolutize', 'createUnoStruct', 'fileUrlToSystemPath', 'generateUuid', 'getClass', 'getComponentContext', 'getConstantByName', 'getCurrentContext', 'getTypeByName', 'invoke', 'isInterface', 'os', 'pyuno', 'setCurrentContext', 'socket', 'sys', 'systemPathToFileUrl', 'unicode']

MRI l'explorateur d'API
MRI est un outil d'introspection d'objets UNO, écrit en Python. Si vous voulez connaître les objets UNO, essayez d'utiliser MRI.

Les cibles de cette extension sont les macro, le développement d'extension et ainsi de suite. MRI est un service UNO qui peut être utilisé facilement depuis n'importe quel autre langage.

MRI nécessite l'installation d'une liaison Python-UNO.

Installation de l'extension MRI
Téléchargez l'extension ici

Ouvrez le fichier téléchargé mri-x.x.x.oxt avec LibreOffice.

Faite défiler vers le bas avec le bouton «Défiler vers le bas» puis cliquez sur le bouton «Accepter» si vous êtes d'accord avec la licence. Puis vérifiez si la version est à jour avec le bouton «Vérifier les mises à jour...». Si il y a une mise à jour cliquez sur le bouton «Installer». Une fois l'extension mise à jour cliquez sur le bouton «OK». Puis cliquez sur le bouton «Fermer» de la boite de dialogue Gestionnaire des extensions.

Utilisation de MRI
Voici le code de la fonction d'appel de l'environnement MRI

Pour tester MRI vous devez créer un nouvelle macro avec l'éditeur de macros.

Pour cela ouvrez le menu dans LibreOffice : Outils/Macros/Gérer les scripts python ou au clavier Alt+Maj+F11 Dans la boite de dialogue Scripts python :
 * 1) Sélectionnez avec la souris la liste Mes macros
 * 2) Cliquez sur le bouton «Menu» et sélectionnez le menu Nouveau module APSONouveauModule.png
 * 3) Dans la boite de saisie Nom du module à créer saisissez mri APSONouvelleMacro.png
 * 4) Sélectionnez dans la liste Mes macros avec la souris le module mri nouvellement créé.
 * 5) Cliquez sur le bouton «Menu» et sélectionnez le menu Modifier APSOModifierMacro.png

Voici un code d'exemple d'utilisation

Sauvegardez le fichier et fermez votre éditeur.

Dans la fenêtre Scripts Python sélectionnez avec la souris le dossier mri puis la macro Mri_test et cliquez sur le bouton «Exécuter»

Explorateur de configuration
= Contexte = La passerelle Python-UNO s'exécute dans un contexte différent suivant comment le script python est exécuté.

C'est à dire que les environnements d'exécution sont distincts dans le cas du mode interactif, et encapsulé dans LibreOffice lors de l'exécution d'une macro par l'interface graphique.

= Scripts = Nous avons vu qu'il existait deux modes d'exécution des scripts Python. Nous allons voir ici comment récupérer les contextes dont nous avons besoin pour gérer des objets.

Mode interactif
Python communique avec LibreOffice en échangeant des appels de procédures distant RPC (Remote Procedure Call).

C'est pour cela qu'il nous faut toujours récupérer le contexte de composant correct pour indiquer à la fabrique de composants multiples d'instancier un service pour créer les objets au bon endroit.

Comme nous l'avons vu dans Python et le mode interactif avec LibreOffice, il nous faut initier le code Python minimal suivant pour récupérer le contexte de LibreOffice :

Gestionnaire de Services
En Python cette instance est la plus importante. Elle permet d'instancier les services et de travailler avec les API du bureau.

Les éléments de LibreOffice
Avec le contexte, nous pouvons récupérer l'environnement de bureau de LibreOffice :

Et enfin nous pouvons travailler sur le document actif :

>>> document.getIdentifier 'com.sun.star.text.TextDocument'

Macro exécutée depuis LibreOffice
Pour l'exécution d'une macro directement depuis LibreOffice, nous utilisons de contexte XSCRIPTCONTEXT avec le code suivant pour récupérer le contexte de LibreOffice :

Les éléments de LibreOffice
Avec XSCRIPTCONTEXT, nous pouvons récupérer l'environnement de bureau de LibreOffice :

Et enfin nous pouvons travailler sur le document actif :

= Composants = De façon générale, après pour obtenir le contexte d'un composant dans le dévelopement de vos scripts, il suffira d'utiliser «.getComponentContext».

comme :

= Instances =

Énumérations
LibreOffice dans ses API contient des constantes que vous pouvez utiliser à la place de nombres pour donner plus de sens à votre code lors de la lecture.

Ce sont les énumérations.

Ces énumérations sont accéssibles grace à la librairie PyUno

Il existe trois syntaxes possibles pour les récupérer : ou ou

Constantes
= Internationaliser ses macros python = Commencer à coder une macro en pensant à la partager c'est l'esprit du logiciel libre.

La recherche du partage est aussi utile pour corriger, améliorer et apprendre le langage python des macros LibreOffice.

C'est pour cela que plutôt on intègre l'internationnalisation dans son code, plus on a de chance d'être aidé et d'apprendre mieux par le partage le langage python des macros LibreOffice.

Génération du modèle de traduction
Sous linux :

Traduire le vocabulaire de la macro
ouvrir l'application Poedit



cliquez sur

Choisir le fichier /home/utilisateur/.config/libreoffice/4/user/Scripts/python/bonjour.py



La fenêtre de traductions s'affiche



Cliquez sur

Choisir la langue de traduction



Écrivez votre traduction



Génération de la traduction ou mise à jour de la traduction
Cliquez sur

Généré la traduction dans /home/utilisateur/.config/libreoffice/4/user/Scripts/python/locale/fr_FR/LC_MESSAGES



Cliquez sur

Changer de langue dans la macro
⇐ Introduction au développement en Python Identifier son système ⇒