GX-TXT Python Script Workspace: importare ed esportare file Python

Python Script Workspace permette di aprire un sorgente Python esterno e di esportare il codice nell’editor in un file .py. Queste operazioni consentono di riutilizzare programmi, produrre copie portabili e scambiare testo con altri ambienti.

In questa guida distingueremo Import, Export e Save nel Registry. Utilizzeremo soltanto sorgenti sintetici UTF-8, senza eseguire Job né pubblicare Dataset.

1. Aprire il Workspace

Dalla finestra principale GX-TXT aprire Viewers → Python Scripts. Il menu File contiene i comandi Import .py… ed Export .py….

È preferibile mantenere chiusi i pannelli secondari quando si esamina il codice, utilizzando View → Focus source / restore panes. La superficie Source rimane autenticamente High Contrast Dark, anche se i controlli Tk esterni sono chiari.

2. Importare non significa registrare

Import .py legge un file esterno e ne mostra il testo in una nuova bozza. La procedura non attribuisce automaticamente un’identità registrata.

Per creare uno Script nel Registry occorrono Scope, Script ID e altri metadati coerenti, seguiti dall’operazione separata Save. Import non avvia un Job.

3. Avviare Import .py

Selezionare File → Import .py…, oppure usare Ctrl+O. Si apre il selettore file nativo intitolato Import Python script.

Si tratta di una finestra del sistema grafico Tk. L’aspetto può variare leggermente secondo il tema desktop installato, mentre il significato di File name, Open e Cancel rimane lo stesso.

Il selettore presenta un elenco di file, il campo File name, il filtro Python scripts (*.py) e i pulsanti Open e Cancel.

Selezionare un file .py e confermare con Open. Il filtro rende più facile trovare i sorgenti Python, e l’applicazione verifica anche l’estensione effettiva.

Selettore file nativo di GX-TXT Python Script Workspace con sorgenti .py e pulsanti Open e Cancel
Figura 1. Il selettore Import Python script mostra il filtro *.py e consente di scegliere il sorgente da importare.

5. Individuare il sorgente appropriato

Prima della conferma verificare nome ed estensione. Il comando Import .py apre un singolo file sorgente, non automaticamente l’intera struttura di un progetto Python con più moduli.

La creazione di Script Project, gli entrypoint e la gestione dei file secondari saranno oggetto di capitoli distinti.

6. Un esempio UTF-8

Il seguente sorgente contiene una funzione semplice e commenti con caratteri accentati. Serve soltanto per illustrare il contenuto importato: non viene eseguito.

# P07 synthetic UTF-8 source — not executed
# Temperatura: città, qualità; unit: °C
from math import sqrt

def synthetic_curve(value):
    """Synthetic square-root calibration — esempio non eseguito."""
    gain = 2.0
    return gain * sqrt(value)

samples = [1.0, 4.0, 9.0]
for value in samples:
    print(synthetic_curve(value))

Conservarlo in un file .py con codifica UTF-8. Gli accenti, il simbolo di grado e l’indentazione sono utili per controllare eventuali alterazioni.

7. Il controllo della codifica

L’importatore interpreta i byte come testo UTF-8 e verifica che la decodifica non provochi differenze. Se un file contiene una sequenza di byte non valida, l’importazione viene rifiutata.

La verifica riguarda la codifica del testo, non la disponibilità delle librerie Python o la correttezza scientifica delle formule.

8. La nuova bozza nell’editor

Dopo Open il codice compare in una nuova scheda untitled.py. Il testo conserva funzione, indentazione, commenti e caratteri Unicode del file.

La barra inferiore segnala che il sorgente non è ancora registrato, con indicazioni come unsaved, SHA-256 pending e modified.

Editor Python GX-TXT con codice UTF-8 importato, caratteri accentati, scheda untitled.py e stato unsaved modified
Figura 2. Dopo Import .py, il codice UTF-8 è leggibile nell’editor High Contrast Dark e la bozza rimane unsaved.

9. I metadati proposti

