Strumento di Cattura Ambiente - capture_environment.py

capture_environment.py

1. Scopo e Contesto d’Uso

Lo script capture_environment.py (e la sua versione semplificata) è uno strumento di “archeologia delle dipendenze”. Il suo scopo non è per l’uso nello sviluppo quotidiano, ma per una situazione di emergenza specifica: quando ci si trova di fronte a un ambiente Python funzionante ma non documentato, di cui si vuole catturare lo stato per tentare di riprodurlo.

È stato creato a seguito del “dependency hell” incontrato durante il rollback di FIRE, dove avevamo un .venv funzionante ma nessun lockfile affidabile.

2. Funzionalità Principali

Lo script esegue una serie di comandi pip per estrarre quante più informazioni possibili dall’ambiente attivo, generando una cartella env_capture_<timestamp>/ con i seguenti artefatti:

• requirements-freeze.txt: L’output standard di pip freeze. Utile come base di partenza.
• requirements-exact.txt: Una versione più robusta del freeze, che tenta di “bloccare” (pin) tutte le versioni con ==. Questo è il file che abbiamo usato come input per pip-compile.
• environment-info.json: Un file JSON con metadati cruciali sull’ambiente: versione di Python, piattaforma, e versioni di pacchetti critici.
• RESTORE_GUIDE.md: Un file Markdown generato automaticamente con le istruzioni per tentare di ripristinare l’ambiente.

Le versioni più avanzate dello script possono anche generare un requirements.lock tramite pip-tools e un albero delle dipendenze con pipdeptree.

3. Quando Usarlo

L’uso di questo script è riservato a scenari di recupero o migrazione:

• Quando si eredita un progetto senza un lockfile.
• Quando si deve eseguire il rollback a una vecchia versione di cui si possiede solo l’ambiente virtuale.
• Quando si deve documentare lo stato di un ambiente di produzione per analisi forense.

Nello sviluppo normale, non si deve mai usare questo script. Il processo corretto è modificare requirements.in e usare pip-compile, come definito nella nostra policy ufficiale.

4. Riferimenti

• Per la policy ufficiale di gestione delle dipendenze, vedere DEPENDENCY-MANAGEMENT.