Python Development Environment/it

Un semplicistico Ambiente di sviluppo per Python all'interno di FreeCAD

Python è l'ambiente di programmazione che è stato incorporato nel sistema di FreeCAD. Usando Python molte delle operazioni offerte da FreeCAD sono accessibili tramite programmazione. Di solito i programmi in Python per FreeCAD sono sviluppati per essere eseguiti nella console Python o attraverso la facilitazione delle Macro di FreeCAD (vedere Come installare le macro).

Gli strumenti disponibili per lo sviluppo di programmi in Python sono numerosi. I fattori di complicazione per lo sviluppo di Python da usare con FreeCAD sono due: in primo luogo gli strumenti non hanno alcun supporto per le numerose strutture di dati e punti di accesso di FreeCAD; in secondo luogo non funzionano "internamente a FreeCAD". Ciò significa che è possibile utilizzare Python per sviluppare del codice all'esterno di FreeCAD senza poterlo testare nell'ambiente di destinazione; oppure si può svilupparlo nell'ambiente di destinazione (ad esempio l'ambiente FreeCAD), ma senza poter usufruire del supporto degli strumenti di sviluppo. Nessuna di queste è una soluzione accettabile.

Introduzione
Lo sviluppo dei software moderni nello standard commerciale di solito è fatto con un set di strumenti genericamente denominato 'IDE' (Integrated Development Environment - Ambiente di sviluppo integrato). Tipicamente questi strumenti sono i seguenti 3:


 * editor di codice sorgente
 * uno strumento di building automatico
 * un debugger

