Macros/Python Design Guide/fr

From The Document Foundation Wiki
Jump to: navigation, search
Conception et Développement d'Applications Python

Introduction

Cette page est destinée aux programmeurs de macros Python qui désirent concevoir des projets LibreOffice complexes et/ou collaboratifs. Elle concerne les utilisateurs débutants ou bien expérimentés. Une initiation à la programmation Python sous LibreOffice permet la découverte rapide du Python au sein de LibreOffice.

Les volontaires au projet LibreOffice peuvent se reporter à ce Wiki.

Une exposition raisonnable au langage Python ainsi qu'une certaine familiarité avec la suite LibreOfice sont bienvenues avant de poursuivre la lecture. Les exemples Python figurant ici sont incomplets et les usages de LibreOffice brièvement décrits.

Documentation

Python - Apache OpenOffice (en anglais)

Bibliographie

Modélisation UML

De nombreuses solutions de modélisation existent. Voici une liste arbitraire des outils gratuits, libres, multi-plate-formes ou multi-lingues.

  • ArgoUML : ArgoUML Développé en Java, il est disponible en dix langues (anglais, français, allemand, italien, portugais, espagnol, russe, norvégien et chinois).
  • StarUML : StarUML est proposé pour OS X 10.6+, Windows XP+ et Ubuntu (64/32-bit). StarUML compte de nombreuses fonctions mais exige la maîtrise de l'anglais.
  • Umbrello : Umbrello est multi-lingue et accompagne les distributions GNU/Linux, Windows (64 or 32-bit) et Mac OS X.

Une liste exhaustive d'outils pour (Unified Modeling Language (UML) est disponible depuis Wikipedia.
StarOffice Programmer's Tutorial décrit en anglais les documents LibreOffice à l'aide de diagrammes UML.

Préambule

Windows - Bibliothèques de scripts Python

L'environnement de développement intégré (EDI), présent dans LibreOffice, permet l'écriture, la mise au point et la gestion des macros en language Basic seulement. L'usage d'un EDI pour le développement de macros Python requiert un effort de configuration. En retour le développeur dispose d'un outil de développement à sa mesure ou adapté à ses besoins. Les recommandations ci-après s'adressent aux débutants comme aux utilisateurs expérimentés.

La gestion de bibliothèques et de macros disponible pour le Basic, n'existe pas pour le Python. Cependant gérer les modules et fonctions du langage Python est tout à fait possible. Les packages Python ne correspondent pas exactement aux extensions LibreOffice ou aux packages UNO. Cette page utilise indifféremment le terme module pour bibliothèque et fonctions pour macros. La terminologie Python peut y être privilégiée pour accoutumer les familiers au Python.

Il existe trois types de scripts Python, ceux propres à l'utilisateur, ceux qui sont partagés par tous ou bien ceux contenus dans les documents. Il sont présents en divers endroits selon leur type et selon la plate-forme utilisée. Pour gérer les scripts il est possible de recourir aux bibliothèques de Windows ou bien aux raccourcis sous Gnu/Linux. Cela permet de les organiser par simple glisser-lâcher. La définition de ces bibliothèques ou de ces raccourcis se fait en consultant Débuter avec OpenOffice ou LibreOffice.

Les projets Python peuvent se grouper par EDI au sein d'une bibliothèque comme illustré.

Outils - Macros - Gérer les scripts python

Une extension intitulée Alternative Python Script Organizer apporte une remarquable assistance à la gestion des scripts. Une fois installée et LibreOffice redémarré, apparaît un menu Outils - Macros - Gérer les scripts python. Les dépôts "Mes macros", "Macros LibreOffice" et "Nom du Document" distinguent les types de script.

De multiples actions facilitent la gestion des scripts Python. Le bouton Exécuter lance la macro sélectionnée. Les actions du bouton Menu dépendent de l'élément actif :

Gestion des scripts Python
  • Nouvelle macro ou bibliothèque en sélectionnant les dépôts "Mes macros" ou "Macros LibreOffice"
  • Modifier, Renommer ou Supprimer une macro ou bibliothèque
  • Copier une macro vers un document depuis les dépôts "Mes macros" ou "Macros LibreOffice"
  • Remplacer une bibliothèque d'un document par un module Python
  • Exporter une bibliothèque d'un document vers un module Python

