add manual and readme
This commit is contained in:
VALLONGOL
parent
26d37fbd72
commit
20e1ea2464
179
README.md
Normal file
179
README.md
Normal file
@ -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:
|
||||||
|
```
|
||||||
|
<qualche_cartella>/
|
||||||
|
└── 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:
|
||||||
|
```
|
||||||
|
<some_folder>/
|
||||||
|
└── 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.
|
||||||
97
doc/English-Manual.md
Normal file
97
doc/English-Manual.md
Normal file
@ -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
|
||||||
189
doc/Italian-Manual.md
Normal file
189
doc/Italian-Manual.md
Normal file
@ -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.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
Loading…
Reference in New Issue
Block a user