Difference between revisions of "FR/Documentation/Python/Python as a macro language"

Latest revision as of 12:39, 9 April 2023

Pyuno prend en charge le cadre de script OpenOffice livré avec OpenOffice 4.1.3. Le support actuel est limité au cadre principal ( core framework ), ce qui signifie que l'exécution et l'affectation des macros via la boîte de dialogue standard Tools / Macro fonctionne correctement, mais l'édition et le débogage des macros ne sont pas intégrés dans l'interface utilisateur OpenOffice.org (Simplemenr en raison du manque de ressources pour le développement). Utilisez votre éditeur de texte favori pour créer et modifier des scripts python.

Emplacement des scripts

Les scripts à excuter dans OpenOffice.org peuvent être stockés dans les emplacements suivants:

Répertoire utilisateur de OpenOffice

C'est l'endroit standard pour les scripts personnels en python. Les fichiers de script sont simplement stockés dans le système de fichiers. L'emplacement du répertoire dépend de la version utilisée d'OpenOffice et du système d'exploitation. Certains exemples sont:

OpenOffice 2.x

• windows - C:\Documents and Settings\<current-user\>Application Data\OpenOffice.org 2.0\user\Scripts\python
• unix - ~/.openoffice.org.2.0/user/Scripts/python, ~/.openoffice.org.2.0/user/Scripts/python

OpenOffice 3.x

• windows 7 - C:\Users\<current-user>\AppData\Roaming\OpenOffice.org\3\user\Scripts\python
• unix - ~/.openoffice.org/3/user/Scripts/python

OpenOffice 4.x

• windows 7 - 11 C:\Users\<current-user>\AppData\Roaming\OpenOffice.org\4\user\Scripts\python
• Linux- ~/.openoffice.org/4/user/Scripts/python

Notez que le dernier sous-répertoire python peut avoir besoin d'être créé initialement. Assurez-vous que "python" est entièrement écrit en minuscules. Vous pouvez ajouter des sous-répertoires arbitrairement imbriqués, les noms de ces répertoires sont reflétés dans l'interface utilisateur.

Exemple: le ficher dynamicDialog.py peut simplement être placé dans le répertoire ci-dessus. Ensuite, ouvrez la boîte de dialogue Outils / Macros / Exécuter macro et naviguez jusqu'à la position affichée dans l'image ci-dessus. Cliquez sur Exécuter pour exécuter le script python, qui ouvre une autre boîte de dialogue avec un bouton poussoir et un champ d'étiquette. Cliquez sur le bouton pour augmenter le nombre dans le champ de l'étiquette. La boîte de dialogue peut être fermée en appuyant sur ESC.

Dossier partagé de OpenOffice

Les scripts qui seront partagés entre tous les utilisateurs d'une installation concrète d'OpenOffice.org peuvent être stockés dans ce répertoire de partage. Tous les scripts par défaut venant avec OpenOffice.org sont situés ici. En général, ce répertoire ne doit pas être utilisé pour le déploiement de scripts (voir plus loin les uno-packages). Les fichiers de script sont simplement stockés dans le système de fichiers. L'emplacement du répertoire (comme les répertoires d'utilisateurs) dépend de la version d'OpenOffice.org utilisée et du système d'exploitation. Quelques exemples :

OpenOffice 2.x

• windows C:\Program Files\OpenOffice.org 2.0\share\Scripts\python
• unix /usr/lib/openoffice/share/Scripts/python

OpenOffice 3.x

• windows 7/32Bit C:\Program Files (x86)\OpenOffice.org 3\Basis\share\Scripts\python'
• ubuntu 10.04 /usr/lib/openoffice/basis3.2/share/Scripts/python

OpenOffice 4.x

• windows 7-11/64Bit C:\Program Files (x86)\OpenOffice.org 4\share\Scripts\python'
• ubuntu 22.04 /opt/openoffice4/share/Scripts/python/

Inclus dans un document OpenOffice

Un document OpenOffice.org est un fichier zip, qui contient différents fichiers. Les scripts Python dans les documents sont stockés dans le sous-répertoire Scripts / python.