Le chapitre "Mise au Point" détaille d'autres aspects liés à l'organisation des modules et des packages Python.

La page Script LibreOffice détaille comment assigner des scripts personnalisés (ou macros) à des entrées de menu, des icônes, des contrôles de boîte de dialogue et des événements dans LibreOffice.

Développement

De nombreux logiciels ont recours au Python soit nativement soit spécifiquement. LibreOffice incorpore son propre interpréteur Python, lequel permet l'usage des API au travers d'Universal Network Objects (UNO). Le langage Python propose nativement un interpréteur utilisable parallèlement à celui de LibreOffice. Tous deux partagent une base commune et sont extensibles, ainsi certaines de leurs fonctions se recoupent, mais pas toutes. Le Python natif n'inclut pas l'interface UNO à l'API de LibreOffice et il n'offre pas la possibilité de les reconnaître. Réciproquement l'interpréteur de LibreOffice ne se comporte pas totalement comme le Python natif, ainsi n'étend il pas ses fonctionnalités de la même façon. Cependant ni LibreOffice ni le Python natif ne facilitent le développement d'applications en Python pour Writer, Calc, Impress, Draw, Base ou Math.

LibreOffice est disponible en versions 32bits ou 64bits. L'environnement de développement intégré (EDI) qui peut lui être associé s'exécute dans le même contexte que la suite bureautique, soit tous deux en 32bits soit tous deux en 64bits. Il existe de nombreux EDIs pour Python, des plus basiques (quoique) comme IDLE aux plus élaborés comme PyCharm ou Pydev pour Eclipse. La liste qui suit est arbitraire, elle se focalise sur quelques outils libres gratuits, inter-opérables et si possible multi-lingues. La rubrique mise au point (débogage) est détaillée ci-après avec PyCharm à titre d'exemple. Le site Python.org répertorie une liste, en anglais, d'EDIs pour le langage Python. Un comparatif (en anglais) des Environnements de Développement Intégrés (EDI) par langage de programmation existe sur Wikipedia.

  • Integrated Development and Learning Environment (IDLE) supporte 32bits ou 64bits, est disponible sur un grand nombre de plate-formes, ne parle qu'anglais. C'est l'outil de référence pour s'initier au langage Python.
  • Geany fonctionne en 32bits et parle 43 langues différentes. Il tourne sur GNU/Linux, *BSD, MacOS X, AIX v5.3, Solaris Express et Windows. Geany est léger, convient aux petits projets, et peut lancer l'interpréteur Python de LibreOffice.
  • Aptana semble supporter le débogage, cf. ce sujet (en anglais).
  • PyCharm (dans sa version gratuite) supporte les plates-formes Gnu/Linux, Mas OS X et Windows. Disponible en 32bits, il semble s'accommoder du 64bits également. PyCharm intègre un puissant débogueur compatible avec LibreOffice, de nombreuses autres fonctionnalités accompagnent la mise au point avec cet outil, cependant il exige de maîtriser l'anglais.

Voici une liste incomplète de possibilités offertes par ces IDEs, parfois sans équivalent dans l'IDE Basic propre à LibreOffice.

Explorateur de Classe, Coloration Syntaxique

IDLE, Geany et PyCharm facilitent l'édition de scripts Python à l'aide de la navigation dans le code et de la coloration syntaxique. Geany et PyCharm supportent aussi pliage et dépliage de code. Le navigateur de scripts d'IDLE ne supporte pas les classes internes ou imbriquées.

Complétion de Code

IDLE, comme Geany et PyCharm proposent une assistante à l'écriture de script appelée complétion de code.


Conventions de Codage (PEP)

Développement Orienté Test (TDD)

Tests unitaires

Gestion des Versions

PyCharm dispose d'un historique local des modifications de code source comme dans cet exemple :

Historique des modifications de code source

Le programme Python apso.py y est affiché dans deux versions, labellisées v0.8.3 et v0.8.7. Un affichage différencié des copies identifie précisément les corrections apportées.

