Quartz 4

Strumento di Verifica Ambiente

2 min read

Transclude of qc_verify_environment.py

1. Scopo e Filosofia

Lo script qc_verify_environment.py è la nostra prima linea di difesa contro i problemi di ambiente. Il suo scopo è fornire una risposta rapida e chiara alla domanda: “Il mio ambiente di sviluppo è configurato correttamente?”

È progettato per essere il primo comando da eseguire quando si inizia una sessione di lavoro o si incontra un comportamento inaspettato, per escludere immediatamente problemi legati all’ambiente.

2. Funzionalità e Controlli

Lo script esegue una serie di controlli sequenziali per validare lo stato dell’ambiente:

2.1. Controllo della Versione di Python

  • Cosa fa: Verifica che la versione di Python attiva (sys.version_info) corrisponda alla versione richiesta dal progetto (definita in una costante all’interno dello script).
  • Perché è importante: Garantisce che il codice venga eseguito con l’interprete per cui è stato testato, prevenendo errori di sintassi o di API.

2.2. Controllo dell’Ambiente Virtuale

  • Cosa fa: Controlla che lo script sia in esecuzione all’interno di un ambiente virtuale (venv).
  • Perché è importante: Previene l’inquinamento dell’ambiente Python globale di sistema e garantisce che le dipendenze installate siano quelle specifiche del progetto.

2.3. Controllo di Consistenza delle Dipendenze

  • Cosa fa: Esegue il comando pip check.
  • Perché è importante: Rileva conflitti tra le versioni dei pacchetti installati (es. pacchetto-A richiede pacchetto-C v1.0, ma è installato pacchetto-C v2.0).

2.4. Controllo di Sincronizzazione con il Lockfile

  • Cosa fa: Confronta la lista dei pacchetti attualmente installati (pip freeze) con la lista definita nel file requirements.lock.txt.
  • Perché è importante: Questo è il controllo più critico. Rileva due problemi comuni:
    1. Pacchetti Mancanti: Il lockfile è stato aggiornato (es. dopo un git pull), ma lo sviluppatore non ha ancora sincronizzato il proprio ambiente.
    2. Pacchetti Extra: Lo sviluppatore ha installato manualmente dei pacchetti (pip install ...) che non fanno parte dello standard del progetto, creando un ambiente “sporco” e non riproducibile.

3. Uso Operativo

L’uso dello script è semplice. Dal terminale, con l’ambiente virtuale attivo, eseguire:

python scripts/util/qc_verify_environment.py
  • Output in caso di successo: Lo script terminerà con un messaggio di successo (✅ Ambiente SANO).
  • Output in caso di fallimento: Lo script stamperà un messaggio di errore per ogni controllo fallito e fornirà suggerimenti su come risolvere il problema (es. Per risolvere, esegui: pip-sync requirements.lock.txt).

4. Riferimenti

Graph View