Makros/Python-Design-Leitfaden

    From The Document Foundation Wiki
    This page is a translated version of the page Macros/Python Design Guide and the translation is 100% complete.

    Einführung

    Diese Seite ist gedacht für Python-Makro-Entwickler, die LibreOffice-Anwendungen entwickeln oder mit diesen zusammenarbeiten wollen. Anfänger bis zu erfahrenen Python-Programmierer können von den Entwicklungsrichtlinien dieser Seite profitieren. Ein Zugang zu Python in LibreOffice ist verfügbar in dem Python-Entwickler-Leitfaden.

    Bewerber für das LibreOffice-Projekt können entsprechend dieses Wikis handeln, um dabei zu sein.

    Diese Seite geht davon aus, dass Sie angemessenen Kontakt zu Python haben wie auch einige Vertrautheit mit der LibreOffice Anwendungssuite. Sie enthält einige Python-Code-Beispiele wie auch den Gebrauch von LibreOffice-Extensions, der kurz beschrieben wird.

    Dokumentation

    Online-Kurse oder -Leitfäden

    e-Literaturliste

    Unified Modeling Language (UML)

    Zahlreiche UML-getriebene Werkzeuge sind verfügbar. Hier ist eine beliebige Liste, die sich auf freie Open Source vollständig kompatible Anwendungen konzentriert, deren angebotene Sprachen erwähnend.

    • ArgoUML : ArgoUML läuft auf jeder Java-Plattform und ist in zehn Sprachen verfügbar (Amerikanisches Englisch, Britisches Englisch, Französisch, Deutsch, Italienisch, Portugiesisch, Spanisch, Russisch, Norwegisches Bokmål und Chinesisch).
    • StarUML : StarUML wird vorgeschlagen für macOS 10.6+, Windows XP+ und Ubuntu (64 or 32-bit). StarUML hat eine umfangreiche Funktionsliste und ist nur in Englisch verfügbar.
    • Umbrello : Mehrsprachig Umbrello kommt mit GNU/Linux-Distributionen, Windows (64 oder 32-bit) und macOS.

    Eine umfangreiche Liste von (Unified Modeling Language (UML) Werkzeugen ist verfügbar auf Wikipedia (nur Englisch verfügbar).

    StarOffice Programmer's Tutorial erläutert genau LibreOffice-Dokumente mit Hilfe von UML-Diagrammen.

    Software Design Patterns (Software-Designmuster) werden in Wikipedia beschrieben, manchmal flankiert mit Python-Beispielen.

    Präambel

    Bewerkstelligen von Python-Skripten mit Bibliotheken

    Für die Entwicklung von Makros in der Sprache Basic gibt es in LibreOffice eine Integrierte Entwicklungsumgebung (IDE), die es ermöglicht, Basic-Makros zu bearbeiten, debuggen und desgleichen. Das Schreiben von Python-Makros erfordert zusätzliche Konfigurationsschritte, um die IDE Ihrer Wahl einzurichten. Im Gegenzug werden Sie mit einer flexiblen Designerfahrung ausgerüstet, erstellt nach Ihren Python-Entwicklungs-Vorlieben oder -Gewohnheiten. Nachstehend werden IDE-Einrichtungs-Leitlinien beschrieben, die von Anfänger bis fortgeschrittener Benutzer reichen.

    Die Behandlung von Bibliotheken und Makros entsprechend derjenigen in Basic ist für Python nicht verfügbar. Allerdings ist die Verwaltung von traditionellen Python-Funktionen und -Modulen durchaus möglich, während das Bauen von Python-Paketen sich irgendwie teilweise zum Erstellen von LibreOffice-Erweiterungen oder UNO-Paketen verschiebt. Diese Seite verwendet synonym Modul für Bibliotheken und Funktionen für Makros. Die Terminologie von Python wird eventuell bevorzugt zwecks besserer Anpassung an Pythons kulturellen Sprachgebrauch.

    LibreOffice-Skripte kommen in drei unterschiedlichen Varianten vor. Sie können persönlich, geteilt oder eingebettet in Dokumente sein. Abhängig von ihrem Typ und abhängig von der Plattform enden sie gespeichert an unterschiedlichen Orten, die detailliert in dem AOO-Wiki-Artikel Python als Makro-Sprache beschrieben sind.

    Um Python-Skripte zu verwalten, kann man entweder auf Windows-Bibliotheken verwenden oder auf GNU/Linux Dateimanager-Verknüpfungen zurückgreifen. Somit können .py-Dateien mit einfachem Drag & Drop organisiert werden. Eine Beschreibung der Speicherorte von Ordnern entsprechend Ihrer Systemumgebung, um Ihnen beim Einrichten Ihrer Bibliotheken oder Dateimanager-Verknüpfungen zu helfen, kann im AOO-Wiki-Artikel Python als eine Makro-Sprache gefunden werden.

    Python-Projekte können wie abgebildet per IDE in einer subsequenten Windows-Bibliothek angeordnet werden.

    Alternative Python Script Organizer Menü

    Die unentbehrliche Alternative Python Script Organizer Erweiterung bringt das Python-Skript-Management in Schwung. Sie bekommen durch ihre Installation bessere Python-Skript-Integration in LibreOffice. Sobald LibreOffice neu gestartet ist, schauen Sie im Extras-Menü nach dem Makros - Pythen-Skripten verwalten Menüeintrag.

    Die Erweiterung bietet verschiedene Aktionen um Python-Skripte zu verwalten. Die Ausführen Schaltfläche führt das ausgewählte Makro aus. Die über die Menu Schaltfläche verfügbaren Aktionen hängen vom auswählten Element ab:

    Alternative Python Script Organizer Dialog
    • Erstellen Sie ein Makro oder eine Bibliothek, wann immer Sie einen persönlichen, einen geteilten oder einen Dokument-Container auswählen
    • Bearbeiten, Umbenennen, Löschen eines Makros oder einer Bibliothek
    • Binden Sie ein Makro in ein Dokument ein von einem persönlichen oder geteilten Container
    • Tauschen Sie eine in ein Dokument eingebettete Bibliothek mit einem Platform-Python-Modul
    • Exportieren Sie eine in ein Dokument eingebettete Bibliothek als ein Python-Modul
    • Debuggen Sie ein ausgewähltes Makro
    • Führen Sie die Python-Interaktive-Konsole aus, auch bekannt als Python-Interpreter

    Andere Informationen in Bezug auf Skript-Organisation und Python-Pakete können Sie in Debuggen finden.

    Skripte in LibreOffice zuweisen beschreibt ausführlich, wie Sie Skripte in der LibreOffice-Anwendungs-Suite verwenden.

    Entwicklung

    Zahlreiche Anwendungen verwenden Python, entweder nativ oder speziell. LiberOfice bindet seinen eigenen Python-Interpreter ein, der es ermöglicht, die API durch Universal Network Objects (UNO) zu verwenden. Die Python-Programmiersprache verfügt über ihren eigenen Interpreter, der parallel zu dem von LibreOffice verwendet werden kann. Beide teilen eine gemeinsame Basis und sind erweiterbar. Daher stellen sie sowohl identische als auch unterschiedliche Funktionen bereit. Natives Python enthält nicht das UNO-Interface zum LibreOffice API. Umgekehrt verhält sich LibreOffice nicht vollständig wie natives Python und erweitert seine Funktionalitäten nicht in der gleichen Weise wie natives Python. Allerdings ermöglichen weder LibreOffice noch natives Python die Anwendungsentwicklung mit der Python-Programmiersprache für Writer, Calc, Impress, Draw, Base oder Math.

    LibreOffice existiert in 32- oder 64-bit-Versionen. Die Integrierte Entwicklungsumgebung (IDE), die es flankiert, erfordert, dass sie in demselben Kontext ausführt, in 32- oder 64-bit. Es existieren zahlreiche IDEs von den einfachsten, wie IDLE, wenn auch umstritten, zu ausgefeilteren wie PyCharm oder PyDev für Eclipse. Die folgende Liste konzentriert sich willkürlich auf Werkzeuge, die frei, Open Source, plattformübergreifend und eventuell mehrsprachig sind. Das Debugging-Kapitel unten verwendet Pyzo und PyCharm allein zur Veranschaulichung. Eine Liste von IDEs für Python ist auf der Seite Python.org verfügbar. Ein Vergleich von Integrierten Entwicklungsumgebungen (IDE) ist für zahlreiche Sprachen auf Wikipedia verfügbar.

    • Integrated Development and Learning Environment (IDLE) unterstützt 32- und 64-bit. Es ist für viele Plattformen verfügbar. IDLE ist das empfohlene Werkzeug, um Python zu lernen.
    • Geany funktioniert in in 32- oder 64-bit und ist in 43 verschiedenen Sprachen verfügbar. Es läuft auf GNU/Linux, *BSD, macOS, AIX v5.3, Solaris Express und Windows. Geany ist leicht, passt zu kleinen Projekten und unterstützt den LibreOffice-Python-Interpreter.
    • Liclipse
    • Debuggen mit Aptana scheint möglich vgl. dieser Thread
    • PyCharm (freie Edition) unterstützt die Plattformen Gnu/Linux, macOS und Windows. Es ist als 32bit erhältlich und passt sich offensichtlich auch 64bit an. Nebst zahlreichen Funktionen, die die Python-Entwicklung flankieren, enthält PyCharm einen Python-Debugger, der mit LibreOffice kompatibel ist.
    • Pyzo ist verfügbar für Linux, OS X und Windows in 10 verschiedenen Sprachen. Mehrere Python-Interpreter können konfiguriert werden, seien sie 32bit oder 64bit. Pyzo bietet Debugging-Funktionen.

    Hier ist eine Liste von Funktionen, verfügbar von diesen IDEs. Die LibreOffice-Basic-IDE bietet nicht einige von ihnen.

    Quelltext-Erkunder, Syntaxhervorhebung

    Quelltext-Erkundung und Syntaxhervorhebung in IDLE, Geany and PyCharm erleichtern die Skript-Bearbeitung. Geany und PyCharm unterstützen Code-Faltung. IDLE-Klassen-Navigator unterstützt nicht innere oder eingebettete Klassen.

    Code-Vervollständigung

    Die Codevervollständigung unterstützt das Bearbeiten von Python-Skripten in IDLE, Geany und PyCharm.

    Debuggen

    Das Debugging-Kapitel unten geht zu diesem Thema mehr in Einzelheiten.

    Kodierungsrichtlinien (PEP)

    Die PyCharm-IDE zeigt eine Komformitäts-Prüfung zu Python Enhancement Proposal (PEP) an.

    PyCharm-Kodierungs-Konventions-Assistent

    Python-Kodierungs-Konventionen und -Empfehlungen sind ganz rechts im Editor verfügbar. Dies kommt besonders gelegen für unerfahrene Programmierer.

    Test-getriebene Entwicklung (Test-Driven Development) (TDD) - Entwurf

    </Unit-Testen>

    Versionskontrolle

    Eine lokale Historie des Quellcodes kommt mit PyCharm wie unten gezeigt:

    Quellcode aktualisiert die lokale Historie

    Zwei Kopien des Python-Modul apso.py werden gemeinsam angezeigt und entsprechend beschriftet mit v0.8.3 und v0.8.7. Versionsunterschiede werden genau hervorgehoben.

    PyCharm unterstützt andere other Versionskontroll-Lösungen(version control solutions) (VCS) wie Git, GitHub, Mercurial, Perforce oder Subversion.

    Debuggen

    In LibreOffice

    Xray - Methoden eines Writer-Text-Objekts
    MRI - Eigenschaften, Methoden, Dienste und Interfaces für ein Writer-Dokument
    Objekt-Inspektor - 'StarDesktop'-Eigenschaften, -Methoden, unterstützte Dienste und exportierte Interfaces

    Man kann Python-Makros direkt in LibreOffice mit Hilfe der Erweiterung Alternative Python Script Organizer bearbeiten und debuggen. Verwalten von Bibliotheken und Modulen ist möglich, wie auch das Auswählen Ihres bevorzugten Editors ohne LibreOffice zu verlassen.

    Entwickeln außerhalb von LibreOffice ist genauso machbar, somit wird Debuggen möglich. Remote-Kodieren und -Testen unter Verwenden einer Integrierten Entwicklungsumgebung (IDE) bringt weitere Funktionen, die im Folgenden beschrieben werden.

    Hier sind drei Erweiterungen, von denen Programmierer in diesen beiden Zusammenhängen profitieren können. Sie können verwendet werden ungeachtet der Programmiersprache, sei es LibreOffice Basic, Python, JavaScript oder BeanShell. Alle drei erweitern die API's Introspektion der LibreOffice-Suite.

    Nützliche Erweiterungen

    Es ist nicht stets klar zum Entwurfszeitpunkt, welche Dienste ein UNO-Objekt aktuell unterstützt. Allerdings existieren Erweiterungen, die Entwicklern helfen, beliebige UNO-Objekte zu inspizieren, jedoch werden diese nicht über den Katalog der Erweiterungen verfügbar gemacht, mit Ausnahme von MRI. Sie sind auf LibreOffice's API Reflexions-Fähigkeit aufgebaut.

    • X-Ray inspiziert LibreOffice-API-Objekte. Es zeigt die Eigenschaften, Methoden, Dienste, Interfaces an, die von einer Objekt-Variablen bereitgestellt werden. X-Ray ist verfügbar in Französisch, Englisch, Deutsch, Spanisch, Tschechisch, Polnisch und Russisch. X-Ray ist in Basic geschrieben.
    • MRI (My Reflection and Introspection) ist ein Introspektion-Werkzeug von UNO-Objekten, geschrieben in Pyton. Seine Funktionen sind gleichartig zu denen von X-Ray. MRI ist nur in Englisch verfügbar. Hinweis: Die Kopie von MRI im Katalog der LibreOffice-Erweiterungen ist veraltet.
    • Objekt-Inspektor Die Objekt-Inspektor-Erweiterung zeigt die gesamten Fähigkeiten eines UNO-Objekts an, wie zum Beispiel alle unterstützten Dienste, exportierten Interfaces und ihre jeweiligen Methoden und Eigenschaften in einer Baumansicht. Der Objekt-Inspektor ist in Java geschrieben und nur in Englisch verfügbar.
    • APSO Die Alternate-Python-Skript-Organisierer-Erweiterung integriert die Objekt-Inspektion gut in ihren Debugger. Sie verwendet entweder X-Ray oder MRI.

    Verwenden von Python-Makros

    Python-Makros in LibreOffice sind an zahlreichen Orten abgespeichert und kommen in verschiedenen Arten vor, wie erläutert in Python als eine Makro-Sprache. Skripts können persönlich, geteilt, in Erweiterungen untergebracht, integriert in Pakete oder eingebettet in Dokumente sein. Diese Vielfalt impliziert unterschiedliche Nutzungen und Einschränkungen.

    • In einem Dokument ist jedes Modul autonom, kein Modul-Import.
    Es sei auf Python-Import in der Online-/localen Hilfe verwiesen, um dies zu umgehen.
    • Aufruf einer Basic- oder Python-Erweiterung von einem eingebetteten Python-Modul ist möglich.
    • Python-Skripte in <user>\python\pythonpath können von eingebetteten Modulen oder von Skripten in <user>\python importiert werden.
    • Keine Basic-Unterstützung von einer IDE: Kein X-Ray
    Basic-Präsenz hängt von dem mit der IDE eingerichteten Brücken-Typ ab.
    • Python und Java werden unterstützt, sofern von einer IDE aktiviert: MRI, Object Inspector können benutzt werden.

    Hier ist beschrieben, wie Sie MRI in Python-Makros verwenden:

    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()

    Stoppen eines laufenden Makros mit 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("\nDie Basisbibliothek Xray ist nicht installiert", uno.getComponentContext())
    
    # ___________  Anwendungsbeispiel  _______________ 
    
    def demoXray(): 
      """ Beispiel: Gebrauch von xray in einem Writer-Dokument """ 
      
      xTextDoc = XSCRIPTCONTEXT.getDocument() 
      xText = xTextDoc.Text 
      xray(xText)
      xray("Demo ist fertig") 
    
    g_exportedScripts = demoXray,

    Anzeige von UNO-Objekten in einer Baumansicht unter Verwenden von Objekt-Inspektor:

    import uno
    def inspectObject( obj, title="Objekt-Inspektor" ):
    	ctx = uno.getComponentContext()
    	oi = ctx.ServiceManager.createInstanceWithContext("org.openoffice.InstanceInspector", ctx)
    	if oi is None:  # dh., InstanceInspector ist nicht installiert oder deaktiviert
    		return  # stiller Programmausgang
    	oi.inspect( obj, title )
    def exObjInspector():
    	doc = XSCRIPTCONTEXT.getDocument()
    	dsk = XSCRIPTCONTEXT.getDesktop()
    	inspectObject(doc)
    	inspectObject(dsk, title="StarDesktop")

    Aus einer IDE via LibreOffice-Python-Interpreter

    Die Entwicklung von Python-Makros innerhalb einer IDE erfordert das Verwenden des LibreOffice-Interpreters. Natives Python verfügt über den Interpreter der IDLE, der nicht mit UNO-Objekten kompatible ist. Bei der Auswahl einer Python-IDE profitieren Programmierer von zahlreichen Funktionen, wie zum Beispiel Klassen-Browser, Syntaxhervorhebung, Code-Vervollständigung, Durchsetzung von Kodierstandards, Test-getriebene Entwicklung, Debuggen, Versionskontrolle und viele mehr.

    Die Einstellung des LibreOffice-Python-Interpreters für Geany, PyCharm oder Pyzo ist dargestellt in Python- IDE-Grundlagen.

    Um ein Skript von <user>\python oder von <user>\python\pythonpfad auszuführen, muss eine Kommunikation zwischen der IDE und LibreOffice etabliert werden. UNO-Objekte sind ohne eine solche Brücke nicht erreicht werden. Sobald eine solce Kommunikation zustande gekommen ist, arbeiten die IDE und LibreOffice zusammen. Die folgenden Links dokumentieren diesen Prozess:

    IDE_utils-Modul übernehmen von diesen Ressourcen und stellen LibreOffice einfache Aktivierung von Python-Makro für IDE bereit.

    Verwenden von Python-Skripts

    • ...Python-Pakete aufrufen...

    Externe Ausführung mit Geany

    Geany initiert das Öffnen eines Fensters in LibreOffice. Geany-EDI ruft die Funktion info() auf, die die API-Methode ..awt.createMessageBox verwendet, definiert im SDK. Das Anwender-Skript ist als SysInfo.py benannt.

    Geany führt die Funktion info() aus, die die API-Methode ..awt.createMessageBox() aufruft, definiert im SDK - Skript-Name ist <user>\SysInfo.py

    Debuggen mit PyZo

    PyUNO-Workspace ist ein Objekt-Introspektions-Pyzo-IDE-Plug-in für PyUNO und die LibreOffice-UNO-API:

    Pyzo läuft und stoppt in <user>\..\IDE_utils.py
    Pyzo läuft und stoppt in <user>\..\IDE_utils.py

    Debuggen mit PyCharm

    PyCharms Debugger zeigt UNO-Objekte, Python-Klassen oder -Objekte an:

    Betrachten von UNO-Objekten, Python-Klassen oder -Variablen

    Debuggen mit APSO

    Der Alternative-Python-Skript-Organisierer-Erweiterung (APSO) erlaubt Schritt-für-Schritt-Ausführung ebenso wie Stapelverfolgungs-Ansicht (stack trace display) und UNO-Objekt-Inspektion mit xRay oder MRI.

    APSO-Debugger-Fenster

    Ausgabe in Konsolen

    Python-Skripte können mithilfe der Python-Shell und ihres REPL-Prozesses (Read Execute Print Loop) als Prototyp erstellt werden. Der Alternative Python-Skript-Organisierer integriert diese Funktion, die Teil von LibreOffice Python ist.

    APSO-Konsole

    Python-Interaktiv-Konsole

    Die Python interaktive Konsole, auch bekannt als Python-Interpreter oder Python-Shell bietet Programmierern eine schnelle Möglichkeit, Kommandos auszuführen und ihren Code auszuprobieren und zu testen, ohne eine Datei zu erstellen. UNO-Objekt-Introspektion ebenso wie LibreOfficeDev Python-Modul-Dokumentation können im Terminal abgerufen werden. LibreOffice online/lokal führen einzeln auf, wie man Python Interaktive Konsole ausführt.

    Python-Shell

    Konsole in Windows

    Standardmäßig gibt es kein voreingestelltes stdout auf Windows. Was mit der Funktion “print” gesendet wird, ist nirgendwo sichtbar. Um eine Konsole zu erhalten, um sie als stdout zu verwenden:

    • Starten von LibreOffice unter verwenden von soffice.com anstelle von soffice.exe:

    Die Python-Skript-Anweisungen print() werden in der Konsole angezeigt bis LibreOffice geschlossen wird. Sofern eine Konsole nicht vorhanden ist, sind print() Anweisungen stumm.

    Quelle: Korrekter Konsolenmodus für LibreOffice unter Windows

    Dies ist verfügbar ab dem LibreOffice-Release 6.3. Vor diesem Release folgen Sie dieser Beschreibung:

    1. Schließen Sie LibreOffice.
    2. Laden Sie Visual Studio Express 2010 C++ (Ich vermute es mag auch mit anderen Versionen funktionieren) herunter und installieren Sie es.
    3. Öffnen Sie eine Konsole in Visual Studio.
    4. Tippen Sie:

    editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.exe"
    editbin.exe /subsystem:console "C:\Program Files\LibreOffice 5\program\soffice.bin"

    cf. EditBin reference at TechNet

    Nun wird eine Konsole angezeigt, wenn Sie LibreOffice öffnen. Sie wird das stdout für das Kommando "print" seien. Und Sie können Python-Fehlermeldungen erhalten, während LibreOffice läuft, sofern Sie Traceback verwenden.

    import traceback
    […]
    try:
        […]
        except:
            traceback.print_exc()

    Aber Syntax-Fehler werden weiterhin dort nicht gemeldet.

    source: [Python] Fehler-Meldung - Debugging-Konfiguration

    Umgang mit Ausnahmen (Exceptions) - Entwurf

    Erstellen-Dialoge - Entwurf

    cf. UNODiT UNO Dialog Werkzeuge Nachfolgend finden Sie einige Referenzen, um zu starten:

    Dialoge gestalten

    Ereignisgesteuerte Makros

    Lokalisierung

    Dispatcher-Befehle - Entwurf

    Interface-orientierte Programmierung in *Office, Christopher Bourez (2015)

    Erweiterungen erstellen - Entwurf

    Erweiterungen

    Entwicklung von Erweiterungen

    Erweiterungsverwaltung

    Packen von UNO-Komponenten - Testen von Python-Komponenten

    Akzeptieren Sie Ereignisse erstellt durch Dialogsteuerelemente

    Einen Service erstellen

    Erstellen eines Calc-Add-In

    Erstellen und Erweiterung

    Verschiedenes - Entwurf

    Import von Dateisystemmodulen

    Vgl. Importieren von Python-Modulen in der Online-Hilfe

    Python-Paket versus LibreOffice-Extension

    (vgl. die französische Entwurf-Version bisher)

    Statische Eigenschaften oder Methoden

    F: Wie etwa ist das Verhalten eines globalen Python-Attributs?

    Verwenden von Git mit PyCharm - Entwurf