che sono standard, mentre i seguenti sono presenti in alcuni IDE, ma non in altri:


 * un tool di building automatico
 * un compilatore e/o un interprete integrato
 * un sistema di controllo di versione
 * strumenti per costruire la GUI (Graphical User Interface - Interfaccia Grafica per l'Utente)
 * un navigatore di classi
 * un analizzatore di oggetti
 * un diagramma della gerarchia delle classi

Una sintesi dello stato di questi strumenti all'interno FreeCAD è ('N/A' significa 'Non disponibile', ('Not Available')):

Per la programmazione Python esistono molti strumenti per supportare le funzioni di cui sopra, ma purtroppo non si integrano con l'ambiente di sviluppo di FreeCAD.

Un elenco di IDE per Python si trova a Integrated Development Environments for Python

Editor
FreeCAD contiene incorporato un editor per Python, esso si avvia cliccando sul pulsante Modifica del menu Macro->Macros... Se invece si desidera utilizzare un editor esterno più performante si può sceglire tra i numerosi editor Python disponibili per molte piattaforme e con diversi livelli di funzionalità. Utilizzando un editor esterno si ha il vantaggio di poter usare l'area di visualizzazione di FreeCAD per l'output (sia grafico che testuale nella console) mentre il codice sorgente viene visualizzato in un'altra applicazione. Un elenco di editor per Python secondo la piattaforma è disponibile all'indirizzo Python Editors

Nota : Per i Macintosh l'editor di testo TextWrangler funziona bene. Ha l'evidenziazione del codice ed eccellenti funzioni di ricerca. Ci sono opzioni per eseguire i lavori in Python, ma ovviamente non funzionano con l'ambiente FreeCAD.

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:

Debugger
Tipicamente i Debugger forniscono due caratteristiche principali (tra le altre):
 * i breakpoint (punti di sospensione) nel codice sorgente
 * l'ispezione delle variabili

I punti di sospensione Breakpoints sono "trappole" che vengono inserite nel codice, se il percorso di esecuzione attraverso il codice incontra uno di questi punti di sospensione, l'esecuzione viene fermata o sospesa. Notare che l'esecuzione non viene interrotta, dato che quando un programma viene interrotto tutte le informazioni residenti in memoria, come le variabili, vanno perse. Mentre il programma è sospeso il contenuto delle variabili può essere ispezionato e talvolta alterato (dipende dalla capacità del debugger). Generalmente il codice sorgente non può essere cambiato, ma alcuni ambienti supportano anche questo. Quando si è pronti, si può riprendere l'esecuzione del codice sorgente. Nel codice si possono inserire numerosi breakpoint e tramite questi punti si possono realizzare numerose sospensioni. Lo scopo del debugger è di fare in modo che l'esecuzione con i breakpoint e le sospensioni sia funzionalmente identico all'esecuzione senza breakpoint.

L'ispezione delle variabili è disponibile durante la sospensione dell'esecuzione causata da un breakpoint. In generale il contenuto delle variabili può essere visualizzato, e molti debugger supportano anche la modifica dei contenuti prima di riprende l'esecuzione.

Per FreeCAD è previsto, ma non è ancora disponibile un debugger con tutte le funzionalità. Questa sezione descrive alcune soluzioni alternative per l'interim, fino a quando il debugger non sarà rilasciato.

Breakpoint
Implementando i punti di interruzione si coinvolge un livello di supervisione del codice che gestisce l'esecuzione del codice in fase di sviluppo. Al momento tale livello di codice per lo sviluppo Python all'interno di FreeCAD non è disponibile. Come sostituto debole, il seguente codice è un'opzione. Invece di sospendere l'esecuzione del codice, ferma completamente l'esecuzione dividendo un numero per zero. Questa è davvero una scelta molto debole rispetto ad un corretto debugger con i punti di interruzione, inoltre questa opzione è utile solo se è usata insieme alla routine mostrata nella prossima sezione 'Variable Inspection'.

Breakpoint Code

Console Traceback

Quando un programma fallisce durante l'esecuzione, Python genera ciò che è noto come un traceback che elenca l'ordine di esecuzione del programma (cioè quale programma ha chiamato quale programma, in quale ordine).

Per il codice di esempio

otteniamo il seguente traceback

Leggendo il traceback possiamo stabilire che:
 * un messaggio di 'Breakpoint: amalgamation routine' è stato inviato dal breakpoint che ha la stringa 'amalgamation routine'
 * l'errore di esecuzione si è verificato alla riga 28 del modulo 'myNewMacro'
 * la routine 'myNewMacro' è stata chiamata dalla riga 40 del modulo 'testStub'

Assumendo che la stringa passata alla chiamata del breakpoint sia significativa allora la posizione del breakpoint può essere determinata facilmente. Notare che in un sistema complesso all'interno del traceback possono esserci decine o addirittura centinaia di voci.

Per diventare produttivi con questi punti di interruzione, continuare con la sezione successiva.

Variable Inspection
La seconda caratteristica principale di un debugger è quella di esaminare ed eventualmente modificare il contenuto delle variabili. Ancora una volta, fino a quando il debugger FreeCAD per Python non sarà pronto dobbiamo dipendere da soluzioni alternative.

Una caratteristica del sistema FreeCAD è la fornitura di variabili globali. Queste variabili sono create dal codice Python e risiedono nella memoria di FreeCAD fino a quando l'utente esce da FreeCAD. La forma di queste variabili è:

L'istruzione crea una variabile Python nella memoria di FreeCAD che è completamente accessibile dal codice Python, di fatto si comporta esattamente come una normale variabile Python. Però, dopo che l'esecuzione del codice Python termina, non importa se è eseguito come una macro o attraverso la console, la variabile 'FreeCAD.myVariable' rimane nella memoria con il valore di 123. Inserire:

produce il contenuto della variabile sulla console. Questo valore rimane in FreeCAD fino a quando non viene modificato o l'utente esce da FreeCAD. Ciò significa che il valore è presente e disponibile per essere letto da un successivo programma Python. Esso può essere controllato dalla console, in qualsiasi momento, digitando il suo nome. Quindi un programma chiamato 'Program A':

può essere eseguito e può caricare i valori nella variabile globale. Più tardi può essere eseguito un secondo programma chiamato 'Programma B' che può recuperare i valori:

Presumibilmente il 'Programma B' passa poi a fare calcoli che coinvolgono i valori lasciati in FreeCAD.myVariable. In qualsiasi momento l'utente può digitare nella console per ispezionare il contenuto delle variabili:

Una cosa importante da tenere presente con le variabili globali di FreeCAD è che esistono nella memoria e vengono perse quando il programma viene chiuso. Esse non sono salvate con i documenti, ma esistono solo nella memoria.

Uso
A questo punto possiamo mettere insieme le due fasi e usarle per rintracciare gli errori nel codice. Non è molto pratico da usare, ma è solo una alternativa finché il debugger di FreeCAD non sarà pronto.

Probabilmente è più facile presentando un esempio, vale a dire il seguente programma è in fase di debug:

L'esecuzione del programma produce nella console:

che non è quello che ci aspettavamo! Supponendo non siamo in grado di vedere gli errori, possiamo usare il nostro pseudo breakpoint e l'esaminatore variabile come segue. Possiamo inserire una riga per copiare il valore della variabile in una variabile globale, poi possiamo mettere un breakpoint per fermare l'esecuzione in quel punto:

Ora, quando si esegue il programma si ottiene:

Probabilmente le cose non appaiono molto bene, ma ora possiamo controllare il valore della variabile Python 'temporaryVariable1' dato che abbiamo assegnato il suo valore alla variabile globale 'FreeCAD.saveMyVariable':

Ora, ricordando che la variabile 'FreeCAD.saveMyVariable' contiene il valore della variabile Python 'temporaryVariable1' possiamo determinare l'errore nel valore e avviare tracingback per stabilire da dove arriva l'errore. Quando controlliamo la variabile 'FreeCAD.saveMyVariable' è importante rendersi conto che la variabile 'temporaryVariable1' non è più disponibile - è stata rimossa dal sistema Python.

Quando l'errore è stato localizzato nella istruzione

e corretto con:

Allora possiamo di nuovo eseguire il programma, e ottenere il valore '11', che non è ancora quello giusto. Possiamo fare più assegnazioni alle variabili globali di FreeCAD, avere più punti di interruzione (anche se l'esecuzione si fermerà al primo breakpoint incontrato)

Ora sono usati due punti di interruzione (anche se uno è commentato) e due variabili globali FreeCAD. Non vi è alcun limite pratico alle variabili globali disponibili da FreeCAD quindi non è necessario fare inutili economie. Ora nella console possiamo produrre quanto segue:

Alcuni punti circa l'uso delle variabili globali FreeCAD:
 * Python considera queste variabili in modo identico a qualsiasi altra variabile Python
 * queste variabili possono contenere qualsiasi tipo di dato Python - qualsiasi cosa che possa essere contenuta da una normale variabile Python
 * queste variabili possono essere utilizzate per 'rendere pubblico' il contenuto di una variabile Python in modo che si possa vederlo
 * queste variabili possono anche essere utilizzati per 'fornire' i valori a una variabile Python impostando il loro valore dalla console prima di eseguire una routine, o impodolo in un programma Python precedente
 * queste variabili possono essere utilizzate per passare dei dati tra due programmi che vengono eseguiti in tempi diversi
 * (ripeto) queste variabili esistono solo per la durata della sessione di FreeCAD, quando si esce da FreeCAD le variabili sono perse

Variable Watcher
La macro Global Variable Watcher aiuta a monitorare le variabili globali di FreeCAD. Si può visualizzare il contenuto di una variabile globale su richiesta o su base temporizzata.

Name Space Clash
One thing to be aware of is as there is no management of global variable names by FreeCAD so there is the possibility of changing a variable from the system or another piece of code. Consequently it is a good idea to prefix your variables with something unique such as the routine name. For example to use a variablefrom a routine called 'alpha1' the global name could be 'FreeCAD.alpha1MyVariable'.

Coding Framework
When developing small pieces of Python code in FreeCAD it may be sufficient to use the Python console. However as the number of lines of code grows it makes more sense to store them in a file. Python can be in any file ending with the extension ".py", however FreeCAD also provides a mechanism called Macro for storing such programs and interacting with them (e.g. editing, running). Python in regular '.py' files may only run from the Python console while python in macro file '.FCMacro' can be run from the FreeCAD interface for executing macros. One downside with the FreeCAD menu interface is it is menu based with a control window and potentially causes some clutter on the on-screen GUI.

Un approccio più semplice è quello di prendere il codice Python e invece di avviarlo dal menu Macro di FreeCAD, avviarlo da una barra degli strumenti. Una routine Python collegata ad un pulsante sulla barra degli strumenti può essere eseguita con un clic. Inoltre le barre degli strumenti sono finestre galleggianti che non ingombrano la visualizzazione sullo schermo. Infatti se la finestra di FreeCAD è inferiore alla dimensione fisica dello schermo la barra può essere lasciata fluttuare al di fuori della finestra di FreeCAD. Questo è utile quando sono richieste istantanee dello schermo di FreeCAD. Inoltre la barra degli strumenti può essere molto più piccola della finestra di controllo della macro visualizzata dal menu Macro di FreeCAD.

Come collegare una macro a un pulsante sulla barra degli strumenti è descritto in How to Install Macros e How to Customise a Toolbar. It can take a number of minutes to connect a macro to button on toolbar, select an icon etc. This is not always required as sometimes you simply want to quickly flesh out a piece of code which will then be integrated in some other code. For this situation a Test Stub can be beneficial. There is no real definition for what a test stub would entail, it really depends on the person and the application area. An example is shown below:

This test stub also serves as a template for code with locations defined for the different aspects of a large Python program. When executed the test stub program simply generates a message showing it's name and finishes. In using a test stub, any main line code written is placed at the very end of the file with code for class definition, functions etc. placed in the previous sections. The template can easily be altered to match the situation. Obviously for a program of 5 lines there is no need for such an amount of documentation.

By keeping a button permanently on a toolbar and linking that button to the test sub, there is always an area to write code and execute it immediately. The execution will be independent of the Python console. Also the execution can be independent of the screen GUI. Output from the program under development will appear as it should on the screen without any other artifacts from the programming environment. The Python console can be hidden to increase display area or used for any other purpose if needed. When execution is handled by the button on the toolbar the console is not required.

When the code is finished then is can simply be copied/pasted over to another file and the text stub left empty until the next time it is needed.

Multiple pieces of code can be developed using the same test stub with some extra code for providing multiple buttons which is located at PySide Beginner Examples - More Than 2 Buttons.

Supporti aggiuntivi per PySide

Per maggiori informazioni su PySide GUI c'è la pagina PySide

Supporti aggiuntivi per la programmazione Python

Per ulteriore assistenza con la codifica Python, esiste una macro scritta per facilitare lo sviluppo di codice Python, essa si trova in Python Assistant Window

Mettere tutto insieme
La gestione dello schermo può essere una sfida quando si sviluppa del codice che ha un output grafico complesso e dettagliato come fa FreeCAD. Il seguente sistema funziona bene:
 * FreeCAD per visualizzare console, report e GUI
 * barra degli strumenti per richiamare il codice in fase di sviluppo
 * editor esterno per modificare il codice
 * PAW (Python Assistant Window) per agevolare la generazione del codice Python

Gestione dello schermo

Con il test stub azionato da una barra degli strumenti, e utilizzando un editor esterno, l'impaginazione della finestra nello schermo sarà qualcosa del tipo:



"tree" nel diagramma si riferisce alla vista combinata o struttura a albero, la console Python e la vista Report sono riuniti nella finestra inferiore e selezionabili tramite i pulsanti. Quanto sopra è solo un idea, e può essere ottimizzato per un uso selettivo degli strumenti del flusso di sviluppo. Questo modello è stato confezionato a titolo personale.

Link vari
Alcuni altri link che riguardano le IDE per Python e che possono essere interessanti sono:
 * Comparison of Python IDEs for Development
 * Choosing the Best Python IDE
 * Your Development Environment
 * PyCharm Community Edition IDE