From 20e1ea24647526a2e6e946e91261be22f1775910 Mon Sep 17 00:00:00 2001 From: VALLONGOL Date: Tue, 6 May 2025 14:47:12 +0200 Subject: [PATCH] add manual and readme --- README.md | 179 +++++++++++++++++++++++++++++++++++++++ doc/English-Manual.md | 97 ++++++++++++++++++++++ doc/Italian-Manual.md | 189 ++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 465 insertions(+) create mode 100644 README.md create mode 100644 doc/English-Manual.md create mode 100644 doc/Italian-Manual.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..49a2a9d --- /dev/null +++ b/README.md @@ -0,0 +1,179 @@ +# Dependency Analyzer + +Un'applicazione GUI per analizzare le dipendenze di progetti Python, generare `requirements.txt`, scaricare pacchetti offline e confrontare ambienti. + +--- + +[English Version Below](#english) + +--- + +## Dependency Analyzer (Italiano) + +### Introduzione + +`Dependency Analyzer` è uno strumento desktop (con interfaccia grafica costruita usando Tkinter) che semplifica la gestione delle dipendenze per progetti Python. Analizza staticamente il codice sorgente per identificare i moduli importati, distinguendo tra librerie standard e pacchetti esterni. + +L'obiettivo è fornire un modo semplice per: + +1. Ottenere un elenco chiaro delle dipendenze esterne di un progetto. +2. Generare un file `requirements.txt` dettagliato e informativo. +3. Preparare i pacchetti per una distribuzione offline. +4. Confrontare le dipendenze richieste con l'ambiente di sviluppo corrente. + +### Caratteristiche Principali + +* **Interfaccia Grafica Semplice:** Basata su Tkinter per un utilizzo intuitivo. +* **Selezione Cartella Flessibile:** Analizza l'intera cartella selezionata o una sottocartella specifica se segue la convenzione `nomeprogetto_minuscolo/`. +* **Analisi Statica (AST):** Esamina i file `.py` per trovare le istruzioni `import` senza eseguire il codice. +* **Generazione `requirements.txt` Dettagliata:** + * Include la versione Python dell'ambiente di analisi. + * Elenca i moduli standard utilizzati con i file sorgente di riferimento. + * Elenca le dipendenze esterne con: + * Nome pacchetto PyPI corretto (es. `Pillow` da `import PIL`). + * Versione rilevata nell'ambiente di analisi (se disponibile). + * File sorgente in cui è stato trovato l'import. +* **Download Pacchetti Offline:** Scarica le dipendenze esterne e le loro dipendenze nella sottocartella `_req_packages`. +* **Script di Installazione:** Genera `install_packages.bat`/`.sh` in `_req_packages` per una facile installazione offline su altre macchine (con controllo `pip` integrato e percorsi relativi). +* **Confronto Ambiente:** Mostra una tabella che confronta le dipendenze richieste con i pacchetti attualmente installati. +* **Aggiornamento Ambiente (Opzionale):** Permette di installare/aggiornare pacchetti selezionati direttamente nell'ambiente corrente (**Usare con cautela, preferibilmente in ambienti virtuali!**). +* **Logging in Tempo Reale:** Visualizza i log delle operazioni direttamente nell'interfaccia grafica. + +### Prerequisiti + +* **Python 3:** Raccomandato Python 3.7+ +* **Pip:** Deve essere installato e accessibile. +* **(Opzionale ma Consigliato):** `pip install packaging` (per un confronto delle versioni più accurato). + +### Installazione / Setup + +1. Clona o scarica questo repository. +2. Assicurati che la struttura sia: + ``` + / + └── dependencyanalyzer/ + ├── __init__.py + ├── __main__.py + ├── core.py + └── gui.py + ``` +3. Non è richiesta un'installazione separata tramite `pip` per lo strumento stesso, viene eseguito come modulo. + +### Utilizzo + +1. Apri un terminale o prompt dei comandi. +2. Naviga (**`cd`**) nella cartella che **contiene** la directory `dependencyanalyzer`. +3. Esegui lo strumento usando il flag `-m` di Python: + ```bash + python -m dependencyanalyzer + ``` + *(Se hai rinominato la cartella `dependencyanalyzer`, usa quel nome nel comando).* +4. L'interfaccia grafica apparirà. Segui i passaggi numerati: + * **1. Select Repository Folder:** Scegli la cartella del progetto Python da analizzare. + * **2. Analyze Project & Generate requirements.txt:** Avvia l'analisi e la creazione del file. + * **3. External Dependencies Found:** Visualizza le dipendenze esterne trovate. + * **4. Download / Create Installers:** Scarica i pacchetti o genera gli script per l'offline. + * **5. System Package Comparison:** Confronta con l'ambiente locale ed eventualmente aggiorna (con cautela). + * **Log Messages:** Monitora l'output e i progressi. + +### Come Funziona (Breve Panoramica Tecnica) + +* Utilizza il modulo `ast` per creare un Abstract Syntax Tree del codice Python e trovare nodi `Import` e `ImportFrom`. +* Usa `sysconfig`, `importlib.util.find_spec` e una lista predefinita per distinguere i moduli standard da quelli esterni. +* Applica una mappatura (es. `PIL` -> `Pillow`) per usare i nomi corretti dei pacchetti PyPI. +* Utilizza `importlib.metadata.version` per rilevare le versioni installate. +* Invoca `pip` tramite `subprocess` per le operazioni di download, elenco e aggiornamento. +* Usa `tkinter.ttk` per la GUI e `logging` per mostrare i messaggi nell'interfaccia. + +### Limitazioni Note + +* Non rileva import dinamici (`importlib.import_module`). +* Non gestisce dipendenze non-Python. +* L'identificazione dei moduli interni si basa su convenzioni di base e potrebbe non essere perfetta per strutture di progetto molto complesse. +* Le versioni nel `requirements.txt` riflettono l'ambiente di analisi; non risolve attivamente i vincoli da `setup.py` o `pyproject.toml` durante la generazione iniziale. + +--- + +## Dependency Analyzer (English) + +### Introduction + +`Dependency Analyzer` is a desktop application (with a GUI built using Tkinter) that simplifies dependency management for Python projects. It statically analyzes source code to identify imported modules, distinguishing between standard libraries and external packages. + +The goal is to provide an easy way to: + +1. Get a clear list of a project's external dependencies. +2. Generate a detailed and informative `requirements.txt` file. +3. Prepare packages for offline distribution. +4. Compare required dependencies against the current development environment. + +### Key Features + +* **Simple Graphical Interface:** Based on Tkinter for intuitive use. +* **Flexible Folder Selection:** Analyzes the entire selected folder or a specific subfolder if it follows the `projectname_lowercase/` convention. +* **Static Analysis (AST):** Examines `.py` files to find `import` statements without executing code. +* **Detailed `requirements.txt` Generation:** + * Includes the Python version of the analysis environment. + * Lists used standard library modules with referencing source files. + * Lists external dependencies with: + * Correct PyPI package name (e.g., `Pillow` from `import PIL`). + * Detected version in the analysis environment (if available). + * Source files where the import was found. +* **Offline Package Download:** Downloads external dependencies and their dependencies into the `_req_packages` subfolder. +* **Installation Script Generation:** Creates `install_packages.bat`/`.sh` in `_req_packages` for easy offline installation on other machines (with built-in `pip` check and relative paths). +* **Environment Comparison:** Shows a table comparing required dependencies against currently installed packages. +* **Environment Update (Optional):** Allows installing/updating selected packages directly in the current environment (**Use with caution, preferably in virtual environments!**). +* **Real-time Logging:** Displays operation logs directly in the GUI. + +### Prerequisites + +* **Python 3:** Python 3.7+ recommended. +* **Pip:** Must be installed and accessible. +* **(Optional but Recommended):** `pip install packaging` (for more accurate version comparison). + +### Installation / Setup + +1. Clone or download this repository. +2. Ensure the structure is: + ``` + / + └── dependencyanalyzer/ + ├── __init__.py + ├── __main__.py + ├── core.py + └── gui.py + ``` +3. No separate `pip install` for the tool itself is required; it runs as a module. + +### Usage + +1. Open a terminal or command prompt. +2. Navigate (**`cd`**) to the directory **containing** the `dependencyanalyzer` directory. +3. Run the tool using Python's `-m` flag: + ```bash + python -m dependencyanalyzer + ``` + *(If you renamed the `dependencyanalyzer` folder, use that name in the command).* +4. The GUI will appear. Follow the numbered steps: + * **1. Select Repository Folder:** Choose the Python project folder to analyze. + * **2. Analyze Project & Generate requirements.txt:** Start the analysis and file creation. + * **3. External Dependencies Found:** View the detected external dependencies. + * **4. Download / Create Installers:** Download packages or generate scripts for offline use. + * **5. System Package Comparison:** Compare with the local environment and optionally update (carefully). + * **Log Messages:** Monitor output and progress. + +### How it Works (Brief Technical Overview) + +* Uses the `ast` module to build an Abstract Syntax Tree of Python code and find `Import` and `ImportFrom` nodes. +* Uses `sysconfig`, `importlib.util.find_spec`, and a predefined list to distinguish standard modules from external ones. +* Applies mappings (e.g., `PIL` -> `Pillow`) to use correct PyPI package names. +* Uses `importlib.metadata.version` to detect installed versions. +* Invokes `pip` via `subprocess` for download, list, and update operations. +* Uses `tkinter.ttk` for the GUI and the `logging` module to display messages in the interface. + +### Known Limitations + +* Does not detect dynamic imports (`importlib.import_module`). +* Does not handle non-Python dependencies. +* Internal module identification relies on basic conventions and might not be perfect for highly complex project structures. +* Versions in `requirements.txt` reflect the analysis environment; it doesn't actively resolve constraints from `setup.py` or `pyproject.toml` during initial generation. diff --git a/doc/English-Manual.md b/doc/English-Manual.md new file mode 100644 index 0000000..a4b56d5 --- /dev/null +++ b/doc/English-Manual.md @@ -0,0 +1,97 @@ +### **ENGLISH** + +#### 1. Introduction + +Dependency Analyzer is a Graphical User Interface (GUI) tool designed to assist Python developers in managing their project dependencies. It simplifies the process of identifying external libraries required by a project, generating a `requirements.txt` file, downloading packages for offline distribution, and comparing required dependencies against those installed in the current environment. + +The tool analyzes Python source code within a specified folder to find import statements and distinguishes between Python standard library modules and external packages. + +#### 2. Key Features + +* **Project Folder Selection:** Easily choose the main folder of the Python project to analyze. +* **Flexible Scanning:** Automatically detects whether to scan a specific subfolder (convention `projectname_lowercase/`) or the entire selected folder. +* **Dependency Identification:** Recursively analyzes `.py` files to find all imported modules. +* **Standard/External Distinction:** Classifies imports as belonging to the Python standard library or as external (third-party) dependencies. +* **`requirements.txt` Generation:** Creates a detailed `requirements.txt` file in the project root, including: + * Python version of the analysis environment. + * List of used standard library modules, indicating the source files where they are imported. + * List of external dependencies (using the correct PyPI package name, e.g., `Pillow` for `import PIL`), the version detected in the analysis environment, and the source files where they are imported. +* **Dependency Visualization:** Displays a clear list of identified external dependencies in the GUI. +* **Offline Download:** Downloads external packages specified in `requirements.txt` (and their dependencies) into a `_req_packages` subfolder for offline installation. Also copies `requirements.txt` into this folder. +* **Installation Script Creation:** Generates `install_packages.bat` (Windows) and `install_packages.sh` (Linux/macOS) scripts inside `_req_packages` to facilitate installing the downloaded packages on another machine. The scripts include a check for `pip` availability. +* **Environment Comparison:** Compares the packages listed in `requirements.txt` with those currently installed in the Python environment where the tool is running, showing the status (OK, Mismatch, Not installed). +* **Environment Update:** Allows selecting packages that are not installed or have mismatching versions from the comparison table and attempts to install/update them in the current environment using `pip install --upgrade`, respecting the specifications in `requirements.txt`. +* **Detailed Logging:** Provides real-time log messages both in the console and in the "Log Messages" area of the GUI to track operations. + +#### 3. Prerequisites + +* **Python:** Python 3 must be installed (Python 3.7+ recommended for better compatibility with internally used libraries like `importlib.metadata`). +* **Pip:** The `pip` tool must be installed and accessible from the terminal (usually included with modern Python installations). It's used for downloading, comparing, and updating packages. +* **(Optional) `packaging` Library:** For more accurate version comparison and better handling of version specifiers (e.g., `>=1.0, <2.0`) in `requirements.txt`, installing the `packaging` library is recommended: + ```bash + pip install packaging + ``` + The tool will function without it, but version comparison will be more basic. + +#### 4. Installation/Setup + +Dependency Analyzer is provided as a Python package. To use it: + +1. Ensure you have the source files (`__init__.py`, `__main__.py`, `gui.py`, `core.py`). +2. Create a folder named `dependencyanalyzer` (or your preferred name, but ensure it's a valid Python identifier). +3. Place the four source files inside the `dependencyanalyzer` folder. +4. Place this `dependencyanalyzer` folder in a location accessible by your Python PATH, or directly inside the *parent* directory of the project you intend to launch with `python -m`. For example: + ``` + My_Projects/ + ├── dependencyanalyzer/ <-- Tool's folder + │ ├── __init__.py + │ ├── __main__.py + │ ├── gui.py + │ └── core.py + └── MyProjectToAnalyze/ + ├── myproject/ + │ └── ... + └── README.md + ``` + +#### 5. Running the Tool + +1. Open your terminal or command prompt. +2. Navigate to the *parent* folder containing the `dependencyanalyzer` folder (in the example above, `My_Projects/`). +3. Run the command: + ```bash + python -m dependencyanalyzer + ``` + (Replace `dependencyanalyzer` with the actual folder name if you renamed it). +4. The tool's GUI should appear. + +#### 6. Using the Graphical Interface + +The interface is divided into numbered sections guiding the user through the workflow: + +1. **Repository Operations:** + * Click the **"Select Repository Folder"** button. + * Choose the main folder of the Python project you want to analyze. + * The selected path will appear in the label to the right. The log will show the selection. + +2. **Analysis & Requirements:** + * Once a folder is selected, the **"Analyze Project & Generate requirements.txt"** button becomes active. + * Click it to start the analysis. The tool will: + * Determine whether to scan the entire folder or a specific subfolder (e.g., `foldername_lowercase/`). + * Recursively scan `.py` files in the target folder. + * Identify standard and external imports. + * Attempt to detect the installed version of external dependencies. + * Generate the `requirements.txt` file in the root of the folder selected in step 1. + * Log messages will show the progress. + +3. **External Dependencies Found:** + * This table (`Treeview`) will be populated with the names of the **external packages** (PyPI names) found during the analysis and written to `requirements.txt`. + +4. **Download Packages & Create Installers:** + * **"Download Packages to \_req\_packages":** If `requirements.txt` has been generated and contains external dependencies, this button becomes active. Clicking it will: + * Create (if needed) a `_req_packages` folder in the project root. + * Attempt to download each package specified in `requirements.txt` (and their dependencies) into this folder. It will also copy `requirements.txt` itself into this folder. + * The log will show progress, indicating which package it's trying to download and the outcome. + * **"Create install\_packages.bat/sh":** If `requirements.txt` exists, this button becomes active. Clicking it will: + * Copy the latest `requirements.txt` to `_req_packages` (if not already present). + * Create `install_packages.bat` and `install \ No newline at end of file diff --git a/doc/Italian-Manual.md b/doc/Italian-Manual.md new file mode 100644 index 0000000..5d011a6 --- /dev/null +++ b/doc/Italian-Manual.md @@ -0,0 +1,189 @@ +--- + +## 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. + +--- +