SXXXXXXX_DependencyAnalyzer/doc/English-Manual.md

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:

  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:

   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