---

## 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.

---