Si vous souhaitez expédier vos scripts personnels en python dans un document, vous devez d'abord développer vos scripts dans le répertoire utilisateur (mentionné ci-dessus), puis enfin déplacer les scripts dans le document avec votre outil préféré zip. Toutefois, notez que vous devez réaffecter toutes les liaisons que vous avez déjà effectuées aux instances de script dans le document. Idéalement, vous écartez les scripts du répertoire utilisateur et effectuez un test de régression sur la fonctionnalité du document. Vous pouvez aussi utiliser l'extension An Other Script Organizer.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
 <manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
 <manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
 <manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/push_me.py"/>
 <manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
 <manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>
 </manifest:manifest>

Lorsque vous ouvrez le document par la suite, l'interface utilisateur de OpenOffice devrait vous avertir du script contenu dans le document (si ce n'est pas le cas, vous avez désactivé l'avertissement dans les options ou vous avez fait quelque chose de pas bien....).

Exemple: Pour voir comment cela fonctionne, téléchargez File:Push me python4.odt. Le document contient un bouton poussoir et un contrôle d'édition multi lignes. Une pression sur le bouton ajoute une nouvelle ligne avec l'horodatage actuel au contrôle d'édition multi-lignes. Ce fichier ne fonctionne que s'il est enregistré...

Incorporé dans un un package, dans le répertoire utilisateur d'OpenOffice (lecture seule)

Souvent, distribuer des scripts dans des documents n'est pas ce que vous voulez (par exemple lorsque vous souhaitez modifier l'application elle-même ou que vous souhaitez utiliser les mêmes scripts avec plusieurs documents). Pour cela, vous pouvez placer vos scripts simplement dans un package uno.

Un package est un fichier zip. Son nom doit se terminer par .pkg (sinon il ne fonctionne pas), Vous devez définir le sous-répertoire (obligatoire!) qui contiendra des scripts. Par exemple, l'exemple pyhello2.uno.pkg possède la structure de fichier suivante::

META-INF/
META-INF/manifest.xml
package/
package/hallo.py

Le fichier hallo.py contient les scripts. Comment écrire des scripts est expliqué ci-dessous. Toutefois, afin de rendre opérationnel un script dans un package uno, vous devez ajouter un code fictif.

# ... Voici le code de script python
 
# Ceci doit être ajouté à chaque fichier de script (le
# nom org.openoffice.script.DummyImplementationForPythonScripts doit être changé en quelque chose
# de différent (doit être unique dans une installation de bureau!)
# --- composant factice, dummy pour permettre l'enregistrement avec unopkg, aucune fonctionnalité attendue
import unohelper
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation( \
	None,"org.openoffice.script.DummyImplementationForPythonScripts", \
    ("org.openoffice.script.DummyServiceForPythonScripts",),)

Par défaut, chaque fichier .py est interprété comme un composant UNO. Ne pas placer les lignes ci-dessus dans le fichier .py provoquerait des erreurs lors du déploiement.

Le nom du répertoire (ici le paquet) peut être choisi librement. Un package uno avec un script python doit contenir un META-INF / manifest.xml, qui doit pointer vers le nom du répertoire librement choisi.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="package"/>
</manifest:manifest>

Chaque utilisateur peut ajouter des paquets via le gestionnaire de paquetages (Outils/ Gestionnaire des extensions). Notez que le contenu du package est conçu en lecture seule, c'est vraiment un déploiement pur, pas un mécanisme de développement. C'est peut-être la raison pour laquelle les scripts dans les packages ne peuvent pas être consultés via la boîte de dialogue Outils / Macros / Organiser les macros / Python. Les packages peuvent être ajoutés par un administrateur à une installation complète de OpenOffice.org, de sorte que chaque utilisateur puisse utiliser les macros situées dans le package. Cela peut être fait avec l'outil unopkg.

Script coding