Il Viewer ricava Name dal nome del file senza estensione e propone Version = 1.0.0. Lo Scope segue il contesto di Session o User attivo.

In Description viene annotata la provenienza dal file. L’eventuale Script registrato sarà indipendente dal file originale; lo Script ID rimane da definire prima della registrazione.

10. Import crea una nuova scheda

Il comando Import apre un documento aggiuntivo senza sovrascrivere arbitrariamente quelli già presenti. I precedenti Script registrati e le bozze restano disponibili nelle rispettive schede.

Quando si importano più sorgenti, è importante controllare quale scheda è attiva prima di usare Save, Export o Close tab.

11. Il file esterno non si sincronizza da solo

Dopo Import, il testo nell’editor è una copia di lavoro. Una modifica del file esterno non aggiorna automaticamente la scheda già aperta, e modificare la scheda non riscrive automaticamente il file di origine.

Analogamente, Save nel Registry è un’operazione sullo Script GX-TXT, non un comando di sovrascrittura del file importato.

12. Export prima di Save

È possibile usare File → Export .py… anche quando il sorgente importato è ancora una bozza non registrata.

Questo permette di leggere o modificare codice e conservarlo come file esterno, senza creare una nuova revisione del Registry.

13. Il dialogo Export Python script

Si apre il dialogo nativo Export Python script, con un nome suggerito, il filtro Python scripts (*.py) e i pulsanti Save e Cancel.

Selezionare una destinazione adeguata, fornire un nome che termini in .py e confermare. Il file prodotto contiene il testo della scheda attiva.

Selettore nativo Export Python script con nome file .py, filtro Python scripts e pulsanti Save e Cancel
Figura 3. Export .py apre il dialogo nativo di salvataggio del file anche se la bozza importata non è registrata.

14. Cancel non crea un file

Premendo Cancel nel dialogo Export, la procedura termina senza creare la nuova destinazione. Il documento nell’editor rimane invariato.

Anche Cancel nel dialogo Import evita l’apertura di un nuovo sorgente. La selezione del nome e la conferma sono due passaggi distinti.

15. Verificare il contenuto esportato

Dopo Save nel dialogo Export, GX-TXT scrive il testo come byte UTF-8 nel file .py selezionato.

Con l’esempio UTF-8 non modificato, il file esportato è identico byte per byte all’originale: accenti, simbolo di grado, indentazione, righe vuote e newline finale sono preservati.

16. Verificare il file con SHA-256

Se è necessaria un’identità esatta fra file esterni, si possono confrontare dimensioni e SHA-256 dei due file. Impronte uguali indicano che i byte sono uguali.

Questa impronta calcolata sul file esterno non va confusa con SHA-256 pending della bozza, che indica l’assenza di un record sorgente già registrato.

17. Newline LF e CRLF

Le righe dei file di testo possono terminare con LF oppure CRLF, comune nell’ambiente Windows.

Nel ciclo verificato Import → Export, GX-TXT mantiene i terminatori CRLF del file originale, così come gli LF. Se il codice non viene modificato, non è richiesta una normalizzazione automatica in LF.

18. Un sorgente importato con CRLF

Un breve file di due righe con terminatori CRLF viene visualizzato normalmente nell’editor Python.

Dopo Export, il file mantiene gli stessi byte e lo stesso SHA-256 dell’originale. Il controllo dei newline va fatto sui byte del file, non soltanto sull’aspetto del testo nel Viewer.

Editor Python GX-TXT con sorgente importato di due righe, preparato in UTF-8 con terminatori CRLF
Figura 4. Il file di esempio con newline CRLF appare come codice Python leggibile; i byte dei newline vengono conservati nell’esportazione.

19. Importare un file .py vuoto

Un file .py privo di contenuto può essere aperto. Compare una nuova scheda untitled.py, con la superficie del codice vuota e il nome descrittivo ricavato dal file.

La bozza rimane unsaved e non genera un nuovo Script registrato.