Pycharm permet l'intégration d'autres solutions de gestion des versions telles que Git, GitHub, Mercurial, Perforce ou Subversion.

Mise au Point

Depuis LibreOffice

Xray - Méthodes d'un objet texte Writer
MRI - Propriétés, méthodes, service et interface d'un document Writer
Object Inspector - Propriétés, méthodes, services supportés et interfaces exportées de 'StarDesktop'

L'édition et la mise au point de macros en Python est possible directement depuis LibreOffice à l'aide de l'extension Alternative Python Script Organizer. Celle-ci permet de gérer bibliothèques et modules, de travailler avec l'éditeur de son choix, et d'exécuter les macros sans quitter LibreOffice.

Travailler hors LibreOffice est également possible, le débogage devient alors réalisable. Développer hors LibreOffice à l'aide d'un environnement de développement intégré (EDI) offre bien d'autres avantages détaillés ci-après.

Voici trois extensions pour développeur, vite nécessaires sinon incontournables dans ces deux contextes. Elles sont utilisables que l'on code en LibreOffice Basic, en Python, en JavaScript ou en BeanShell. Toutes trois s'appuient sur la faculté d'introspection des API de la suite LibreOffice.

Extensions utiles

Identifier les services supportés par un objet au moment de la conception est délicat. Il existe des extensions qui aident le développeur à inspecter les objets UNO. Elles sont absentes du catalogue des extensions, à l'exception de MRI, elles reposent sur la réflexion qui est intrinsèque aux API de LibreOffice.

  • X-Ray inspecte les objets API de LibreOffice. X-Ray affiche les propriétés, les méthodes, les services et les interfaces supportés par un objet. Il est disponible en français, allemand, anglais, espagnol, polonais, russe et tchèque. X-Ray est écrit en Basic.
  • MRI (My Reflection and Introspection) est un outil d'introspection pour objets UNO, écrit en Python. Ces fonctions sont similaires à celles d'X-Ray. Il est disponible en anglais. La version MRI au sein du catalogue des extensions de LibreOffice est périmée.
  • Object Inspector L'extension Object Inspector affiche les caractéristiques des objets telles que les services supportés, les interfaces exportées, ainsi que les méthodes et les propriétés sous la forme d'une arborescence. Object Inspector est écrit en Java et est disponible en anglais seulement.

Usage des macros Python

Avec LibreOffice les macros Python peuvent être présentes en de nombreux endroits et sous de nombreuses formes comme l'explique Python comme langage de macro. Les scripts sont soit personnels, soit partagés, soit présents dans une extension, soit intégrés dans un package (ou paquetage en français), soit intégrés dans un document. De chacun de ces dépôts découlent différents usages ou contraintes.

  • Dans un document chaque module Python est autonome, pas d'import entre modules.
  • Un module Python peut appeler depuis un document une extension en Basic ou en Python.
  • Les modules Python de <utilisateur>\python\pythonpath sont importables depuis un document ou depuis <utilisateur>\python
  • Le Basic n'est pas supporté depuis un EDI: Pas de X-Ray (sic).
  • Python et Java fonctionnent depuis un EDI: MRI, Object Inspector sont utilisables.

Voici comment utiliser Mri dans une macro Python:

import uno
def mri(target):
    ctx = uno.getComponentContext()
    mri = ctx.ServiceManager.createInstanceWithContext(
        "mytools.Mri",ctx)
    mri.inspect(target)
    
if __name__ == '__main__':
    def Mri_test():
        document = XSCRIPTCONTEXT.getDocument()
        mri(document)
 
    Mri_test()

Stopper l'exécution d'une macro avec X-Ray :

import uno
from com.sun.star.uno import RuntimeException as _rtex

def xray(myObject):
  try:
    sm = uno.getComponentContext().ServiceManager
    mspf = sm.createInstanceWithContext("com.sun.star.script.provider.MasterScriptProviderFactory", uno.getComponentContext())
    scriptPro = mspf.createScriptProvider("")
    xScript = scriptPro.getScript("vnd.sun.star.script:XrayTool._Main.Xray?language=Basic&location=application")
    xScript.invoke((myObject,), (), ())
    return
  except:
     raise _rtex("\nBasic library Xray is not installed", uno.getComponentContext())

