190 lines
16 KiB
Markdown
190 lines
16 KiB
Markdown
---
|
|
|
|
## Manuale Utente: Dependency Analyzer
|
|
|
|
---
|
|
|
|
### **ITALIANO**
|
|
|
|
#### 1. Introduzione
|
|
|
|
Dependency Analyzer è uno strumento con interfaccia grafica (GUI) progettato per aiutare gli sviluppatori Python a gestire le dipendenze dei loro progetti. Semplifica il processo di identificazione delle librerie esterne richieste da un progetto, la generazione di un file `requirements.txt`, il download dei pacchetti per la distribuzione offline e il confronto delle dipendenze richieste con quelle installate nell'ambiente corrente.
|
|
|
|
Lo strumento analizza il codice sorgente Python all'interno di una cartella specificata per trovare le istruzioni di importazione e distingue tra moduli della libreria standard di Python e pacchetti esterni.
|
|
|
|
#### 2. Funzionalità Principali
|
|
|
|
* **Selezione Cartella Progetto:** Permette di scegliere facilmente la cartella principale del progetto Python da analizzare.
|
|
* **Scansione Flessibile:** Rileva automaticamente se analizzare una sottocartella specifica (convenzione `nomeprogetto_minuscolo/`) o l'intera cartella selezionata.
|
|
* **Identificazione Dipendenze:** Analizza ricorsivamente i file `.py` per trovare tutti i moduli importati.
|
|
* **Distinzione Standard/Esterne:** Classifica gli import come appartenenti alla libreria standard di Python o come dipendenze esterne (di terze parti).
|
|
* **Generazione `requirements.txt`:** Crea un file `requirements.txt` dettagliato nella root del progetto, includendo:
|
|
* Versione Python dell'ambiente di analisi.
|
|
* Elenco dei moduli standard utilizzati, con indicazione dei file sorgente in cui sono importati.
|
|
* Elenco delle dipendenze esterne (con nome del pacchetto PyPI corretto, es. `Pillow` per `import PIL`), la versione rilevata nell'ambiente di analisi e i file sorgente in cui sono importate.
|
|
* **Visualizzazione Dipendenze:** Mostra un elenco chiaro delle dipendenze esterne identificate nell'interfaccia grafica.
|
|
* **Download Offline:** Scarica i pacchetti esterni specificati nel `requirements.txt` (e le loro dipendenze) in una sottocartella `_req_packages` per l'installazione offline. Copia anche il `requirements.txt` in questa cartella.
|
|
* **Creazione Script Installazione:** Genera script `install_packages.bat` (Windows) e `install_packages.sh` (Linux/macOS) all'interno di `_req_packages` per facilitare l'installazione dei pacchetti scaricati su un'altra macchina. Gli script includono un controllo per la presenza di `pip`.
|
|
* **Confronto Ambiente:** Confronta i pacchetti elencati nel `requirements.txt` con quelli attualmente installati nell'ambiente Python in cui lo strumento è in esecuzione, mostrando lo stato (OK, Mismatch, Not installed).
|
|
* **Aggiornamento Ambiente:** Permette di selezionare pacchetti non installati o con versione non corrispondente dalla tabella di confronto e tentare di installarli/aggiornarli nell'ambiente corrente usando `pip install --upgrade`, rispettando le specifiche del `requirements.txt`.
|
|
* **Logging Dettagliato:** Fornisce messaggi di log in tempo reale sia sulla console che nell'area "Log Messages" della GUI per seguire le operazioni.
|
|
|
|
#### 3. Prerequisiti
|
|
|
|
* **Python:** È necessario avere Python 3 installato (raccomandato Python 3.7 o superiore per una migliore compatibilità con le librerie utilizzate internamente come `importlib.metadata`).
|
|
* **Pip:** Lo strumento `pip` deve essere installato e accessibile dal terminale (di solito è incluso con le installazioni moderne di Python). Viene utilizzato per scaricare, confrontare e aggiornare i pacchetti.
|
|
* **(Opzionale) Libreria `packaging`:** Per un confronto più accurato delle versioni e una migliore gestione degli specificatori (es. `>=1.0, <2.0`) nel file `requirements.txt`, si consiglia di installare la libreria `packaging`:
|
|
```bash
|
|
pip install packaging
|
|
```
|
|
Lo strumento funzionerà anche senza, ma il confronto delle versioni sarà più basilare.
|
|
|
|
#### 4. Installazione/Setup
|
|
|
|
Dependency Analyzer viene fornito come un pacchetto Python. Per utilizzarlo:
|
|
|
|
1. Assicurati di avere i file sorgente (`__init__.py`, `__main__.py`, `gui.py`, `core.py`).
|
|
2. Crea una cartella chiamata `dependencyanalyzer` (o il nome che preferisci, ma assicurati che sia un identificatore Python valido).
|
|
3. Posiziona i quattro file sorgente all'interno della cartella `dependencyanalyzer`.
|
|
4. Posiziona questa cartella `dependencyanalyzer` in una locazione accessibile dal tuo Python PATH, oppure direttamente all'interno della cartella *genitore* del progetto che intendi lanciare con `python -m`. Ad esempio:
|
|
```
|
|
I_miei_progetti/
|
|
├── dependencyanalyzer/ <-- Cartella dello strumento
|
|
│ ├── __init__.py
|
|
│ ├── __main__.py
|
|
│ ├── gui.py
|
|
│ └── core.py
|
|
└── MioProgettoDaAnalizzare/
|
|
├── mioprogetto/
|
|
│ └── ...
|
|
└── README.md
|
|
```
|
|
|
|
#### 5. Avvio dello Strumento
|
|
|
|
1. Apri il tuo terminale o prompt dei comandi.
|
|
2. Naviga fino alla cartella *genitore* che contiene la cartella `dependencyanalyzer` (nell'esempio sopra, sarebbe `I_miei_progetti/`).
|
|
3. Esegui il comando:
|
|
```bash
|
|
python -m dependencyanalyzer
|
|
```
|
|
(Sostituisci `dependencyanalyzer` con il nome effettivo della cartella se l'hai rinominata).
|
|
4. L'interfaccia grafica dello strumento dovrebbe apparire.
|
|
|
|
#### 6. Utilizzo dell'Interfaccia Grafica
|
|
|
|
L'interfaccia è divisa in sezioni numerate che guidano l'utente attraverso il processo:
|
|
|
|
1. **Repository Operations:**
|
|
* Clicca sul pulsante **"Select Repository Folder"**.
|
|
* Scegli la cartella principale del progetto Python che vuoi analizzare.
|
|
* Il percorso selezionato apparirà nell'etichetta a destra. Il log mostrerà la selezione.
|
|
|
|
2. **Analysis & Requirements:**
|
|
* Una volta selezionata una cartella, il pulsante **"Analyze Project & Generate requirements.txt"** diventa attivo.
|
|
* Cliccalo per avviare l'analisi. Lo strumento:
|
|
* Determinerà se scansionare l'intera cartella o una sottocartella specifica (es. `nomecartella_minuscolo/`).
|
|
* Scansionerà ricorsivamente i file `.py` nella cartella target.
|
|
* Identificherà gli import standard ed esterni.
|
|
* Tenterà di rilevare la versione installata delle dipendenze esterne.
|
|
* Genererà il file `requirements.txt` nella root della cartella selezionata al passo 1.
|
|
* I messaggi di log mostreranno l'avanzamento.
|
|
|
|
3. **External Dependencies Found:**
|
|
* Questa tabella (`Treeview`) si popolerà con i nomi dei **pacchetti esterni** (nomi PyPI) trovati durante l'analisi e scritti nel `requirements.txt`.
|
|
|
|
4. **Download Packages & Create Installers:**
|
|
* **"Download Packages to \_req\_packages":** Se `requirements.txt` è stato generato e contiene dipendenze esterne, questo pulsante diventa attivo. Cliccandolo:
|
|
* Verrà creata (se non esiste) una cartella `_req_packages` nella root del progetto.
|
|
* Lo strumento tenterà di scaricare ogni pacchetto specificato nel `requirements.txt` (e le sue dipendenze) in questa cartella. Verrà copiato anche `requirements.txt` stesso.
|
|
* Il log mostrerà il progresso, indicando quale pacchetto sta tentando di scaricare e l'esito.
|
|
* **"Create install\_packages.bat/sh":** Se `requirements.txt` esiste, questo pulsante diventa attivo. Cliccandolo:
|
|
* Verrà copiata l'ultima versione di `requirements.txt` in `_req_packages` (se non già presente).
|
|
* Verranno creati gli script `install_packages.bat` e `install_packages.sh` dentro `_req_packages`. Questi script possono essere usati su un'altra macchina (insieme alla cartella `_req_packages`) per installare le dipendenze offline usando i file scaricati.
|
|
|
|
5. **System Package Comparison:**
|
|
* **"Compare requirements.txt with Installed Packages":** Se `requirements.txt` esiste e contiene dipendenze, questo pulsante è attivo. Cliccandolo:
|
|
* Lo strumento esegue `pip list` per ottenere i pacchetti installati nell'ambiente Python corrente.
|
|
* Confronta ogni dipendenza esterna nel `requirements.txt` con la versione installata.
|
|
* Popola la tabella sottostante con i risultati:
|
|
* `Package`: Nome del pacchetto (dal `requirements.txt`).
|
|
* `Required Version`: Specificatore di versione eventuale (dal `requirements.txt`, altrimenti "any").
|
|
* `Installed Version`: Versione trovata nell'ambiente corrente o "Not installed".
|
|
* `Status`: Indica se la versione installata soddisfa i requisiti ("OK", "Mismatch", "Not installed", ecc.).
|
|
* **"Update Selected Mismatched/Not Installed Packages":** Dopo aver eseguito il confronto, puoi selezionare una o più righe nella tabella (specialmente quelle con stato "Mismatch" o "Not installed"). Cliccando questo pulsante:
|
|
* Verrà chiesta conferma.
|
|
* Se confermato, lo strumento tenterà di eseguire `pip install --upgrade nomepacchetto` per i pacchetti selezionati, usando le specifiche di versione presenti nel `requirements.txt` del progetto.
|
|
* **Attenzione:** Questa operazione modifica l'ambiente Python in cui Dependency Analyzer è in esecuzione. Si consiglia vivamente di usare ambienti virtuali.
|
|
* Dopo l'aggiornamento, verrà automaticamente rieseguito il confronto.
|
|
|
|
* **Log Messages:** Quest'area mostra i messaggi informativi, di avviso e di errore generati dallo strumento durante le varie operazioni, fornendo un feedback in tempo reale.
|
|
|
|
#### 7. File Generati Spiegati
|
|
|
|
* **`requirements.txt` (nella root del progetto):**
|
|
* Contiene l'elenco delle dipendenze.
|
|
* Inizia con commenti sulla versione di Python e sul progetto.
|
|
* Include una sezione commentata con i moduli della libreria standard utilizzati.
|
|
* Include una sezione per le dipendenze esterne:
|
|
* Ogni dipendenza ha commenti che indicano dove è stata trovata nel codice e la versione rilevata nell'ambiente di analisi.
|
|
* La riga successiva contiene il nome del pacchetto PyPI (es. `Pillow`) che `pip` può usare per l'installazione.
|
|
* **`_req_packages/` (sottocartella nella root del progetto):**
|
|
* Creata quando si scaricano i pacchetti.
|
|
* Contiene i file dei pacchetti scaricati (`.whl`, `.tar.gz`, ecc.) e le loro dipendenze.
|
|
* Contiene una copia del file `requirements.txt` (usato dagli script di installazione).
|
|
* Contiene gli script `install_packages.bat` e `install_packages.sh`.
|
|
* **`_req_packages/install_packages.bat`:**
|
|
* Script per Windows.
|
|
* Verifica la presenza di `pip`.
|
|
* Esegue `pip install --no-index --find-links . -r requirements.txt` usando il `requirements.txt` presente nella stessa cartella (`_req_packages`).
|
|
* Da eseguire facendo doppio clic o da un prompt dei comandi all'interno della cartella `_req_packages`.
|
|
* **`_req_packages/install_packages.sh`:**
|
|
* Script per Linux e macOS.
|
|
* Verifica la presenza di `pip` per `python3` o `python`.
|
|
* Esegue `pip install --no-index --find-links . -r requirements.txt` usando il `requirements.txt` presente nella stessa cartella (`_req_packages`).
|
|
* Potrebbe essere necessario renderlo eseguibile (`chmod +x install_packages.sh`) prima di lanciarlo con `./install_packages.sh` da un terminale all'interno della cartella `_req_packages`.
|
|
|
|
#### 8. Esempi di Utilizzo
|
|
|
|
* **Scenario 1: Progetto Standard**
|
|
1. Hai un progetto in `C:/Projects/MyWebApp/` che contiene una sottocartella `mywebapp/` con il codice sorgente (`__init__.py`, `views.py`, ecc.).
|
|
2. Avvia `dependencyanalyzer`.
|
|
3. Clicca "Select Repository Folder" e scegli `C:/Projects/MyWebApp/`.
|
|
4. Clicca "Analyze Project & Generate requirements.txt". Lo strumento rileverà `mywebapp/`, scansionerà al suo interno, e ignorerà gli import come `from mywebapp.views import ...`. Genererà `C:/Projects/MyWebApp/requirements.txt`.
|
|
5. Esamina la tabella "External Dependencies Found".
|
|
6. Clicca "Download Packages..." per ottenere i pacchetti offline in `C:/Projects/MyWebApp/_req_packages/`.
|
|
7. Puoi zippare la cartella `_req_packages` e trasferirla su un'altra macchina per l'installazione tramite gli script `install_packages.*`.
|
|
|
|
* **Scenario 2: Script Singolo o Progetto "Piatto"**
|
|
1. Hai uno script e alcuni moduli di supporto in `D:/Scripts/MyUtility/` (es. `main_script.py`, `helpers.py`), senza una sottocartella `myutility/`.
|
|
2. Avvia `dependencyanalyzer`.
|
|
3. Clicca "Select Repository Folder" e scegli `D:/Scripts/MyUtility/`.
|
|
4. Clicca "Analyze Project & Generate requirements.txt". Lo strumento non troverà una sottocartella `myutility/` e scansionerà tutti i file `.py` direttamente in `D:/Scripts/MyUtility/`. Genererà `D:/Scripts/MyUtility/requirements.txt`.
|
|
5. Procedi come nello Scenario 1 per le altre operazioni.
|
|
|
|
#### 9. Risoluzione Problemi / Domande Frequenti
|
|
|
|
* **"Una dipendenza non viene trovata (ma so che c'è)":**
|
|
* Assicurati che l'import sia diretto (es. `import numpy`) e non dinamico (`importlib.import_module("numpy")`). Lo strumento analizza staticamente il codice con AST.
|
|
* Verifica se la dipendenza è importata all'interno di blocchi `try...except ImportError`. L'analisi AST di base la troverà comunque, ma assicurati che sia questo il caso.
|
|
* Controlla i log per eventuali errori durante l'analisi dei file.
|
|
* **"PIL/pillow non funziona":** Lo strumento ora mappa automaticamente `import PIL` al pacchetto `Pillow` per `requirements.txt` e il recupero della versione. Assicurati di avere `Pillow` installato (`pip install Pillow`).
|
|
* **"mpl_toolkits risulta come dipendenza esterna":** Questo modulo è spesso parte di `matplotlib`. Lo strumento ora dovrebbe ignorarlo esplicitamente (è nella lista `FALSE_POSITIVE_EXTERNAL_MODULES`). Se altri moduli simili causano problemi, potrebbero dover essere aggiunti a quella lista in `core.py`.
|
|
* **"Un modulo standard viene classificato come esterno (o viceversa)":** La logica `_is_standard_library` cerca di essere robusta usando `sysconfig` e liste predefinite, ma ambienti Python molto particolari o installazioni personalizzate potrebbero ingannarla. Controlla i log DEBUG per vedere come viene classificato e qual è il suo `origin`.
|
|
* **Errori durante il Download/Update (`pip`):**
|
|
* Controlla la connessione internet.
|
|
* Verifica di avere i permessi per scrivere nella cartella del progetto e `_req_packages`.
|
|
* Assicurati che `pip` funzioni correttamente dal tuo terminale.
|
|
* Leggi attentamente i messaggi di errore di `pip` mostrati nei log. Potrebbe trattarsi di un pacchetto non trovato su PyPI, conflitti di versione, o problemi di compilazione per pacchetti C.
|
|
* **L'aggiornamento modifica l'ambiente sbagliato:** Lo strumento modifica l'ambiente Python da cui viene lanciato. Usa sempre ambienti virtuali (`venv`, `conda`) per isolare le dipendenze dei progetti ed esegui `python -m dependencyanalyzer` dall'ambiente virtuale attivato.
|
|
|
|
#### 10. Limitazioni
|
|
|
|
* **Import Dinamici:** Gli import eseguiti programmaticamente (es. con `importlib.import_module()`) non vengono rilevati.
|
|
* **Dipendenze Non-Python:** Dipendenze a livello di sistema operativo o librerie C/C++ non installate tramite `pip` non vengono gestite.
|
|
* **Versioni Iniziali:** La versione scritta nel `requirements.txt` è quella rilevata nell'ambiente *al momento dell'analisi*. Non risolve attivamente le versioni richieste da `setup.py` o `pyproject.toml` (anche se `pip install -r requirements.txt` lo farà successivamente).
|
|
* **Strutture Complesse:** L'identificazione dei moduli interni del progetto si basa su convenzioni (sottocartella omonima o file nella root/pacchetti diretti). Progetti estremamente complessi con namespace packages o strutture non standard potrebbero richiedere aggiustamenti alla logica di identificazione.
|
|
|
|
---
|
|
|