Editor Python High Contrast Dark con sorgente vuoto importato, numero riga 1 e schede precedenti intatte
Figura 5. Anche un file Python vuoto viene aperto come una nuova bozza untitled.py non registrata.

20. Import rifiuta una falsa estensione

Un file con un’estensione diversa da .py viene respinto con il messaggio Import failed.

Il controllo avviene prima della creazione di una nuova scheda. Il documento corrente e gli Script registrati rimangono intatti.

Messaggio originale Import failed con richiesta di scegliere un file sorgente Python con estensione .py
Figura 6. Un file che non termina in .py viene respinto dal dialogo Import failed senza alterare la bozza già aperta.

21. Import rifiuta byte UTF-8 non validi

Se un file termina in .py ma contiene byte non validi in UTF-8, il Viewer mostra un altro messaggio Import failed.

Non conviene sostituire arbitrariamente i caratteri non leggibili. Occorre correggere la codifica del file di partenza e ripetere l’operazione.

Messaggio originale Import failed per file di testo non conforme alla codifica UTF-8
Figura 7. L’importazione respinge un file contenente byte non validi in UTF-8 e preserva il documento corrente.

22. Gli errori lasciano intatto il sorgente corrente

Nei due casi appena descritti l’importazione viene rifiutata prima di inserire il testo. Dopo la chiusura del messaggio, la scheda già aperta conserva il contenuto precedente.

È possibile correggere il problema nel file esterno e ripetere Import senza ricostruire il documento esistente.

23. Anche Export verifica l’estensione

Export richiede un file di destinazione con estensione .py. Se si sceglie una destinazione con un’estensione differente, il Viewer mostra Export failed.

La destinazione non valida non viene creata e il codice nell’editor non cambia.

Messaggio originale Export failed per destinazione non conforme all’estensione Python .py
Figura 8. Export failed impedisce di salvare il sorgente con un’estensione diversa da .py.

24. Import, Export e Save sono operazioni diverse

OperazioneRisultato principaleNuovo Script nel Registry?
Import .pyApre il file esterno come bozzaNo
Export .pyScrive il codice corrente come file esternoNo
File → SaveRegistra o aggiorna lo Script con ID e metadatiSì, se la validazione riesce
File → Save AsRegistra una copia con una nuova identitàSì

Per condividere un sorgente può bastare Export. Per utilizzarlo come Script identificato nel framework occorre una registrazione esplicita.

25. Identità dello Script e portabilità

Quando si decide di registrare un file importato, scegliere uno Script ID stabile, un Name comprensibile e una Description che chiarisca lo scopo.

È preferibile evitare percorsi assoluti dell’installazione nel codice. Un sorgente portabile è più semplice da riutilizzare in altre Session o su un altro computer.

26. Controllare la copia prima di distribuirla

Riaprire il file esportato in un editor e verificare caratteri speciali, indentazione, codifica e terminatori di riga.

Se serve un’identità completa con l’originale, confrontare dimensione e SHA-256. Se nel frattempo si è modificato volontariamente il testo, un hash diverso è normale.

27. Una procedura di lavoro ordinata

Aprire il Workspace, utilizzare Import .py e controllare il sorgente nell’editor. Se si vuole conservare una copia esterna, usare Export .py e verificare il file prodotto.

Per integrare il programma nel flusso GX-TXT, completare Scope, Script ID e metadati e utilizzare separatamente File → Save. Per una prova temporanea, chiudere la bozza soltanto dopo aver deciso se conservarla.

Import .py apre un documento di lavoro, Export .py scrive un file Python e Save registra lo Script nel Registry. Sono tre passaggi distinti.

Il Viewer accetta file Python UTF-8, preserva i byte e i newline dei sorgenti non modificati, permette anche un .py vuoto e rifiuta estensioni o codifiche non valide senza alterare il documento precedente.

Nel prossimo capitolo esamineremo Manage imports: come consultare gli import suggeriti e inserirli nel sorgente, distinguendo gli esempi dalla reale disponibilità dei moduli nel runtime.