Python Development Environment/de

Eine vereinfachte Entwicklungsumgebung für Python in FreeCAD

Python ist eine Programmierumgebung, die in das FreeCAD System integriert wurde. Mit Python stehen viele von FreeCAD angebotene Abläufe für den programmierten Zugriff zur Verfügung. Python Programme für FreeCAD werden in der Regel so entwickelt, dass sie entweder auf der Python Konsole oder über die Makrofunktion von FreeCAD ausgeführt werden können (siehe Wie man Makros installiert).

Für die Programmentwicklung in Python stehen zahlreiche Werkzeuge zur Verfügung. Die komplizierenden Faktoren für die Entwicklung von Python zur Verwendung mit FreeCAD sind zweifach: Zum einen haben die Werkzeuge keine Unterstützung für die zahlreichen Datenstrukturen und Zugriffspunkte von FreeCAD; zum anderen funktionieren sie nicht "innerhalb von FreeCAD". Das bedeutet, dass Du mit ihnen Code außerhalb von FreeCAD entwickeln kannst und nicht in der Zielumgebung testen kannst; oder Du kannst Python in der Zielumgebung (d.h. der FreeCAD Umgebung) entwickeln, hast aber keine Unterstützung durch die Entwicklungswerkzeuge. Keines von beiden ist eine akzeptable Lösung.

Hintergrund
Die moderne Softwareentwicklung auf dem kommerziellen Standard erfolgt in der Regel mit einem Satz von Werkzeugen, der üblicherweise als 'IDE' bezeichnet wird. Typischerweise umfassen diese Werkzeuge die folgenden 3:


 * Quellcode Editor
 * Automatisierungstools bauen
 * Fehlersuchprogramme

die Standard sind, während die folgenden in einigen IDEs vorhanden sind, in anderen aber nicht:


 * intelligente Code Vervollständigung
 * integrierter Compiler, Interpreter oder beides
 * Versionskontrollsystem
 * Konstruktion der grafischen Benutzeroberfläche (GUI)
 * Klasse Browser
 * Objekt Browser
 * Klassenhierarchie Diagramm

A summary of the status of these tools within FreeCAD is ('N/A' meaning 'Not Available'):

Many tools exist to support the above function for Python programming but unfortunately they do not integrate with the FreeCAD development environment.

A list of IDEs for Python is located at Integrated Development Environments for Python

Editors
There is an editor for Python as part of FreeCAD, it is started by clicking the Edit button on the Macro->Macros... If you want to use a 3rd party editor which takes advantage of your platform then there are various Python editors available, for numerous platforms and with a variety of level of functionality. One advantage of using an external editor is that the display area of FreeCAD can be used for output (both graphic and textual to the console) while the source code is displayed in a different application. A list of editors for Python for a variety of platforms is available at Python Editors

Note : For the Macintosh the text editor TextWrangler works well. It has code highlighting and excellent search facilities. There are options to execute jobs in Python but of course they do not work with the FreeCAD environment.

Macro Source Code Directories
There are two directories used by FreeCAD, by default they are the same directory but they are pointed to by different callable point in FreeCAD:
 * FreeCAD.ConfigGet("UserAppData")
 * FreeCAD.ParamGet('User parameter:BaseApp/Preferences/Macro').GetString('MacroPath')

The first one "UserAppData" points to a directory where things like configuration files or other files intended for the user but not to be edited by the user may be stored.

The second one "MacroPath" points to a directory where the Python files which are macro files for FreeCAD are stored. To mark a Python file as a macro file for FreeCAD, the file extension is changed from ".py" to ".FCMacro".

By default these two directories are the same location but this is not necessary. It might be convenient to alter the location for the macro files (*.FCMacro) to a different location.

Editing files located in the "MacroPath" is straight forward, the text editor will accommodate this. For ease of use of FreeCAD Macro files, it is advisable to keep all the macro files in the directory pointed to by "MacroPath".

To alter the "MacroPath" directory, use Tools->Edit Parameters and then select Preferences/Macro/MacroPath where the text may be double-clicked and edited. Alternatively "MacroPath" can be altered by the code:

