VALLONGOL/SXXXXXXX_DependencyAnalyzer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e8485703b3
SXXXXXXX_DependencyAnalyzer/doc/Italian-Manual.md
VALLONGOL 20e1ea2464 add manual and readme
2025-05-06 14:47:12 +02:00

16 KiB
Raw Blame History

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