Un script python dans la structure de script OpenOffice.org est une fonction (introduite par le mot-clé def) dans un fichier .py. Pour l'exécution via la boîte de dialogue Outils / Macros / Exécuter macro , le script doit avoir une liste d'arguments vide. Pour les Listeners d'événements typiques, la fonction doit avoir exactement un argument (l'événement). En général, le nombre d'arguments dépend du contexte dans lequel la fonction doit être utilisée. Actuellement, le fichier .py doit utiliser des flux de ligne unix, ce qui sera modifié à l'avenir. Le mieux est d'implanter une liste d'arguments variables (*args), qui convient à toutes les situations.

Un fichier .py simple peut contenir un nombre arbitraire de définitions de fonction. Par défaut, toutes les définitions de fonctions sont exportées (= affiché dans la boîte de dialogue de sélection des macros). Comme cela peut devenir fastidieux, les exportations peuvent être limitées à un plus petit ensemble de fonctions en ayant une variable globale nommée g_exportedScripts, qui est un tuple de définitions de fonction.

Au niveau d'intégration actuel, les fichiers .py ne peuvent importer que des modules python qui se trouvent dans le PYTHONPATH python. Par défaut, ce n'est que le runtime python avec ses bibliothèques standard et les fichiers passerelle uno. Cela signifie que les macros python ne peuvent pas référencer d'autres fichiers de macro python. Cette limitation peut être modifiée à l'avenir mais existe actuellement. Les macros Python peuvent, bien sûr, importer à partir de n'importe quel module que vous placez dans PYTHONPATH; Mais vous devez le faire vous-même et les résultats ne seront pas portables (Un lecteur se demande: le pythonloader ne pouvait pas ajouter automatiquement les scripts OOo à PYTHONPATH?)

Avant d'exécuter le code source dans le module, la variable globale XSCRIPTCONTEXT est insérée comme variable globale dans le module (cette variable existe également pour javascript et beanshell, elle est proposée ici pour des raisons de cohérence). Elle a trois membres (Document, Desktop et ComponentContext).

Le commentaire d'une fonction (introduit et terminé par trois ") est présenté comme une description dans la boîte de dialogue de sélection des macros.

Les fichiers de script python compilés ne sont pas ajoutés à sys.modules. Il peut exister plusieurs instances du même module en même temps Exemple:

 
# Hello World script python pour le cadre de script
 
def HelloWorldPython( ):
    """Ecrit la chaîne 'Hello World (en Python)' dans le document actuel"""
    # Obtient le document à partir du contexte de script qui est mis à la disposition de tous les scripts
    model = XSCRIPTCONTEXT.getDocument()
    text = model.Text
    cursor = text.createTextCursor()
    text.insertString( cursor, "Hello World(en Python)", 0 )

Gestion des erreurs et débogage

Les erreurs lors de la compilation ou de l'exécution des scripts sont transmises en tant qu'exceptions au cadre de script lorsque cela est possible. Le cadre de script en général ouvre une boîte contextuelle et affiche le message de l'exception projetée.

Cependant, parfois cela n'est pas possible et une erreur est ignorée. L'utilisateur réalise ces erreurs, lorsque

• Son fichier script python n'apparaît pas là où il devrait être
• Le nom du fichier de script apparaît, mais il ne contient aucun script
• Seule une partie du script est exécutée

Vous pouvez connaître ces problèmes en modifiant certains drapeaux dans le fichier OpenOffice.org 4/program/pythonscript.py:

# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE                # Utilisez alternativement LogLevel.ERROR ou LogLevel.DEBUG
LOG_STDOUT = False                          # True, écrit sur stdout
                                            # False, écrit dans user/Scripts/python/log.txt
ENABLE_EDIT_DIALOG=False                    # Offre un éditeur minimal pour l'édition.

La connexion d'un débogueur python n'est actuellement pas prise en charge.

Credits

La liaison python du cadre de script est développée et maintenue par Joerg Budischewski dans son temps libre. Beaucoup, beaucoup de mercis à Tomas O'Connor de Sun pour son grand appui et ses ajouts de code au cadre qui a rendu cette liaison possible. Veuillez poser des questions de bas niveau sur la liaison à api@openoffice.apache.org.