Fehlersuchprogramm
Debugger bieten typischerweise zwei Hauptfunktionen (unter anderem):
 * Haltepunkte im Quellcode
 * Variablenprüfung

Breakpoints are 'traps' that are placed in the code, if the execution path through the code encounters one of these breakpoints, then execution is halted or suspended. Note that execution is not stopped as when a program is stopped all memory resident information such as variables is lost. While the program is suspended the contents of variables can be inspected and sometimes altered (which depends on the ability of the debugger). Generally the source code can not be changed although some environments do support this. When ready, the execution of the source code can be resumed. Numerous breakpoints can be placed in the code and numerous suspensions through the breakpoints may occur. The purpose of the debugger is to make sure that the execution with the breakpoints and suspensions is functionally identical to execution without breakpoints.

Variable Inspections are available during the suspension of execution caused by a breakpoint. Generally the contents of variables can be viewed, many debuggers also support the editing of the contents before execution resumes.

Although a fully functioned debugger is planned for FreeCAD it is not available as of yet. This section will detail some work-arounds for the interim until the debugger is released.

Breakpoints
Implementing breakpoints involves a supervisory level of code which administers the execution of the code under development. Such a level of code for Python development within FreeCAD is not presently available. As a weak substitute, the following code is an option. Instead of suspending the execution the code will halt execution completely by dividing a number by zero. This really is a very weak option compared to a proper debugger breakpoint, also this option is only of use when used alongside the routine shown in the next section 'Variable Inspection'.

Breakpoint Code

Console Traceback

When a program fails during execution, Python generates what is known as a traceback which lists the order of program execution (i.e. which program called which program in which order).

For the code sample

we get the following traceback:

Reading the traceback we can determine that:
 * a message of 'Breakpoint: amalgamation routine' was sent by the breakpoint which has the string 'amalgamation routine'
 * the execution error occurred at line 28 of module 'myNewMacro'
 * routine 'myNewMacro' was called from line 40 in the module 'testStub'

Assuming the string passed to the breakpoint call is meaningful then the location of the breakpoint can easily be determined. Note that is a complex system the traceback may have tens or even hundreds of entries in it.

To become productive with these breakpoints, continue on to the next section.

Variable Inspection
The second main feature of a debugger is to examine and possibly alter the contents of variables. Once again, until the FreeCAD debugger for Python is ready we have to depend on work-arounds.

A feature of the FreeCAD system is the provision of global variables. These variables that are created by the Python code and exist in FreeCAD's memory until the user Quits from FreeCAD. The form of these variables is:

The statement creates a Python variable in the FreeCAD memory which is fully accessible to Python code, in fact it behaves identically to a normal Python variable. Yet after the Python code finishes running, no matter if it is running as a macro or through the console, there will be a variable 'FreeCAD.myVariable' remaining in memory with the value of 123. Entering:

will produce the contents of the variable on the console. This value will remain in FreeCAD until either it is changed or the user Quits from FreeCAD. This means the value is present and available for a subsequent Python program to read from. At any time it can be checked from the console by typing it's name. So a program called 'Program A':

can run and load values into the global variable. Later a second program called 'Program B' can run and retrieve the value:

Presumably 'Program B' then goes on to make calculations involving the values left in FreeCAD.myVariable. At any time the user can type on the console to inspect the variable contents:

An important fact to be aware of with FreeCAD global variables is that they exist in memory and are lost when the program is Quit from. They are not saved with documents but only exist in memory.

Usage
This brings us to a point where we can put the two steps together and use them to trace down errors in code. This is a bit cumbersome to use but is only the option until the FreeCAD debugger is ready.

It's probably easiest to present through an example, say the following program is being debugged:

Execution of the program on the console yields:

which is not what we expected! Assuming we are unable to see the errors we can use our unsophisticated breakpoint and variable examiner as follows. We can insert a line to copy the value of the variable we are wondering about to a global variable, then we can place a breakpoint to halt execution there:

Now when we run the program we get:

Probably things don't look so good, but what we can now do is inspect the value of the Python variable 'temporaryVariable1' as we assigned it's value to the global variable 'FreeCAD.saveMyVariable':