# ___________  example of use  _______________ 

def demoXray(): 
  """ example : using xray in a Writer document """ 
  
  xTextDoc = XSCRIPTCONTEXT.getDocument() 
  xText = xTextDoc.Text 
  xray(xText)
  xray("Demo is finished") 

g_exportedScripts = demoXray,

Affichage de l'arborescence d'objets UNO avec Object Inspector :

import uno
def inspectObject( obj, title="Object Inspector" ):
        ctx = uno.getComponentContext()
        oi = ctx.ServiceManager.createInstanceWithContext("org.openoffice.InstanceInspector", ctx)
        if oi is None:  # i.e. InstanceInspector is not installed or deactivated
                return  # exit silently
        oi.inspect( obj, title )
def exObjInspector():
        doc = XSCRIPTCONTEXT.getDocument()
        dsk = XSCRIPTCONTEXT.getDesktop()
        inspectObject(doc)
        inspectObject(dsk, title="StarDesktop")

Depuis un EDI via l'interpréteur Python de LibreOffice

Développer des macros en Python depuis un EDI est possible en utilisant l'interpréteur de LibreOffice. IDLE qui accompagne le Python natif exécute son propre interpréteur, qui n'est pas compatible avec LibreOffice. Le recours à un EDI ouvre toute une gamme de nouvelles possibilités au développeur telles que la navigation dans le source, la coloration syntaxique, la complétion de code, le respect des conventions de codage, le développement orienté tests, le débogage, la gestion de version, et bien plus encore.
A titre d'exemple uniquement, voici comment indiquer l'interpréteur Python de LibreOffice au sein de Geany ou de PyCharm.

Une communication doit être établie entre l'EDI et LibreOffice afin d'exécuter un script depuis <utilisateur>\python ou <utilisateur>\python\pythonpath. Sans une passerelle les objets UNO sont inaccessibles. Une fois la communication activée, EDI et LibreOffice opèrent ensemble. Les liens qui suivent documentent ce processus :

Usage des Scripts Python

  • ...appel de packages Python...

Exécution externe avec Geany

Une fenêtre s'affiche dans LibreOffice depuis Geany dans la figure ci-dessous. L'EDI Geany lance la fonction info() laquelle utilise l'API .awt.createMessageBox() du SDK. Le script utilisateur s'appelle SysInfo.py.

Geany lance la fonction info() qui utilise l'API ..awt.createMessageBox() du SDK - Script <user>\SysInfo.py


Débogage avec PyCharm

Voici le débogueur de PyCharm affichant le contenu d'objets UNO, de classes et objets Python :

Débogage d'objets UNO, de classes et variable Python

Gestion des Exceptions (brouillon)

Utilisation des Dialogues ( brouillon )

Voici un liste de qq. références pour démarrer :

Conception de Dialogues

Programmation évènementielle


Ecriture d'Extensions ( brouillon )

Voici un liste de qq. références pour démarrer :


Construire un service

Bibliothèque de fonctions dans un document

cf. Bibliothèque de fonctions dans un document, Hubert Lambert, Nov-2016

Construire un Add-In

Construire une extension

Paquétage Python vs. Extension LibreOffice

Il est courant en Python de définir des modules, ou packages, comme suit :

  • __init__.py expose les classes A, B, et D dont les variations sont respectivement présentes en dir1/, dir2/ et d.py
  • dir1/
    • __init__.py
    • a'.py expose la classe A'
    • a".py expose la classe A" dérivée de A'
  • dir2/
    • __init__.py
    • b1.py expose la classe B1
    • b2.py expose la classe B2
    • b3.py expose la classe B3
  • c.py utilise A
  • d.dy expose la classe D

Une telle organisation n'est pas supportée dans une extension LibreOffice. Elle doit être réorganisée, aux dépens d'une maintenance aisée du code, comme suit :

  • (a'+a"+b).py

Ainsi :

  • L'import relatif n'est pas supporté dans les extensions Python:
    • from .a' import A' ne fonctionne pas.
    • from . import A ne fonctionne pas.

Propriétés et méthodes statiques

Quid du global de Python ?

Synchroniser avec PyCharm & Git (brouillon)