Remembering that the variable 'FreeCAD.saveMyVariable' holds the value of the Python variable 'temporaryVariable1' we can now determine the error in the value and start tracing back to determine where the error came from. When we are looking at 'FreeCAD.saveMyVariable' it is important to realise that the variable 'temporaryVariable1' is no longer available - it has been garbage collected away by the Python system.

Once the error has been located in the statement

and corrected to:

Then we can run the program again, and get the value of '11' which is still not right. We can make more assignments to FreeCAD global variables, have multiple breakpoints (although the first one encountered will stop execution)

We now have two breakpoints (although one is commented out) and two FreeCAD global variables in use. There is no practical limit to the global variables available from FreeCAD so there is no need to economise unnecessarily. We can now produce the following on the console:

Some points about the use of the FreeCAD global variables:
 * Python treats these variables identically to any other Python variable
 * these variables may hold any Python data type - anything a regular Python variable would hold
 * these variables may be used to 'bring out' the contents of a Python variable so we can see them
 * also these variables may be used to 'supply' values to a Python variable by setting their value from the console prior to running a routine, or setting it in a previous Python program
 * these variables may be used to pass data between two programs that run at different points in time
 * (to repeat) these variables are only for the duration of the FreeCAD session, once the user Quits from FreeCAD then the variables are lost

Variable Beobachter
Es gibt ein Dienstprogramm Global Variable Watcher, um die globalen Variablen von FreeCAD zu überwachen. Es kann den Inhalt einer globalen Variable entweder auf Anfrage oder auf Zeitbasis anzeigen.

Name Space Clash
Eine Sache, die man beachten muss, ist, dass FreeCAD keine Verwaltung von globalen Variablennamen hat, so dass die Möglichkeit besteht, eine Variable vom System oder ein anderes Stück Code zu ändern. Folglich ist es eine gute Idee, Ihren Variablen etwas Eindeutiges voranzustellen, wie z.B. den Routinenamen. Um beispielsweise eine Variable aus einer Routine namens 'alpha1' zu verwenden, könnte der globale Name 'FreeCAD.alpha1MyVariable' lauten.

Codierung Gerüst
Bei der Entwicklung von kleinen Teilen des Python Codes in FreeCAD kann es ausreichen, die Python Konsole zu verwenden. Mit zunehmender Anzahl von Codezeilen macht es jedoch mehr Sinn, diese in einer Datei zu speichern. Python kann in jeder Datei mit der Endung ".py" stehen, FreeCAD bietet jedoch auch einen Mechanismus namens Macro zum Speichern solcher Programme und zur Interaktion mit ihnen (z.B. Bearbeiten, Ausführen). Python in regulären '.py'-Dateien kann nur von der Python Konsole aus ausgeführt werden, während Python in der Makro Datei '.FCMacro' von der FreeCAD Schnittstelle zur Ausführung von Makros ausgeführt werden kann. Ein Nachteil der FreeCAD Menüoberfläche ist, dass sie menügeführt ist und ein Kontrollfenster enthält, was zu einem gewissen Durcheinander auf der Bildschirmoberfläche führen kann.

Ein einfacherer Ansatz ist es, den Python Code zu nehmen und ihn nicht aus dem FreeCAD Makro Menü zu starten, sondern aus einer Werkzeugleiste heraus. Eine Python Routine, die mit einer Schaltfläche in einer Symbolleiste verknüpft ist, kann mit einem Klick ausgeführt werden. Da es sich bei den Symbolleisten um schwebende Fenster handelt, wird die Bildschirmanzeige nicht überladen. Wenn das FreeCAD Fenster kleiner als die physische Größe des Bildschirms ist, kann die Symbolleiste außerhalb des FreeCAD Fensters schweben. Dies ist vorteilhaft, wenn Bildschirmschnappschüsse der FreeCAD Anzeige benötigt werden. Außerdem kann die Werkzeugleiste viel kleiner sein als das Makro-Steuerungsfenster, das im Makro Menü von FreeCAD angezeigt wird.

Das Verbinden eines Makros mit einer Schaltfläche auf einer Symbolleiste wird in So installieren Sie Makros und So passen Sie eine Symbolleiste an behandelt. Es kann einige Minuten dauern, ein Makro mit einer Schaltfläche in der Symbolleiste zu verbinden, ein Symbol auszuwählen usw. Dies ist nicht immer erforderlich, da man manchmal einfach nur schnell ein Stück Code ausarbeiten möchte, das dann in einen anderen Code integriert wird. Für diese Situation kann ein Test Stub vorteilhaft sein. Es gibt keine wirkliche Definition dafür, was ein Test-Stub beinhalten würde, es hängt wirklich von der Person und dem Anwendungsbereich ab. Ein Beispiel ist unten dargestellt:

Dieser Test stub dient auch als Vorlage für Code mit definierten Stellen für die verschiedenen Aspekte eines großen Python Programms. Bei der Ausführung des Teststub Programms wird einfach eine Meldung mit dem Namen des Programms erzeugt und beendet. Bei der Verwendung eines Teststubs wird der geschriebene Hauptzeilencode ganz am Ende der Datei platziert, wobei der Code für die Klassendefinition, Funktionen usw. in den vorherigen Abschnitten platziert wird. Das Template kann einfach an die Situation angepasst werden. Bei einem Programm mit 5 Zeilen ist eine solche Menge an Dokumentation natürlich nicht notwendig.

Indem man einen Button permanent auf einer Symbolleiste behält und diesen Button mit dem Test Sub verknüpft, gibt es immer einen Bereich, in dem man Code schreiben und sofort ausführen kann. Die Ausführung erfolgt unabhängig von der Python Konsole. Die Ausführung kann auch unabhängig von der Bildschirm GUI erfolgen. Die Ausgaben des zu entwickelnden Programms erscheinen so, wie sie auf dem Bildschirm erscheinen sollen, ohne weitere Artefakte aus der Programmierumgebung. Die Python Konsole kann bei Bedarf ausgeblendet werden, um die Anzeigefläche zu vergrößern oder für andere Zwecke verwendet werden. Wenn die Ausführung über die Schaltfläche in der Werkzeugleiste erfolgt, wird die Konsole nicht benötigt.

Wenn der Code fertig ist, kann er einfach in eine andere Datei kopiert werden und der Text stub bleibt bis zum nächsten Mal leer.

Mehrere Code Stücke können unter Verwendung desselben Teststub mit etwas extra Code für die Bereitstellung mehrerer Buttons entwickelt werden, der sich unter PySide Beginner Examples - More Than 2 Buttons befindet.

Mehr PySide Unterstützung

Für weitere Unterstützung bei der Verwendung der PySide GUI gibt es die Seite PySide

Mehr Unterstützung für Python-Programmierung

Für weitere Unterstützung bei der Python Codierung gibt es ein Makro, das zur Unterstützung bei der Entwicklung von Python Code geschrieben wurde, befindet es sich unter Python Assistenz Fenster

Alles Zusammensetzen
Die Bildschirmverwaltung kann eine Herausforderung sein, wenn es darum geht, Code zu entwickeln, der komplexe und detaillierte grafische Ausgaben hat, wie es FreeCAD tut. Das folgende System funktioniert gut:
 * FreeCAD für Konsole, Bericht, GUI-Anzeige
 * Symbolleiste zum Aufruf von in Entwicklung befindlichem Code
 * externer Editor zum Modifizieren des Codes
 * PAW (Python Assistant Window) zur Unterstützung der Python Code Generierung

Bildschirmmanagement

Wenn der Test stub über eine Symbolleiste bedient wird und ein externer Editor verwendet wird, wird das Fensterlayout auf dem Bildschirm in etwa so aussehen:



"Baum" im Diagramm bezieht sich auf den Combi oder Baum Browser, die Python Konsole und die Report Ansicht sind im unteren Fenster zusammengefasst und über Schaltflächen auswählbar. Durch den gezielten Einsatz der Werkzeuge kann der Entwicklungsstrom optimiert werden, das oben genannte ist nur eine Idee. Der Zuschnitt erfolgt auf einer persönlichen Basis.

Verschiedene Verknüpfungen
Einige andere Verknüpfungen über IDEs für Python, die von Interesse sein könnten, sind:
 * Vergleich von Python-IDEs für die Entwicklung
 * Die beste Python-IDE auswählen
 * Ihre Entwicklungsumgebung
 * PyCharm Community Edition IDE